Las Mejores Prácticas de Endpoints REST que Todo Desarrollador Debe Conocer

Como desarrollador de software, es probable que encuentres APIs RESTful con frecuencia.

REST (Representational State Transfer) es un estilo arquitectónico para diseñar aplicaciones en red, y adherirse a sus principios es crucial para crear servicios web escalables, mantenibles y eficientes.

Profundizaremos en las mejores prácticas para diseñar endpoints REST, completas con ejemplos, para ayudarte a construir APIs sólidas y amigables para el usuario.

Los servicios REST no tienen una regla estricta de nomenclatura y somos libres de implementarlos de la manera que deseemos, sin embargo, existen ciertas pautas que aseguran que nuestra API REST sea fácil de leer, consistente e intuitiva.

Manténlo Sencillo

Esto no es específico de las pautas de nomenclatura de recursos, pero es un concepto importante al diseñar tu API. La nomenclatura de nuestra API REST debe ser autoexplicativa y lo más sencilla posible. Uno de los principios importantes al nombrar nuestra API es permitir que los desarrolladores trabajen en ella sin tener que consultar los documentos en cada punto.

/api/usuarios/12345 ✅
/api?type=usuario&id=12345 ❌

Al observar el segundo ejemplo, no está claro lo que estamos intentando hacer hasta que observamos los campos "type" y "id" juntos.

Utiliza Sustantivos en Plural para la Nomenclatura de Recursos en las URI

RESTful Un principio clave para diseñar endpoints RESTful es utilizar sustantivos para representar recursos y utilizar nombres en plural para mantener la consistencia. Esto hace que tu API sea más intuitiva y fácil de comprender. Recuerda evitar el uso de verbos o acciones en los nombres de los endpoints, ya que los métodos HTTP ya transmiten la acción.

Dado que una de las operaciones más comunes realizadas por la API REST es obtener datos, el uso del plural es más intuitivo y fácil.

GET Usuarios -> /api/usuarios ✅
GET Cuenta de Usuario -> /api/usuarios/{userId} ✅
GET Derechos del Usuario -> /api/usuarios/{userId}/derechos ✅

GET Usuarios -> /api/obtenerTodosLosUsuarios ❌

Ten en cuenta los siguientes puntos:

• No mezcles convenciones de singular y plural al nombrar tus recursos. Debe ser consistente en toda la API para una mejor legibilidad.
• La URL representa un recurso que puede ser un elemento único o una colección. Un plural representa todos los recursos bajo la URI dada.

/api/clientes -> representa a todos los clientes.
/api/clientes/{id} -> representa a un cliente específico en este recurso.

• Un recurso dado también puede contener subcolecciones.

/api/clientes/{id}/ordenes
/api/clientes/{id}/ordenes/{id-de-orden}

Sigue los Métodos HTTP Estándar

Para operaciones CRUD (Crear, Leer, Actualizar y Borrar), siempre utiliza los métodos HTTP estándar. Esto garantiza consistencia en toda tu API y ayuda a los desarrolladores a comprender tus endpoints más rápidamente.

• POST (Crear): Crea un nuevo recurso.
• GET (Leer): Recupera un recurso o una colección de recursos.
• PUT (Actualizar): Actualiza un recurso.
• DELETE (Borrar): Elimina un recurso.

POST /usuarios // Crear un nuevo usuario
GET /usuarios // Obtener todos los usuarios
GET /usuarios/{id} // Obtener un usuario específico
PUT /usuarios/{id} // Actualizar un usuario específico
DELETE /usuarios/{id} // Eliminar un usuario específico

Nunca uses nombres de funciones CRUD en las URIs

No debemos utilizar URIs para indicar una función CRUD. Las URIs solo deben usarse para identificar de manera única los recursos y no para ninguna acción sobre ellos.

/api/getUsers ❌
/api/getUserRights ❌

GET /api/usuarios ✅
GET /api/usuarios/12345/derechos ✅

Debemos utilizar los métodos de solicitud HTTP para indicar qué función CRUD se está realizando.

Utiliza la barra diagonal (/) para indicar relaciones jerárquicas

El carácter de barra diagonal (/) se utiliza en la parte de la ruta de la URI para indicar una relación jerárquica entre recursos.

