APIs y contratos

En los sistemas de software modernos, las aplicaciones rara vez interactúan directamente con la lógica del backend. En su lugar, se comunican a través de APIs, que actúan como puntos de entrada controlados al sistema.

Un cliente — como un navegador, una aplicación móvil u otro servicio backend — envía una solicitud a un endpoint específico de la API. La API recibe esa solicitud, interpreta la información que contiene y la reenvía a la lógica backend adecuada. Luego, el backend realiza el trabajo necesario, como recuperar datos de una base de datos o ejecutar reglas de la aplicación, antes de devolver una respuesta al cliente.

Esta comunicación estructurada permite que los sistemas sigan siendo modulares. Las aplicaciones frontend, las apps móviles y los servicios externos pueden interactuar con la misma funcionalidad backend siempre que sigan el formato de solicitud y respuesta definido por la API.

Como las APIs definen cómo deben estructurarse las solicitudes y cómo serán las respuestas, crean una interfaz predecible entre distintas partes de un sistema. Esta interfaz permite que componentes desarrollados de forma independiente se comuniquen de manera fiable sin necesidad de saber cómo funciona la implementación interna del backend.

Cuando un cliente envía una solicitud a un endpoint de API, debe especificar qué tipo de operación quiere realizar. Esta operación se expresa usando un método HTTP.

El método HTTP funciona junto con la URL del endpoint para definir el significado de la solicitud.

Por ejemplo, una solicitud como GET /users le pide al servidor que recupere datos de usuarios. Una solicitud como POST /users le pide al servidor que cree un nuevo usuario. Una solicitud como DELETE /users/42 indica al backend que elimine un usuario específico.

En las APIs se usan comúnmente varios métodos HTTP.

GET recupera datos existentes del servidor.
POST crea nuevos recursos.
PUT reemplaza un recurso existente con nuevos datos.
PATCH actualiza una parte de un recurso existente.
DELETE elimina un recurso del sistema.

Al combinar endpoints con métodos HTTP, las APIs definen claramente las operaciones que los clientes pueden realizar sobre los recursos del sistema.

En el diseño de APIs, un enfoque es estructurar los endpoints alrededor de acciones, donde cada URL describe lo que el sistema debe hacer. Por ejemplo, un endpoint como POST /createUser codifica directamente la acción en la URL.

Este enfoque funciona para sistemas pequeños, pero se vuelve difícil de mantener a medida que crece el número de funcionalidades. Los endpoints se vuelven inconsistentes y resulta más difícil predecir cómo se expondrán las nuevas funciones.

REST adopta un enfoque diferente al organizar las APIs alrededor de recursos como usuarios, pedidos o productos. En lugar de codificar acciones en la URL, el endpoint representa el recurso y el método HTTP define la operación.

Por ejemplo, POST /users crea un nuevo usuario, mientras que GET /users recupera usuarios. Esta separación conduce a un patrón consistente en toda la API.

Gracias a esta estructura, las APIs RESTful son más fáciles de entender, escalar y ampliar. Los desarrolladores pueden interactuar con nuevos endpoints más fácilmente, ya que siguen el mismo diseño predecible.

REST se basa en un conjunto de principios de diseño que ayudan a que las APIs se mantengan consistentes y confiables a medida que los sistemas crecen.

Un principio clave es la comunicación sin estado. Cada solicitud debe contener toda la información necesaria para que el servidor la procese. El servidor no depende de solicitudes anteriores, lo que hace que el sistema sea más fácil de escalar y distribuir.

Otro principio es el diseño basado en recursos. Las APIs representan entidades como usuarios o pedidos como recursos, y estos recursos se identifican usando URLs como /users o /orders.

REST también se basa en la semántica estándar de HTTP. Métodos HTTP como GET, POST, PUT, PATCH y DELETE se usan para expresar claramente la operación que se está realizando sobre un recurso.

Por último, REST impone una interfaz uniforme. Los endpoints siguen patrones consistentes, lo que hace que las APIs sean más fáciles de entender y reduce la confusión al interactuar con diferentes partes de un sistema.

