Artículo elaborado por:



José Collado

Desarrollador Full Stack

Desarrollador Full Stack especializado en Angular y Spring Boot, con interés en User Experience y Usabilidad.



Marco Naranjo

Software Engineer

Analista Programador especializado en Java y Python. Apasionado de los gráficos 3D y con gran interés en Machine Learning e Inteligencia Artificial.

Contenidos

1. Introducción
2. Organización
   • 2.1 Principios clave de REST
     • Resumen visual de los principios REST
   • 2.2 API como producto y enfoque API First
3. Buenas Prácticas REST
   • 3.1 Métodos HTTP
     • Resumen visual de los métodos HTTP
     • Matices avanzados en el uso de métodos HTTP
   • 3.2 Códigos de Estado y Errores
     • Uso correcto de los códigos de estado HTTP
     • Respuestas de error estructuradas
     • Buenas prácticas adicionales
     • Trazabilidad y encabezados propietarios
   • 3.3 Diseño de URLs y Recursos
     • Reglas clave para el diseño de URLs
   • 3.4 Carga útil (Payload)
   • 3.5 Versionado, Compatibilidad y Deprecación
     • Versionado semántico
     • Compatibilidad hacia atrás
     • Deprecación de endpoints y funcionalidades
   • 3.6 Seguridad
     • Autenticación y autorización
   • 3.7 Rendimiento, Paginación y Rate Limiting
     • Estrategias de caché
     • Rate limiting (limitación de peticiones)
4. Conclusiones y Recursos adicionales
   • Recursos recomendados

1. Introducción

Las APIs REST se han convertido en el estándar de facto para la integración de sistemas y el desarrollo de aplicaciones modernas. Su popularidad radica en la simplicidad, flexibilidad y escalabilidad que ofrecen al exponer servicios a través de la web utilizando el protocolo HTTP.

Sin embargo, diseñar una API REST no consiste solo en exponer endpoints: implica seguir una serie de principios y buenas prácticas que garantizan la mantenibilidad, la seguridad y la facilidad de uso tanto para desarrolladores internos como externos. Una API bien diseñada facilita la evolución del producto, reduce errores y mejora la experiencia de quienes la consumen.

En esta guía práctica encontrarás los fundamentos esenciales y las recomendaciones clave para diseñar APIs REST robustas, coherentes y alineadas con los estándares actuales del sector. Tanto si estás comenzando como si buscas perfeccionar tus servicios existentes, aquí descubrirás cómo llevar tus APIs al siguiente nivel.

2. Organización

El diseño de una API RESTful se basa en una serie de principios arquitectónicos que garantizan su simplicidad, escalabilidad y facilidad de integración. Comprender estos principios es esencial para crear servicios robustos y predecibles.

2.1 Principios clave de REST

• Cliente-servidor:

Separa la interfaz de usuario (cliente) de la lógica de datos y reglas de negocio (servidor). Esto permite evolucionar ambos lados de forma independiente.

• Sin estado (Stateless):

Cada petición HTTP contiene toda la información necesaria para ser procesada. El servidor no almacena el estado de la sesión entre peticiones, lo que facilita la escalabilidad y la tolerancia a fallos.

• Caché:

Las respuestas pueden ser almacenadas temporalmente por el cliente o intermediarios para mejorar el rendimiento y reducir la carga del servidor. Es fundamental definir correctamente qué recursos son cacheables.

• Interfaz uniforme:

Todas las interacciones entre cliente y servidor siguen una estructura estándar, utilizando métodos HTTP bien definidos (GET, POST, PUT, DELETE, etc.). Esto simplifica el desarrollo y la integración.

• Sistema en capas:

La arquitectura puede estar compuesta por varias capas (por ejemplo, balanceadores, proxies, gateways), cada una con responsabilidades claras. El cliente no necesita saber si está comunicándose directamente con el servidor final.

Resumen visual de los principios REST

2.2 API como producto y enfoque API First

