APIs
Buenas prácticas para diseñar APIs REST: guía actualizada
Guía actualizada de buenas prácticas para APIs REST: recursos, métodos y códigos HTTP, errores con RFC 9457, paginación, versionado, idempotencia, seguridad y OpenAPI.

Una API es una interfaz que otras personas van a usar durante años, con código que tú no controlas. Por eso sus errores de diseño son caros: una vez que hay clientes en producción, cada decisión se vuelve difícil de cambiar. Esta guía reúne las prácticas que hoy se consideran estándar para diseñar APIs REST sobre HTTP, con ejemplos concretos y la razón detrás de cada una.
Reúne y actualiza lo que se recomendaba hace unos años. Desde entonces cambiaron cosas importantes: las RFC de semántica HTTP se reescribieron (RFC 9110), hay un formato estándar de errores (RFC 9457), OpenAPI 3.1 es el estándar de descripción de contratos y la seguridad de las APIs tiene su propio ranking de riesgos en OWASP. Incluimos todo eso.
Está pensada para desarrolladores con experiencia media que ya construyeron al menos una API. Los ejemplos son independientes del lenguaje o framework.
Qué significa realmente “REST”
REST es un estilo de arquitectura, no un estándar. En la práctica, cuando se habla de “API REST” se espera lo siguiente:
- Recursos identificados por URL (
/orders/42), no funciones remotas. - Métodos HTTP con su semántica estándar para actuar sobre ellos.
- Sin estado en el servidor entre peticiones: cada petición lleva lo necesario (credenciales, parámetros) para procesarse. Eso permite escalar horizontalmente.
- Representaciones del recurso, normalmente JSON.
- Códigos de estado y cabeceras HTTP usados con su significado, no como adorno.
Muy pocas APIs cumplen la definición académica completa (incluye hipermedia o HATEOAS). Lo pragmático es seguir bien las convenciones anteriores y ser consistente. Una API predecible vale más que una pura.
Regla de oro: diseña desde la perspectiva de quien consume la API, no de cómo está organizada tu base de datos.
1. Diseña el contrato primero
Antes de escribir código, describe la API con OpenAPI 3.1 (YAML o JSON). El contrato es la fuente de verdad: de él salen la documentación, los mocks, los tests de contrato y los SDK de clientes. Revisarlo en un pull request es mucho más barato que corregir una API ya publicada.
openapi: 3.1.0
info:
title: API de pedidos
version: 1.0.0
servers:
- url: https://api.ejemplo.com/v1
paths:
/orders/{orderId}:
get:
summary: Obtiene un pedido
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
responses:
'200':
description: El pedido
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'404':
$ref: '#/components/responses/NotFound'
Complementa el contrato con un linter (por ejemplo, Spectral) en CI para aplicar las reglas de estilo de tu equipo, y con tests de contrato que verifiquen que la implementación cumple lo documentado.
2. Recursos y URLs
La URL identifica qué es el recurso. El método HTTP indica qué hacer con él.
| Evita | Prefiere | Por qué |
|---|---|---|
POST /createOrder |
POST /orders |
La acción ya la expresa el método |
GET /getOrders |
GET /orders |
Ídem |
GET /order/42 |
GET /orders/42 |
Colecciones en plural, siempre |
GET /Orders/42/ |
GET /orders/42 |
Minúsculas y sin barra final |
GET /customer_orders |
GET /customer-orders |
kebab-case en rutas; evita guion bajo |
GET /companies/3/employees/45/orders/9/items/2 |
GET /order-items/2?orderId=9 |
Evita anidar más de dos niveles |
Reglas prácticas:
- Sustantivos en plural para colecciones:
/orders,/customers. - Anidamiento solo cuando expresa pertenencia clara, y con un máximo de dos niveles:
GET /customers/7/orders. - Identificadores opacos. Usa UUID u otros IDs no secuenciales cuando exponer cuántos registros tienes o permitir adivinar IDs sea un riesgo. Nunca asumas que el cliente interpreta el ID.
- Sin extensiones ni detalles de implementación en la ruta (
.php,.json, nombres de tablas). El formato se negocia con la cabeceraAccept.
Acciones que no encajan en CRUD
A veces una operación no es crear, leer, actualizar o borrar. Hay dos salidas razonables, y conviene elegir una y mantenerla:
- Modelar la acción como un sub-recurso o un estado:
POST /orders/42/cancellation,PUT /users/7/password. - Usar un endpoint de acción cuando no hay un buen sustantivo:
POST /orders/42/actions/refund. Es un compromiso válido, siempre que sea la excepción.
3. Métodos HTTP
RFC 9110 define la semántica de cada método. Dos propiedades importan al diseñar:
- Seguro: no modifica el estado del servidor.
- Idempotente: repetir la misma petición varias veces deja el servidor en el mismo estado que hacerla una sola vez.
| Método | Uso | Seguro | Idempotente | Cuerpo de la petición |
|---|---|---|---|---|
GET |
Leer un recurso o una colección | Sí | Sí | No |
POST |
Crear un recurso o ejecutar una acción | No | No | Sí |
PUT |
Reemplazar un recurso completo | No | Sí | Sí |
PATCH |
Modificar parcialmente un recurso | No | No necesariamente | Sí |
DELETE |
Eliminar un recurso | No | Sí | Normalmente no |
HEAD |
Igual que GET pero solo cabeceras |
Sí | Sí | No |
OPTIONS |
Consultar métodos permitidos (y CORS) | Sí | Sí | No |
Puntos que suelen confundirse:
GETjamás debe cambiar datos. Los navegadores, rastreadores y proxies lo llaman libremente.PUTreemplaza, no “actualiza algunos campos”. Si el cliente omite un campo, se interpreta que ese campo ya no existe. Para cambios parciales usaPATCH.PATCHpuede usar JSON Merge Patch (RFC 7396,application/merge-patch+json), simple pero que no distingue biennull, o JSON Patch (RFC 6902), más expresivo. Define cuál admites.DELETEes idempotente aunque la segunda llamada devuelva404: el estado final es el mismo.- Crear con
POSTa la colección (POST /orders) es lo habitual: el servidor asigna el ID. ReservaPUT /orders/{id}para cuando el cliente elige el ID.
4. Códigos de estado HTTP
El código de estado es la primera parte de la respuesta que lee el cliente y la que usan los proxies, métricas y alertas. Úsalo bien y no devuelvas 200 con un error escondido en el cuerpo.
Éxito (2xx)
| Código | Cuándo |
|---|---|
200 OK |
Lectura o actualización correcta con cuerpo de respuesta |
201 Created |
Se creó un recurso. Incluye la cabecera Location con su URL y, idealmente, el recurso en el cuerpo |
202 Accepted |
Se aceptó la petición pero se procesa de forma asíncrona (ver sección de operaciones largas) |
204 No Content |
Éxito sin cuerpo: típico en DELETE y en PUT o PATCH que no devuelven el recurso |
Redirección y caché (3xx)
| Código | Cuándo |
|---|---|
304 Not Modified |
Petición condicional (If-None-Match): el cliente ya tiene la versión vigente |
301 / 308 |
El recurso cambió de URL de forma permanente (308 conserva el método) |
Error del cliente (4xx)
| Código | Cuándo |
|---|---|
400 Bad Request |
Petición mal formada: JSON inválido, parámetro con tipo equivocado |
401 Unauthorized |
No autenticado: faltan credenciales o son inválidas. Incluye WWW-Authenticate |
403 Forbidden |
Autenticado, pero sin permiso para esa acción |
404 Not Found |
El recurso no existe, o no quieres revelar que existe a quien no tiene acceso |
405 Method Not Allowed |
El método no está soportado en esa ruta. Incluye Allow |
409 Conflict |
Conflicto con el estado actual: duplicado, transición no válida |
410 Gone |
El recurso existió y se retiró de forma definitiva |
412 Precondition Failed |
Falló una condición If-Match (control de concurrencia) |
415 Unsupported Media Type |
El Content-Type enviado no está soportado |
422 Unprocessable Content |
Sintaxis correcta pero datos inválidos según las reglas de negocio o validación |
429 Too Many Requests |
Superó el límite de uso. Incluye Retry-After |
La diferencia entre 400 y 422 es útil pero opcional: lo importante es elegir una convención y aplicarla siempre. Mucha gente usa 400 para ambos casos y distingue el motivo en el cuerpo del error.
Y entre 401 y 403: 401 significa “no sé quién eres”, 403 significa “sé quién eres y no puedes”.
Error del servidor (5xx)
| Código | Cuándo |
|---|---|
500 Internal Server Error |
Fallo inesperado en el servidor. Nunca devuelvas la traza al cliente |
502 Bad Gateway / 504 Gateway Timeout |
Un servicio del que depende no respondió bien o a tiempo |
503 Service Unavailable |
Mantenimiento o sobrecarga. Incluye Retry-After si lo sabes |
5. Formato de las peticiones y respuestas
- JSON como formato por defecto, con
Content-Type: application/json. Valida elContent-Typey la cabeceraAcceptde la petición. - Un estilo de nombres para todos los campos:
camelCaseosnake_case, pero no ambos. Elige uno y documéntalo. - Fechas y horas en RFC 3339 / ISO 8601, en UTC:
"2026-11-17T14:30:00Z". Evita timestamps ambiguos o formatos locales. - Dinero: usa enteros en la unidad mínima (
"amount": 1999, "currency": "USD") o cadenas decimales. Los números de coma flotante producen errores de redondeo. - Enumerados como cadenas legibles (
"status": "shipped"), no como números mágicos. - Distingue
nullde campo ausente y documenta qué significa cada uno, sobre todo enPATCH. - Devuelve el recurso directamente en respuestas de un solo objeto. No lo envuelvas en
{ "data": ... }solo por costumbre. - Para colecciones, usa un objeto y no un arreglo suelto, porque permite añadir metadatos (paginación) sin romper a los clientes:
{
"items": [
{ "id": "ord_8f3a", "status": "shipped", "total": { "amount": 1999, "currency": "USD" } }
],
"page": { "nextCursor": "eyJpZCI6Im9yZF84ZjNhIn0", "limit": 25 }
}
6. Errores: usa Problem Details (RFC 9457)
Cada API suele inventar su formato de error. Hoy existe un estándar: Problem Details for HTTP APIs, RFC 9457 (que reemplaza a la RFC 7807). Se sirve con Content-Type: application/problem+json:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://api.ejemplo.com/errors/validation",
"title": "Datos inválidos",
"status": 422,
"detail": "Uno o más campos no cumplen las reglas de validación.",
"instance": "/v1/orders",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"errors": [
{ "field": "items[0].quantity", "message": "Debe ser mayor que 0" },
{ "field": "email", "message": "Formato de correo no válido" }
]
}
type: URI que identifica el tipo de problema (puede apuntar a documentación).title: resumen corto, igual para todos los errores del mismo tipo.status: el mismo código HTTP de la respuesta.detail: explicación de esta ocurrencia concreta.instance: identifica esta ocurrencia.- Extensiones propias (
errors,traceId) están permitidas.
Buenas prácticas con errores:
- Devuelve todos los errores de validación a la vez, no uno por intento.
- Mensajes útiles para el desarrollador y códigos estables para que el cliente los procese (
type), no solo texto. - No filtres información interna: nada de trazas de pila, consultas SQL ni nombres de servidores.
- Incluye un identificador de correlación (
traceId) que puedas buscar en tus logs.
7. Filtrado, ordenación, búsqueda y paginación
Todas son consultas sobre una colección: se implementan con parámetros de consulta en el GET, no con endpoints nuevos.
GET /v1/orders?status=shipped&customerId=7&sort=-createdAt&limit=25
GET /v1/products?q=teclado
GET /v1/orders?createdAfter=2026-01-01T00:00:00Z
- Filtros como parámetros con el nombre del campo:
status=shipped. - Ordenación:
sort=createdAt(ascendente) ysort=-createdAt(descendente). Permite varios campos separados por coma. Valida contra una lista de campos permitidos. - Búsqueda de texto:
q=.... - Rangos: sufijos o prefijos claros (
createdAfter,createdBefore). - Límite de tamaño de página, con un valor por defecto razonable (20 a 50) y un máximo (por ejemplo, 100).
Paginación: offset o cursor
Offset (?page=3&limit=25) |
Cursor (?cursor=...&limit=25) |
|
|---|---|---|
| Simplicidad | Alta | Media |
| Saltar a una página concreta | Sí | No |
| Rendimiento en tablas grandes | Se degrada con OFFSET altos |
Constante |
| Consistencia si cambian los datos | Puede duplicar u omitir filas | Estable |
| Recomendado para | Listados pequeños y paneles de administración | Feeds, listados grandes y datos que cambian |
Para colecciones grandes o cambiantes, usa paginación por cursor: el servidor devuelve un cursor opaco (nextCursor) y el cliente lo envía en la siguiente petición. Tampoco calcules el total de registros en cada llamada si es costoso: ofrécelo de forma opcional.
También puedes exponer los enlaces con la cabecera estándar Link (RFC 8288):
Link: <https://api.ejemplo.com/v1/orders?cursor=eyJpZCI6...>; rel="next"
Si los filtros son tan complejos que no caben en una URL, ofrece un endpoint de búsqueda: POST /orders/search con el criterio en el cuerpo. Es una excepción conocida, no la regla.
8. Versionado y evolución sin romper clientes
El mejor versionado es no romper. La mayoría de los cambios pueden hacerse de forma compatible:
| Cambio compatible (no requiere versión nueva) | Cambio incompatible (requiere versión nueva) |
|---|---|
| Añadir un campo en una respuesta | Eliminar o renombrar un campo |
| Añadir un endpoint | Cambiar el tipo o significado de un campo |
| Añadir un parámetro opcional | Añadir un parámetro obligatorio |
| Añadir un valor a un enumerado (si el contrato avisa de que puede ocurrir) | Cambiar códigos de estado o formato de errores |
Para que esto funcione, los clientes deben ignorar campos desconocidos, y tú debes documentarlo en el contrato.
Cuando hay que romper compatibilidad:
- Versión en la URL (
/v1/orders). Es la opción más usada y la más fácil de entender, depurar y cachear. Usa solo la versión mayor. - Alternativas: cabecera propia (
API-Version: 2) o media type (Accept: application/vnd.ejemplo.v2+json). Son más “puras” pero más difíciles de probar con un navegador ocurl. - Mantén pocas versiones vivas a la vez y define una política de soporte.
- Comunica la retirada con antelación. Existen cabeceras estándar:
Deprecation(RFC 9745) marca un recurso como obsoleto ySunset(RFC 8594) indica la fecha de retirada.
Deprecation: @1767225600
Sunset: Wed, 01 Jul 2027 00:00:00 GMT
Link: <https://api.ejemplo.com/docs/migracion-v2>; rel="deprecation"
9. Idempotencia y concurrencia
Reintentos seguros con Idempotency-Key
Las redes fallan. Si un cliente envía POST /payments, no recibe respuesta por un corte y reintenta, podrías cobrar dos veces. La solución habitual es una cabecera Idempotency-Key con un valor único generado por el cliente (un UUID):
POST /v1/payments
Idempotency-Key: 6f1c2f9e-8b4a-4d7e-9c3a-1e2b5d7a9f10
Content-Type: application/json
El servidor guarda el resultado asociado a esa clave durante un tiempo (24 horas es habitual); si recibe de nuevo la misma clave con el mismo cuerpo, devuelve la respuesta original sin repetir la operación. Si la clave se reutiliza con un cuerpo distinto, responde con un error (422 o 409). Es un patrón consolidado en APIs de pagos, y existe un borrador del IETF para estandarizarlo.
Ofrécela en toda operación POST cuyo reintento duplicado tenga consecuencias.
Control de concurrencia optimista con ETag
Si dos clientes editan el mismo recurso, el último puede pisar los cambios del primero. Usa ETag y If-Match:
GET /v1/orders/42
→ 200 OK
ETag: "v7"
PUT /v1/orders/42
If-Match: "v7"
→ 200 OK (si nadie lo cambió)
→ 412 Precondition Failed (si el recurso ya cambió: el cliente debe releer)
El mismo ETag sirve también para caché: con If-None-Match el servidor responde 304 Not Modified sin enviar el cuerpo.
10. Operaciones largas
Si una operación tarda más de unos segundos (generar un informe, procesar un archivo), no mantengas la conexión abierta. Responde 202 Accepted con la URL de un recurso de estado:
POST /v1/reports
→ 202 Accepted
Location: /v1/reports/jobs/91
GET /v1/reports/jobs/91
→ 200 OK
{ "status": "running", "progress": 40 }
GET /v1/reports/jobs/91
→ 303 See Other (cuando termina: apunta al resultado)
Location: /v1/reports/55
Para evitar sondeos continuos, ofrece además webhooks firmados con HMAC que avisen al cliente cuando termine.
11. Seguridad
La seguridad no es una fase posterior: se diseña desde el primer endpoint. La referencia es el OWASP API Security Top 10 (2023). Las medidas esenciales:
Transporte y autenticación
- Solo HTTPS, sin excepciones. Activa HSTS y rechaza o redirige el tráfico HTTP.
- OAuth 2.0 y OpenID Connect para delegar acceso: Authorization Code con PKCE para aplicaciones de usuario y Client Credentials para comunicación entre servicios. No inventes tu propio esquema de autenticación.
- Las API keys identifican aplicaciones, no autentican personas. Sirven para medir uso y limitar; no sustituyen a la autenticación fuerte en operaciones sensibles. Guárdalas con hash y permite rotarlas.
- Si usas JWT: vida corta (minutos), valida firma,
iss,audyexp, fija el algoritmo permitido (nunca aceptesnone) y no pongas datos sensibles en el payload, que es legible. Con tokens de refresco, rótalos y permite revocarlos. - Nunca envíes secretos en la URL (
?token=...): terminan en logs, historiales y proxies. Usa la cabeceraAuthorization: Bearer ....
Autorización
- Comprueba la autorización en cada petición y a nivel de objeto. El riesgo número uno de OWASP (Broken Object Level Authorization) es que un usuario cambie el ID en
/orders/42y acceda al pedido de otro. Verifica siempre que el recurso pertenece al usuario autenticado. - Autorización a nivel de propiedad: que un usuario pueda leer o modificar un recurso no significa que pueda tocar todos sus campos (
isAdmin,price). No hagas mass assignment: nunca copies el cuerpo recibido directamente al modelo; usa listas de campos permitidos. - Mínimo privilegio con scopes de OAuth y roles explícitos.
Entrada, abuso y exposición
- Valida toda la entrada contra un esquema (tipo, longitud, formato, rango) y rechaza lo desconocido. El contrato OpenAPI puede usarse para esto.
- Limita el tamaño del cuerpo y la complejidad de las consultas (profundidad, número de elementos).
- Rate limiting por cliente o por clave, respondiendo
429 Too Many RequestsconRetry-After. Protege además los endpoints sensibles (login, restablecer contraseña) con límites más estrictos. - CORS con lista de orígenes permitidos. Evita
Access-Control-Allow-Origin: *en APIs con credenciales. - No devuelvas más datos de los necesarios. Excluye contraseñas, hashes, tokens y campos internos.
- Registra accesos y fallos de autenticación sin guardar datos sensibles en los logs.
- Inventaría tus APIs: versiones antiguas olvidadas y endpoints de depuración expuestos son un clásico.
Para el servidor que aloja la API, consulta también nuestra guía de seguridad para servidores Ubuntu.
12. Rendimiento y caché
- Compresión (
gzipobr) para respuestas JSON de cierto tamaño. - Caché HTTP: usa
Cache-Control(max-age,privatepara datos de usuario,no-storepara datos sensibles) yETag. Una respuestaGETbien cacheada es la más rápida. - Paginación obligatoria en colecciones: nunca devuelvas una tabla completa.
- Selección de campos opcional (
?fields=id,status) cuando las respuestas son pesadas y los clientes necesitan poco. - Evita el problema N+1 en el servidor: carga relaciones en lote.
- Timeouts claros en llamadas a otros servicios y a la base de datos, y usa circuit breakers para no propagar fallos.
- HTTP/2 o HTTP/3 en el borde (proxy, balanceador): multiplexan peticiones y mejoran la latencia sin cambiar tu API.
13. Observabilidad
- Correlación: acepta y propaga la cabecera
traceparentde W3C Trace Context. Devuelve el identificador de la petición en la respuesta y en los errores. - Logs estructurados (JSON) con método, ruta, estado, duración y el identificador de correlación.
- Métricas RED por endpoint: tasa de peticiones (Rate), errores (Errors) y duración (Duration, con percentiles p95 y p99).
- Endpoints de salud para el orquestador: uno de liveness (el proceso está vivo) y otro de readiness (puede atender tráfico, con sus dependencias listas). No los expongas públicamente con información interna.
14. Documentación y experiencia de desarrollo
Una API sin buena documentación no se adopta, o se adopta mal.
- Genera la documentación a partir del contrato OpenAPI (Swagger UI, Redoc, Scalar) para que nunca se desincronice del código.
- Incluye ejemplos reales de petición y respuesta para cada endpoint, incluidos los errores.
- Guía de inicio rápido: cómo obtener credenciales y hacer la primera llamada en menos de cinco minutos.
- Entorno de pruebas (sandbox) con datos ficticios.
- Registro de cambios (changelog) público y avisos de obsolescencia.
- SDK y colecciones generadas desde el contrato (OpenAPI Generator, colecciones de Postman).
Lista de verificación
- La API está descrita con OpenAPI 3.1 y revisada antes de implementarse.
- URLs con sustantivos en plural, minúsculas y máximo dos niveles de anidamiento.
- Cada método HTTP se usa con su semántica;
GETno modifica datos. - Códigos de estado correctos; nunca
200con un error en el cuerpo. - Errores en formato Problem Details (RFC 9457) con identificador de correlación.
- Fechas en RFC 3339 UTC; dinero en enteros o decimales como cadena.
- Colecciones paginadas (cursor para datos grandes) con límite máximo.
- Cambios compatibles por defecto; versión en la URL solo para rupturas; política de retirada con
DeprecationySunset. -
Idempotency-KeyenPOSTcríticos;ETagyIf-Matchen actualizaciones. - Solo HTTPS; OAuth 2.0 u OIDC; validación de token completa.
- Autorización por objeto y por propiedad en cada petición.
- Validación de entrada, límites de tamaño y rate limiting con
429. - CORS con lista de orígenes; sin secretos en URLs ni en logs.
- Logs estructurados, métricas y trazas con propagación de
traceparent. - Documentación generada del contrato, con ejemplos y guía de inicio.
Errores comunes
- Verbos en las URLs (
/getUser,/deleteOrder): el método HTTP ya expresa la acción. 200 OKpara todo, con{ "success": false }en el cuerpo. Rompe cachés, métricas, alertas y clientes genéricos.- Usar
GETpara operaciones que cambian datos. Un rastreador o una precarga del navegador puede ejecutarlas. - Devolver arreglos desnudos en la raíz. Impide añadir paginación o metadatos sin romper compatibilidad.
- Paginación por
OFFSETen tablas enormes. Se vuelve lenta y produce duplicados cuando cambian los datos. - Exponer IDs secuenciales sin comprobar propiedad. Es el origen del riesgo número uno de OWASP en APIs.
- Mensajes de error con trazas de pila o SQL. Regalas información al atacante.
- Cambiar la respuesta “un poquito” sin versionar. Un campo renombrado rompe aplicaciones que no controlas.
- Inventar autenticación propia en lugar de usar OAuth 2.0 u OIDC.
- Documentación a mano que se desactualiza. Genérala del contrato.
Preguntas frecuentes
¿Qué diferencia hay entre PUT y PATCH?
PUT reemplaza el recurso completo con la representación enviada. PATCH aplica cambios parciales. Si un cliente solo quiere cambiar el teléfono de un usuario, PATCH es lo adecuado; con PUT tendría que enviar todos los demás campos.
¿Debo usar /v1 en la URL o una cabecera?
La versión en la URL es la opción más práctica para la mayoría de equipos: es visible, fácil de probar y de enrutar. Las cabeceras y media types son válidas pero más incómodas. Lo más importante es no romper compatibilidad con cambios inesperados.
¿Necesito implementar HATEOAS?
No es obligatorio en la práctica. Los enlaces de paginación (Link) y las URL en Location son los usos con más retorno. Una API con hipermedia completa exige clientes que la aprovechen, y pocos lo hacen.
¿REST, GraphQL o gRPC?
REST encaja muy bien en APIs públicas y de recursos, aprovecha la caché HTTP y es entendible por todos. GraphQL resulta útil cuando muchos clientes distintos necesitan formas de datos muy diferentes. gRPC destaca en comunicación interna entre servicios de baja latencia. Pueden convivir en un mismo sistema.
¿Cuánto debe durar un token de acceso?
Poco: entre 5 y 15 minutos es habitual, combinado con un token de refresco rotatorio. Cuanto más corta la vida, menos útil es un token robado.
¿Cómo evito que me cobren dos veces por un reintento?
Con claves de idempotencia (Idempotency-Key) en el POST, guardando la respuesta original asociada a la clave durante un tiempo.
Para seguir leyendo
- IETF, RFC 9110: HTTP Semantics
- IETF, RFC 9457: Problem Details for HTTP APIs
- OpenAPI Initiative, OpenAPI Specification 3.1
- OWASP, API Security Top 10 (2023)
- IETF, RFC 8594: The Sunset HTTP Header Field
- W3C, Trace Context