/api/usuarios/{userId}/derechos
/api/clientes/{id}/ordenes

Usa Guiones (-)

Para que tus URIs sean fáciles de escanear e interpretar, utiliza el guion (-) para mejorar la legibilidad de los nombres en segmentos de ruta largos.

/api/clientes/{id}/direcciones/{id-de-direccion}
/api/clientes/{id}/direcciones-de-envio/{id-de-direccion}

Evita los guiones bajos ()

Se recomienda evitar los guiones bajos al nombrar tus URIs. Dependiendo de la fuente de la aplicación, es posible que el carácter de guion bajo () se pueda ocultar parcialmente o completamente en algunos navegadores o pantallas.

Para evitar esta confusión, utiliza guiones (-) en lugar de guiones bajos (_).

Aprovecha los Parámetros de Consulta para la Flexibilidad

Al construir APIs RESTful, nos encontraremos con múltiples requisitos en los que necesitamos una colección de recursos con:

• Ordenación.
• Filtrado de ciertos resultados de la colección.
• Resultados limitados según ciertas condiciones.

No crees una nueva API para estos requisitos, en su lugar, habilita las capacidades de ordenación, filtrado y paginación en la API de colección de recursos y pasa los parámetros de entrada como parámetros de consulta. Esto mantiene tu API limpia y la hace más flexible para los desarrolladores.

GET /usuarios?genero=masculino&edad=25-35&orden=edad,desc&page=1&size=10

La Versión Importa: Sé Consistente

La versión de la API es esencial para mantener la compatibilidad y permitir transiciones suaves al realizar cambios en tu API. Incluye el número de versión en la URL o como encabezado de solicitud para mantener la consistencia.

// Versión en la URL
GET /api/v1/usuarios

// Versión en el encabezado
GET /api/usuarios
Accept: application/vnd.example.v1+json

Comunica con los Códigos de Estado HTTP Correctos

Utiliza los códigos de estado HTTP correctos para informar a los clientes sobre el resultado de sus solicitudes. Esto ayuda a los desarrolladores a manejar errores y comprender los resultados de sus llamadas a la API de manera más efectiva.

Códigos de estado comunes:

• 200 OK: solicitudes GET o PUT exitosas.
• 201 Created: solicitudes POST exitosas.
• 204 No Content: solicitudes DELETE exitosas.
• 400 Bad Request: solicitud del cliente no válida.
• 401 Unauthorized: la solicitud requiere autenticación.
• 403 Forbidden: el cliente carece de permisos.
• 404 Not Found: recurso solicitado no encontrado.
• 500 Internal Server Error: error del servidor.

Mejora la Descubribilidad con HATEOAS

Hypermedia como el Motor del Estado de la Aplicación (HATEOAS) es un principio de diseño RESTful que fomenta proporcionar enlaces a recursos relacionados en las respuestas de la API. Esto mejora la descubribilidad y permite a los desarrolladores navegar por tu API con facilidad.

GET /users/123
{
  "id": 123,
  "nombre": "Juan Pérez",
  "enlaces": [
    {
      "rel": "self",
      "href": "/usuarios/123"
    },
    {
      "rel": "editar",
      "href": "/usuarios/123/editar"
    },
    {
      "rel": "eliminar",
      "href": "/usuarios/123"
    }
  ]
}

Documentación: Un Elemento Imprescindible

Una API es tan buena como su documentación. La documentación clara, consistente e interactiva es fundamental para que los desarrolladores comprendan y trabajen de manera efectiva con tu API. Utiliza herramientas como Swagger o API Blueprint para generar una documentación integral de tus endpoints.

Conclusión

El diseño de APIs RESTful es una parte integral del desarrollo de software moderno. Al seguir estas mejores prácticas, crearás APIs sólidas, mantenibles y amigables que facilitarán la interacción de los desarrolladores con tus servicios web.

Recuerda enfocarte en los nombres de los recursos, utilizar métodos HTTP estándar, aprovechar los parámetros de consulta, mantener una versión consistente, utilizar los códigos de estado correctos, implementar HATEOAS y proporcionar documentación completa.

Estas prácticas te encaminarán hacia el diseño de endpoints REST de primera categoría que los desarrolladores adorarán utilizar.