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

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