Buenas prácticas API Rest

General

Una API es una interfaz de usuario (UI) para un desarrollador, al igual que cualquier UI, es importante asegurar que la experiencia del usuario esté pensada cuidadosamente!

Usa acciones y URLs RESTful

Los fundamentales principios de REST se basan en separar tu API en recursos lógicos. Estos recursos son manipulados usando peticiones HTTP donde el método (GET, POST, PUT, PATCH, DELETE) tienen un significado específico.

¿Pero qué puede hacer un recurso? Bueno, estos deberían ser sustantivos (¡no verbos!) que tengan sentido desde una perspectiva del consumidor de la API. Aunque tus modelos internos pueden mapear cuidadosamente con los recursos, no es necesario que sea un mapeo uno-a-uno.

Una vez que tienes tus recursos definidos, necesitas identificar qué acciones aplican a ellos y cómo deberían relacionarse con tu API. Los principios REST proveen estrategias para manejar acciones CRUD usando métodos HTTP relacionados de la siguiente forma:

GET /tickets- Devuelve una lista de tickets
GET /tickets/12- Devuelve un ticket específico
POST /tickets- Crea un nuevo ticket
PUT /tickets/12- Actualiza el ticket #12
PATCH /tickets/12- Actualiza parcialmente el ticket #12
DELETE /tickets/12- Elimina el ticket #12

Siempre usar plural para los recursos.

Ejemplos

/tickets
/tickets/12

Relaciones

¿Pero cómo lidiar con las relaciones? Si una relación puede existir con un sólo recurso, los principios REST proveen una guía útil. Veamos esto con un ejemplo. Un ticket consiste en un número de mensajes. Estos mensajes pueden ser lógicamente mapeados al endpoint /tickets de la siguiente forma:

 GET /tickets/12/messages - Devuelve una lista de mensajes para el ticket #12
 GET /tickets/12/messages/5 - Devuelve el mensaje #5 para el ticket #12
 POST /tickets/12/messages - Crea un nuevo mensaje en el ticket #12
 PUT /tickets/12/messages/5 – Actualiza el mensaje #5 para el ticket #12
 PATCH /tickets/12/messages/5 - Actualiza parcialmente el mensaje #5 para el ticket #12
 DELETE /tickets/12/messages/5 - Borra el mensaje #5 para el ticket #12

Obervaciones

A veces realmente no tienes forma de mapear la acción a una estructura REST apropiada.

Por ejemplo, una búsqueda multi-recurso no tiene sentido ser asignada a un endpoint de un recurso específico. En este caso, /search podría tener más sentido incluso si no es un sustantivo. Esto está BIEN – sólo realiza lo que sea correcto desde la perspectiva del consumidor de la API y asegúrate de que esté claramente documentado para evitar confusiones.

Extras

• Usa SSL en todos lados, sin excepciones.
• Tener una buena documentación.
• Versiona a través de la URL.
• Usa parámetros de consulta para filtros avanzados, ordenamiento y búsqueda.
• Provee una forma de limitar cuáles campos son devueltos desde la API.
• Devuelve algo útil de las peticiones POST, PATCH & PUT.
• Usa JSON donde sea posible, XML sólo si tienes la obligación.
• Deberías usar camelCase con JSON, pero snake_case es un 20% más fácil de leer.
• Usa Pretty Print por defecto y asegura que gzip esté soportado.
• No uses respuestas encapsuladas por defecto.
• Considera usar JSON para cuerpos de peticiones POST, PUT y PATCH.
• Provee encabezados de respuesta útiles para controles de tráfico (rate limiting).
• Usa autenticación basada en tokens.
• Incluir encabezados de respuesta que faciliten el caché.
• Define un error de carga útil (payload) que sea consumible
• Utilizar efectivamente los códigos de error HTTP