El diseño de una API no es solo una cuestión técnica, sino también de producto. Adoptar el enfoque de API como Producto implica tratar la API como un servicio independiente, con su propio ciclo de vida, documentación, soporte y evolución, pensando siempre en la experiencia del desarrollador que la consume.

Por otro lado, el principio API First recomienda definir y consensuar la especificación de la API (por ejemplo, usando OpenAPI) antes de comenzar la implementación. Esto permite:

• Obtener feedback temprano de los consumidores.
• Garantizar la coherencia y calidad de la interfaz.
• Facilitar la automatización de pruebas, documentación y validación.

Consejo: Diseñar la API como un producto y aplicar API First mejora la mantenibilidad, la adopción y la calidad de los servicios expuestos.

3. Buenas prácticas REST

3.1 Métodos HTTP

• GET:

Utiliza GET solo para operaciones de lectura. No debe modificar el estado del servidor ni aceptar cuerpo en la petición. Ideal para obtener datos, además, soporta cacheado.

• POST:

Empléalo para crear recursos en una colección o para operaciones que no encajan en otros métodos (por ejemplo, búsquedas complejas). No es idempotente: enviar la misma petición varias veces puede crear múltiples recursos.

• PUT:

Úsalo para reemplazar completamente un recurso identificado por su URI. Es idempotente: varias peticiones idénticas tienen el mismo efecto.

• PATCH:

Ideal para actualizaciones parciales de un recurso. Aunque no es idempotente por definición, se recomienda que lo sea para evitar efectos inesperados.

• DELETE:

Elimina el recurso especificado. Es idempotente: eliminar varias veces el mismo recurso no genera error.

• HEAD y OPTIONS:

Útiles para obtener metadatos o descubrir capacidades del endpoint sin transferir datos innecesarios.

Resumen visual de los métodos HTTP

Matices avanzados en el uso de métodos HTTP

Aunque los métodos HTTP tienen una semántica estándar, existen matices importantes en su uso real:

• GET con cuerpo: Si la información no cabe en la URL, se recomienda usar POST para búsquedas que no crean recursos.
• POST idempotente: Aunque POST no es idempotente por definición, en algunos escenarios (como operaciones de upsert) puede implementarse de forma idempotente para evitar duplicados.
• PUT y creación implícita: PUT puede usarse tanto para actualizar como para crear un recurso si no existe, pero siempre debe ser idempotente.
• DELETE: Puede aceptar parámetros de consulta para eliminar múltiples recursos, pero si se requiere lógica compleja, es preferible documentarlo claramente o usar POST.
• Códigos de estado avanzados: Considera el uso de códigos como 202 (Accepted) para operaciones asíncronas, y 410 (Gone) para recursos eliminados permanentemente.

Consejo: Documenta siempre los matices y comportamientos especiales de cada endpoint para evitar ambigüedades en la integración.

Si se desea encontrar más ejemplos, así como detalles de implementación, se puede revisar este otro artículo del blog.

3.2 Códigos de Estado y Errores

Uso correcto de los códigos de estado HTTP

• No abuses del 200:

No devuelvas siempre 200 OK. Selecciona el código que mejor describa el resultado de la operación. No sirve devolver 200 OK con un objeto que indique un error en la respuesta.

• Utiliza solo códigos oficiales y específicos:

Emplea los códigos definidos en los estándares HTTP (por ejemplo, 200, 201, 204, 400, 404, 409, 500, 503). Evita códigos personalizados o ambiguos.

• Elige el código más preciso:

Por ejemplo, utiliza 201 Created al crear un recurso, 204 No Content al eliminarlo, 400 Bad Request para errores de validación y 404 Not Found si el recurso no existe.

Respuestas de error estructuradas

• Formato estándar:

Utiliza el formato Problem+JSON (application/problem+json) para describir errores. Esto permite a los clientes interpretar y manejar los fallos de forma consistente.

• Incluye información útil:

Proporciona detalles como el tipo de error, un título descriptivo, una explicación detallada y, si es posible, una referencia a la documentación.

Ejemplo de respuesta de error