Cuando un servidor procesa una solicitud, debe comunicar el resultado al cliente. Los códigos de estado HTTP proporcionan una forma estandarizada de describir ese resultado.

Los códigos de estado se agrupan en categorías. Los códigos en el rango 2xx indican éxito, lo que significa que la solicitud se procesó correctamente. Los códigos en el rango 4xx indican errores del cliente, como entrada no válida o recursos faltantes. Los códigos en el rango 5xx indican errores del servidor, lo que significa que algo salió mal en el backend.

Entre los ejemplos comunes se incluyen 200 OK, que indica una solicitud exitosa, y 201 Created, que confirma que se creó un nuevo recurso. Errores como 400 Bad Request indican entrada no válida, mientras que 401 Unauthorized señala autenticación faltante o inválida. Una respuesta 404 Not Found significa que el recurso solicitado no existe, y 500 Internal Server Error indica un fallo en el servidor.

Los clientes usan estos códigos de estado para determinar cómo continuar. Por ejemplo, un cliente puede reintentar una solicitud después de un error del servidor o pedirle al usuario que corrija la entrada después de un error del cliente.

En sistemas distribuidos, las solicitudes pueden fallar, agotarse por tiempo de espera o reintentarse varias veces. Por eso, los sistemas backend deben diseñarse para manejar solicitudes repetidas de forma segura.

Una operación se considera idempotente si enviar la misma solicitud varias veces da como resultado el mismo estado final. Por ejemplo, llamar a DELETE /users/10 una vez elimina al usuario. Volver a llamarla no cambia nada más porque el usuario ya fue eliminado.

De manera similar, PUT /users/10 reemplaza el recurso con los mismos datos cada vez, así que repetir la solicitud no crea efectos secundarios adicionales.

En cambio, POST /orders normalmente no es idempotente porque cada solicitud crea un nuevo pedido. Repetir la misma solicitud puede dar lugar a recursos duplicados.

La idempotencia es importante porque los sistemas suelen reintentar solicitudes automáticamente cuando ocurren fallos. Sin idempotencia, los reintentos podrían provocar datos inconsistentes, operaciones duplicadas o efectos secundarios no deseados.

A medida que los sistemas backend evolucionan, las APIs a menudo necesitan cambiar. Se pueden agregar nuevas funciones, actualizar formatos de datos o modificar el comportamiento existente.

El problema es que los clientes, como aplicaciones web, aplicaciones móviles o integraciones de terceros, dependen del comportamiento existente de la API. Si la API cambia sin aviso, esos clientes pueden dejar de funcionar.

El versionado de API resuelve esto permitiendo que existan varias versiones de una API al mismo tiempo. Los clientes antiguos pueden seguir usando la versión original, mientras que los clientes nuevos pueden adoptar versiones actualizadas.

Un enfoque común es el versionado por URL, donde la versión se incluye en la ruta, como /v1/users y /v2/users. Otro enfoque es el versionado por encabezado, donde el cliente especifica la versión usando un encabezado como Accept: application/vnd.api.v2.

Al versionar las APIs, los sistemas backend pueden evolucionar de forma segura mientras mantienen la compatibilidad con los clientes existentes.

Un contrato de API actúa como un acuerdo entre el cliente y el sistema backend. Define exactamente cómo debe ocurrir la comunicación para que ambas partes puedan interactuar sin ambigüedad.

Cuando un cliente envía una solicitud HTTP, debe seguir el contrato usando el endpoint correcto, proporcionando el formato de datos esperado e incluyendo toda la información requerida. El sistema backend procesa la solicitud según estas reglas y devuelve una respuesta HTTP estructurada.

El contrato define varios aspectos críticos de la API, incluidos los endpoints disponibles, el formato de los datos de solicitud, la estructura de las respuestas, el significado de los códigos de estado y el comportamiento esperado de cada operación.

Gracias a este contrato, los clientes no necesitan entender cómo está implementado internamente el backend. Mientras sigan la interfaz definida, la comunicación se mantiene consistente y confiable.

En la práctica, los contratos de API son esenciales para la colaboración entre los equipos de frontend y backend, así como para las integraciones entre sistemas independientes.