API REST: no es solo mandar JSON, es cómo se manda

Explicación

Un estilo, no un estándar

REST (Representational State Transfer) lo definió Roy Fielding en su tesis doctoral del año 2000. No es un protocolo ni un estándar: es un conjunto de restricciones de arquitectura que se apoya en estándares que sí existen, como HTTP, las URIs y los media types.

Por eso una API no es REST por usar JSON sobre HTTP, sino por respetar esas restricciones.

Las seis restricciones

Un matiz que vale la pena decir: stateless no significa sin base de datos. El servidor sí guarda el estado de los recursos (los pedidos, los usuarios). Lo que no guarda es el estado de la conversación con cada cliente.

Recursos, no acciones

La URL nombra una cosa y el verbo HTTP dice qué hacer con ella: GET /orders/42, no POST /getOrder. Las colecciones van en plural (/orders) y las relaciones se anidan (/orders/42/items).

Lo que viaja no es el recurso en sí, sino una representación suya, normalmente JSON. El header Content-Type indica el formato, así que el mismo recurso podría servirse en otro formato sin cambiar su URL.

Verbos y códigos de estado

Seguro significa que no cambia nada en el servidor. Idempotente, que repetir la request deja el mismo resultado que hacerla una vez. Esto importa en los reintentos: repetir un DELETE no rompe nada, pero repetir un POST puede crear dos pedidos.

La respuesta siempre dice qué pasó con su código de estado: 2xx es éxito, 4xx es un error del cliente y 5xx es un error del servidor. Los que más espero ver en una API:

• 200 OK, 201 Created (con el header Location del recurso nuevo) y 204 No Content.
• 400 Bad Request, 404 Not Found y 409 Conflict.
• 401 Unauthorized (no sé quién eres) frente a 403 Forbidden (sé quién eres, pero no tienes permiso).
• 500 Internal Server Error.

Código

El mismo recurso de pedidos, primero como RPC disfrazado de REST y después respetando las reglas. Fíjate en las URLs, los verbos y los códigos de estado.

### Crear un pedido
POST /createOrder HTTP/1.1
Content-Type: application/json

{ "productId": 7, "quantity": 2 }

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true, "orderId": 42 }

### Consultar un pedido que no existe
POST /getOrder HTTP/1.1
Content-Type: application/json

{ "orderId": 99 }

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": false, "error": "Order not found" }

### Crear un pedido
POST /orders HTTP/1.1
Content-Type: application/json

{ "productId": 7, "quantity": 2 }

HTTP/1.1 201 Created
Location: /orders/42

### Leer un pedido
GET /orders/42 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60
ETag: "a1b2c3"

{ "id": 42, "productId": 7, "quantity": 2, "status": "pending" }

### Eliminar un pedido
DELETE /orders/42 HTTP/1.1

HTTP/1.1 204 No Content

### Leer un pedido que no existe
GET /orders/99 HTTP/1.1

HTTP/1.1 404 Not Found

Trade-offs

• Simplicidad frente a flexibilidad. REST usa HTTP tal cual, así que funciona con cualquier cliente y aprovecha la caché y la infraestructura que ya existen. A cambio, la forma de la respuesta la decide el servidor, lo que puede traer datos de más o de menos y obligar a varias llamadas. Para esos casos existen alternativas como GraphQL o gRPC, cada una con sus propios costos.
• Stateless escala, pero cada request carga su contexto. El token viaja y se valida en cada llamada, y eso tiene un costo en tamaño y en procesamiento.
• La caché acelera, pero hay que invalidarla. Si Cache-Control y ETag no están bien pensados, el cliente puede ver datos obsoletos.
• El error típico: RPC disfrazado de REST. Verbos en la URL, todo por POST y 200 con el error en el cuerpo. Funciona, pero pierde la caché, la idempotencia y los códigos de estado que cualquier cliente o proxy sabe interpretar.
• Dato adicional: HATEOAS. Es la restricción que casi nadie cumple: que la respuesta incluya enlaces a las acciones posibles, para que el cliente navegue la API sin conocer las URLs de antemano.