{
  "type": "https://api.ejemplo.com/problems/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "El campo 'email' no tiene un formato válido.",
  "instance": "/users"
}

Buenas prácticas adicionales

• No expongas trazas de pila ni detalles internos en las respuestas de error. Limítate a información relevante para el cliente.
• Documenta los posibles errores de cada endpoint en la especificación de la API.
• Incluye encabezados útiles como Retry-After en casos de limitación de peticiones (429 Too Many Requests).

Consejo: Una gestión clara y estructurada de los errores reduce la frustración de los desarrolladores y agiliza la resolución de incidencias.

Trazabilidad y encabezados propietarios

Para facilitar el seguimiento de peticiones a través de microservicios, es recomendable propagar encabezados de trazabilidad como traceparent (W3C Trace Context) o identificadores propietarios (X-Flow-ID, EDICOM_TRACE_ID). Estos encabezados permiten correlacionar logs y diagnosticar incidencias de forma eficiente en arquitecturas distribuidas.

3.3 Diseño de URLs y Recursos

Reglas clave para el diseño de URLs

• Usa nombres de recursos en plural:

Ejemplo: /users, /orders, /products

• Emplea kebab-case para los segmentos de ruta:

Ejemplo: /shipment-orders/{shipment-order-id}

• Evita verbos y acciones en las rutas:

Las URLs deben describir recursos, no acciones.

Correcto: /orders/123/cancelations

Incorrecto: /orders/123/cancel

• Identifica recursos y subrecursos mediante la jerarquía de rutas:

Ejemplo: /users/123/orders/456

• No uses rutas con barras finales o segmentos vacíos:

Correcto: /customers/123/addresses

Incorrecto: /customers//addresses/

• Utiliza identificadores compatibles con URL:

Los IDs deben ser cadenas ASCII simples, evitando caracteres especiales o espacios.

Ejemplos prácticos

3.4 Carga Útil (Payload)

• Utiliza siempre JSON como formato de intercambio:

Define el encabezado Content-Type: application/json en todas las peticiones y respuestas que incluyan datos.

• Nombres de propiedades en snake_case:

Usa siempre snake_case (user_id, order_date) para los nombres de las propiedades, evitando camelCase o PascalCase. Esto mejora la legibilidad y la coherencia.

• Evita valores nulos en campos booleanos:

Un campo booleano debe ser siempre true o false. Si necesitas un tercer estado (por ejemplo, “no definido”), utiliza una enumeración explícita.

• Define campos comunes y consistentes:

Usa nombres estándar como id, created_at, updated_at, y sigue la misma semántica en todos los recursos.

• Utiliza formatos estándar:

Utiliza siempre formatos estándar para los datos intercambiados:

1. Fechas y horas: ISO 8601 / RFC 3339 («2015-05-28T14:07:17Z»).
2. Países: ISO 3166-1 alpha-2 («ES»).
3. Idiomas: ISO 639-1 («en»).
4. Monedas: ISO 4217 («EUR»).

Esto garantiza interoperabilidad y evita ambigüedades en la interpretación de los datos.

Ejemplo de carga útil JSON correcta

{
  "user_id": "12345",
  "name": "Ana García",
  "email": "ana.garcia@example.com",
  "created_at": "2025-09-23T09:00:00Z",
  "is_active": true
}

3.5 Versionado, Compatibilidad y Deprecación

A medida que una API evoluciona, es fundamental gestionar los cambios de forma que no se rompa la experiencia de los clientes existentes. Un buen control de versiones y una política clara de compatibilidad y deprecación son claves para la estabilidad y la confianza en tu API.

Versionado semántico

• Sigue el versionado semántico: MAJOR.MINOR.PATCH

Puedes obtener más información en la documentación de Semver.

Compatibilidad hacia atrás

• Evita romper contratos existentes:

Los cambios que eliminan campos modifican el significado de los datos o cambian el comportamiento de los endpoints deben evitarse o planificarse cuidadosamente.

• Documenta claramente los cambios:

