Busca en todas las páginas de la documentación
Una API es un contrato: una promesa sobre qué solicitudes aceptará un servicio y qué formas de respuestas devolverá, hecha a los llamadores que no pueden ver —y no deberían necesitar ver— nada sobre la implementación detrás de ella. Diseñar una API bien significa diseñar esa promesa deliberadamente, antes del código, en lugar de dejar que surja con la forma que un manejador de rutas produjo.
Esta página es el modelo mental detrás del resto de la sección. Conceptos básicos del diseño de API muestra los patrones de trabajo —URL de recursos, envoltorios JSON, códigos de estado— y Estándares de respuesta de error, Paginación y filtrado, Versionado y deprecación, y OpenAPI y Swagger profundizan en partes específicas de ese contrato. Aquí, el objetivo es comprender qué hace que algo sea un buen contrato, no solo un endpoint funcional.
La palabra "diseño" en diseño de API está haciendo un trabajo real: un recurso es el sustantivo que expone una API —un pedido, un cliente, una factura— y los métodos HTTP (GET, POST, PATCH, DELETE) son los verbos que se le aplican.
Esa forma orientada a recursos no es una elección estética; es lo que permite a un llamador que nunca ha leído tu código fuente adivinar correctamente que DELETE /orders/:id elimina un pedido, sin una línea de documentación.
Una alternativa de estilo RPC —POST /deleteOrder— también funciona, pero obliga a que cada acción se aprenda individualmente, porque la URL ya no lleva ningún significado por sí misma.
Una analogía útil: una API bien diseñada es una máquina expendedora, no una conversación.
Un llamador no necesita explicar lo que quiere en prosa o adivinar el estado interno: presiona un botón bien etiquetado (una URL de recurso más un método) y obtiene un resultado predecible y documentado cada vez, independientemente de lo que esté sucediendo dentro de la máquina.
GET /v1/orders/:id # obtener un pedido
POST /v1/orders # crear un pedido
PATCH /v1/orders/:id # actualizar parcialmente un pedido
DELETE /v1/orders/:id # eliminar un pedidoLa idempotencia es la propiedad de que llamar a una operación dos veces tiene el mismo efecto que llamarla una vez —se espera que PUT y DELETE sean idempotentes según la propia semántica de HTTP, mientras que POST generalmente no lo es, por lo que los endpoints de pago a menudo agregan un encabezado Idempotency-Key explícito para obtener esa garantía donde el método HTTP por sí solo no la proporciona.
Una vez que una API se lanza y un llamador escribe código contra ella, la forma de la respuesta se convierte en una infraestructura de soporte que el propietario de la API ya no controla por completo: una aplicación móvil en el bolsillo de un usuario, o la integración de un socio, sigue llamando a la forma antigua hasta que alguien actualiza ese código, lo cual el equipo de la API no puede forzar ni siempre ver que sucede.
Esta es la tensión central en el diseño de API: internamente, la refactorización es barata porque cada llamador es un compañero de trabajo que puede actualizar en la misma solicitud de extracción; externamente, una "refactorización" de una forma de respuesta es un cambio disruptivo que se lanza en su propio cronograma, invisible para el equipo que lo hizo hasta que llegan los tickets de soporte.
Los códigos de estado tienen un significado independiente del cuerpo de la respuesta, lo que los hace útiles para la ramificación programática antes de que un cliente incluso analice JSON.
// El código de estado es lo primero en lo que un cliente se ramifica, antes del análisis del cuerpo
if (response.status === 404) {
// el llamador puede reaccionar a "no encontrado" sin leer response.body en absoluto
} else if (response.status >= 500) {
// es seguro reintentar; 4xx generalmente no lo es
}Esa distinción entre 4xx y 5xx es un mecanismo, no una convención: los clientes HTTP, los proxies y las bibliotecas de reintento tratan los dos rangos de manera diferente por defecto (los 5xx a menudo se reintentan automáticamente; los 4xx generalmente no), por lo que devolver 500 para un error de validación le dice a la infraestructura intermedia que reintente una solicitud que fallará idénticamente cada vez.
Un envoltorio consistente —envolver las cargas útiles de éxito en { data: ... } y los errores en { error: ... }— existe por una razón relacionada: permite a un cliente escribir una única pieza de lógica de manejo de respuestas para cada endpoint en la API, en lugar de un caso especial por ruta. Sin esa consistencia, cada nuevo endpoint es un pequeño proyecto de integración para cada consumidor, porque nada de los diecinueve endpoints anteriores predice la forma del vigésimo.
La estabilidad del contrato tiene un costo genuino, y comprender ese costo es lo que separa el diseño deliberado de API de la precaución excesiva o la imprudencia. Un campo que en realidad no es utilizado por ningún llamador puede eliminarse libremente; un campo del que una integración depende silenciosamente no puede, incluso si parece no utilizado desde dentro de la base de código, por lo que las API de producción instrumentan cada vez más el uso de la respuesta (qué campos leen realmente los clientes) antes de eliminar cualquier cosa.
El versionado existe para permitir que un contrato evolucione sin romper a los llamadores existentes: una nueva versión principal (/v2/orders) puede cambiar las formas de respuesta libremente, mientras que /v1 sigue sirviendo exactamente lo que siempre ha hecho hasta que se deprecia formalmente en un cronograma publicado. La alternativa —mutar /v1 en su lugar— intercambia un esquema de URL limpio por un contrato impredecible, lo cual es un peor intercambio para cualquier API con llamadores fuera del control directo del equipo.
| Enfoque | Fortaleza | Debilidad | Mejor ajuste |
|---|---|---|---|
| REST, orientado a recursos | Predecible, cacheable, ampliamente utilizado (OpenAPI, clientes generados) | Verboso para acciones puras que no son realmente CRUD | API públicas y B2B, dominios con mucho CRUD |
Estilo RPC (/doThing) | Fácil de agregar acciones únicas | No hay vocabulario compartido entre endpoints; más difícil de documentar genéricamente | Endpoints internos con muchas acciones, operaciones de estilo comando |
| GraphQL | Los clientes obtienen exactamente los campos que necesitan; un solo endpoint | El almacenamiento en caché y la limitación de velocidad son más difíciles; configuración del lado del servidor más compleja | Interfaces de usuario con muchos datos y muchas formas de cliente desde un solo backend |
El manejo de errores merece la misma disciplina contractual que las respuestas de éxito, y a menudo recibe menos en la práctica. Un campo code estable y legible por máquina (ORDER_NOT_FOUND) permite a los clientes ramificarse por significado; una cadena message legible por humanos no lo hace, porque esa cadena puede cambiar con una edición de texto y romper silenciosamente cualquier cliente que estuviera haciendo coincidir patrones con su texto exacto. Estándares de respuesta de error cubre la forma de RFC 9457 Problem Details que esta pila estandariza, pero el principio subyacente se aplica independientemente del formato: cualquier cosa en la que se espere que un cliente se ramifique programáticamente debe ser tan estable como el propio contrato.
Las herramientas modernas han trasladado parte de esta disciplina de la convención a la aplicación. Una especificación OpenAPI, generada a partir de código o escrita a mano y validada en CI, convierte "el contrato es lo que dicen los documentos" en "el contrato es lo que una máquina puede verificar una respuesta" —detectando la desviación entre la documentación y la implementación antes de que un llamador note la discrepancia.
POST /orders/:id/cancel trata "cancelar" como una acción sobre un recurso en lugar de abandonar por completo el diseño orientado a recursos.Los llamadores externos al equipo —aplicaciones móviles, integraciones de socios, otros servicios— escriben código basándose en las formas de respuesta y los códigos de estado exactos que devuelve una API, y no pueden ver ni influir en cómo se produjo esa respuesta internamente.
Le da a cada endpoint un vocabulario compartido y predecible: un llamador que entiende GET /orders/:id puede predecir correctamente lo que hace GET /customers/:id, sin documentación, porque el patrón se repite.
Los clientes HTTP, los proxies y las bibliotecas de reintento se ramifican en el rango del código de estado antes incluso de analizar el cuerpo de la respuesta; muchos reintentan automáticamente las respuestas 5xx y no reintentan las 4xx, por lo que el código que devuelves determina el comportamiento real de la infraestructura, no solo la semántica.
Permite a un cliente escribir una pieza de código compartida para verificar data versus error en cada endpoint, en lugar de escribir lógica de análisis personalizada por ruta porque la forma de cada endpoint es ligeramente diferente.
Generalmente solo al agregar un nuevo campo opcional que ningún cliente existente lee todavía; eliminar un campo, renombrarlo o cambiar el tipo o significado de un campo es un cambio disruptivo, sin importar cuán pequeño parezca en la diferencia.
El texto del mensaje está destinado a humanos y puede cambiar con una edición de texto en cualquier momento; un campo code estable y legible por máquina es la parte del contrato destinada a ser dependiente programáticamente.
No, REST se adapta bien a escenarios con mucho CRUD, cacheables y con muchas herramientas, mientras que GraphQL se adapta a interfaces de usuario con muchos datos que necesitan muchas combinaciones de campos diferentes de un solo backend; la elección depende de la diversidad de la forma del llamador y las necesidades de almacenamiento en caché, no de que uno sea universalmente mejor.
Cada inconsistencia (una forma de envoltorio diferente, un código de estado impredecible) se convierte en trabajo de integración que cada llamador tiene que rehacer por endpoint, y cada "pequeño" cambio disruptivo se convierte en un incidente de soporte para quien dependía de la forma antigua.
POST no es idempotente según la propia semántica de HTTP, por lo que una solicitud reintentada (por una red inestable, por ejemplo) puede crear un recurso duplicado a menos que la API agregue un mecanismo explícito, como un encabezado Idempotency-Key, para hacer que los reintentos sean seguros.
Convierte el contrato de una descripción en un documento a un esquema verificable por máquina: una respuesta validada por la especificación coincide con lo prometido o falla una verificación, detectando automáticamente la desviación entre la documentación y el comportamiento real.
Incluso los equipos disciplinados eventualmente necesitan un cambio que genuinamente no puede mantener la compatibilidad con versiones anteriores; el versionado les da a los llamadores existentes un objetivo estable (/v1) para seguir usando mientras los nuevos llamadores adoptan la nueva forma (/v2), en lugar de forzar a todos a un cambio disruptivo a la vez.
Versiones de la pila: Esta página es conceptual y no está vinculada a una versión específica de la pila.
Revisado por Chris St. John·Última actualización: 15 jul 2026