Mantén un registro de cambios (changelog) y comunica cualquier modificación relevante a los consumidores de la API.

Deprecación de endpoints y funcionalidades

• Marca los elementos obsoletos en la documentación:

Usa la propiedad deprecated: true en la especificación (por ejemplo, en OpenAPI) y añade una explicación de la alternativa recomendada.

• Comunica con antelación:

Informa a los clientes sobre la fecha de retirada y ofrece un periodo de transición razonable.

3.6 Seguridad

La seguridad es un pilar fundamental en cualquier API. Proteger los datos y los servicios no solo es una obligación legal y ética, sino que también refuerza la confianza de los usuarios y clientes.

Autenticación y autorización

• Protege todos los endpoints:

Exige autenticación para acceder a cualquier recurso, incluso los de solo lectura. Los esquemas más comunes son OAuth2 y Bearer Token.

• Define permisos claros:

Utiliza scopes o roles para limitar el acceso a operaciones sensibles según el perfil del usuario o aplicación.

• No expongas información sensible:

Nunca incluyas datos internos, trazas de pila, mensajes de error detallados ni información de infraestructura en las respuestas de la API.

• Valida y sanitiza todas las entradas:

Protege tu API frente a ataques comunes como inyección de código o datos maliciosos.

3.7 Rendimiento, Paginación y Rate Limiting

El rendimiento y la escalabilidad son aspectos críticos en el diseño de APIs REST. Una API eficiente no solo responde rápido, sino que también protege los recursos del servidor y ofrece una experiencia fluida a los usuarios.

Estrategias de caché

• Aprovecha el almacenamiento en caché:

Permite que clientes e intermediarios almacenen respuestas temporales para reducir la carga y la latencia.

1. Usa encabezados como Cache-Control, ETag y Last-Modified para controlar el comportamiento de la caché.
2. Documenta qué endpoints pueden ser cacheados y durante cuánto tiempo.

Ejemplo de uso de ETag

Paginación de resultados

• Implementa paginación en listas grandes:

Evita devolver grandes volúmenes de datos en una sola respuesta.

1. Usa parámetros como limit y offset (paginación por desplazamiento) o cursor (paginación basada en cursor).
2. Incluye información sobre la página actual, el total de elementos y enlaces a páginas siguientes/anteriores.

Ejemplo de respuesta paginada

{
  "total": 120,
  "limit": 10,
  "offset": 20,
  "users": [
    { "user_id": "123", "name": "Ana" },
    { "user_id": "124", "name": "Luis" }
  ],
  "links": {
    "next": "/users?limit=10&offset=30",
    "prev": "/users?limit=10&offset=10"
  }
}

Rate limiting (limitación de peticiones)

• Protege tu API frente a abusos:

Limita el número de peticiones permitidas por usuario o aplicación en un periodo de tiempo.

1. Usa el código de estado 429 Too Many Requests cuando se exceda el límite.
2. Incluye encabezados informativos como Retry-After y X-RateLimit-Remaining para ayudar a los clientes a gestionar sus peticiones.

• Ejemplo de encabezados de rate limiting:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1695398400
Retry-After: 60

4. Conclusión y Recursos adicionales

Diseñar una API REST robusta y fácil de consumir requiere atención al detalle, coherencia y un enfoque centrado en el desarrollador. Aplicando las buenas prácticas descritas en esta guía, podrás crear servicios más mantenibles, seguros y preparados para evolucionar junto a las necesidades de tu negocio y tus usuarios.

Recuerda: una API bien diseñada no solo facilita la integración, sino que también reduce errores, mejora la experiencia de los desarrolladores y refuerza la reputación de tu producto o empresa.

Recursos recomendados

• Implementación de una API REST completa
  • https://careers.edicomgroup.com/blogtech/implementacion-de-una-api-rest-completa-parte-i/
• Best practices for RESTful web API design
  • https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design
• Zalando RESTful API and Event Guidelines
  • https://opensource.zalando.com/restful-api-guidelines/
• RESTFULAPI: What is rest?
  • https://restfulapi.net/