Buenas Prácticas para diseñar una API RESTful-pragmatic (Parte I)

Complementado estos posts sobre recomendaciones para el diseño de un API RESTful

Abrimos una nueva serie de posts (al menos este y otro más) sobre el diseño de APIS REST:

 

1.Las APIS son para los programadores: esfuérzate en que sea agradable de usar

Para eso:

  • Debe usar estándares Web donde tenga sentido
  • Debe ser amigable con el desarrollador
  • Debe ser explorable con el navegador
  • Debe ser sencilla e intuitiva
  • El API debe ser consistente

 

2.Usar URLs y verbos RESTful

  • Las APIs se separan en recursos lógicos
  • Los recursos se manipulan con peticiones HTTP con los verbos GET, POST, UPDATE y DELETE

 

3.Identificar los Recursos

  • Los Recursos son nombres y no verbos
  • Los Recursos tienen sentido para el consumidor del API
  • Los Recursos no tienen que mapear 1 a 1 con los recursos o el Backend
  • Los Recursos abstraen y aíslan de detalles de implementación

 

4.Identificar las acciones

  • Una vez identificados los recursos identificaremos las acciones que aplican a estos y cómo mapean al API
  • Una de las ventajas de RESTful es que no es necesaria una convención de métodos para poder invocar el API y que la estructura de las URLS es clara y limpia.

GET /reclamaciones – Recupera una lista de reclamaciones

GET /reclamaciones/12 – Recupera la reclamación #12

POST /reclamaciones – Crea una nueva reclamación

PUT /reclamaciones/12 – Actualiza reclamación #12

PATCH /reclamaciones/12 – Actualiza parcialmente la reclamación #12

DELETE /reclamaciones/12 – Borra la reclamación #12

5.Usar el endpoint en plural

  • Aunque la lógica parece decir que un Recurso debe ser singular se ha extendido el uso del plural (/tickets/ en lugar de /ticket/)

 

6.Manejo de relaciones:

  • Si una relación sólo puede existir dentro de otro recurso se manejará como subrecurso. Veamos un ejemplo:

GET /reclamaciones/12/mensajes – Recupera la lista de mensajes de la reclamación #12

GET /reclamaciones/12/mensajes/5 – Recupera el mensajes #5 para la reclamación #12

POST /reclamaciones/12/mensajes – Crea un nuevo mensaje en la reclamación #12

PUT /reclamaciones/12/mensajes/5 – Actualiza el mensaje #5 de la reclamación #12

PATCH /reclamaciones/12/mensajes/5 – Actualiza parcialmente el mensaje #5 de la reclamación #12

DELETE /reclamaciones/12/mensajes/5 – Borra el mensaje #5 de la reclamación #12

  • ·Si una relación puede existir independientemente del recursos se debe incluir un identificador (URI) con la representación del recurso. El consumidor tendrá que ir al endpoint de la relación, si la relación es muy usada el API puede automáticamente embeber la representación de la relación.

 

7.¿Qué hacer con las relaciones que no encajan en las operaciones CRUD?

Justo en este punto es donde nos chocamos por primera vez: cómo hacer una validación, o un cerrar Reclamación.

Por desgracia no hay una única aproximación, se puede:

  1.  Reestructurar la acción para que parezca un campo de un recurso. Esto sirve si la acción no toma parámetros, y encajaría para validar una reclamación si añado un campo validado y lo actualizo vía PATCH.
  2. Tratar la acción como un subrecurso siguiendo los patrones RESTful. Por ejemplo en GitHub para dar una estrella:

3. En algunas ocasiones no existe forma de mapear una acción a una estructura RESTful, por ejemplo para una búsqueda con varios criterios. En esos casos lo lógico sería poner un /search aunque no sea un nombre. Esto es correcto si lo es para el consumidor, simplemente documéntalo claramente.

8.Usar siempre SSL

  • Las APIS pueden ser accedidas desde cualquier sitio, lo que hace más probable que si no usas SSL se desencripte la autenticación.
  • Con SSL además tengo la ventaja de que puedo usar Tokens simples en lugar de firmar cada petición.

 

9.Documentación:

  • Deben tener ejemplos completos de ciclos petición/respuesta. Preferiblemente ejemplos para copier.
  • Una vez publicada un API no debe “romperse” nada sin avisar. La documentación debe añadir cualquier scheduling para deprecar.
  • Podemos ver el API de Gists de GitHub: http://developer.github.com/v3/gists/
  • Si nos fijamos en la de Stripes (https://stripe.com/docs/api) tenemos:

API EndPoint:

Ejemplo de petición:

Sumario de códigos HTTP que se manejan

10.Versionado:

  • Siempre versiona tu API.
  • Hay opiniones encontradas sobre si la versión debe estar en la URL o en una cabecera. Para garantizar que el API puede explotarse desde el navegador la versión debe estar en la URL.
  • Algunas APIs como Stripes usan una major versión que va en la URL y una versión minor opcional que se pasa como header y es la fecha de la publicación: https://stripe.com/docs/api#versioning

 

Anuncios

2 comentarios to “Buenas Prácticas para diseñar una API RESTful-pragmatic (Parte I)”

  1. Fer0 Says:

    Respecto a relaciones que no son CRUD: Si conviertes la acción en un subrecurso de la reclamación, ¿deberías siempre poder hacer GET de ese subrecurso? ¿Y si no tiene sentido funcional?

    ¿Un POST /reclamaciones/123/validar debería permitir siempre un GET sobre la validación?

  2. Buenas Prácticas para diseñar una API RESTful-pragmatic (Parte II): | Un poco de Java Says:

    […] Siguiendo con las buenas prácticas RESTful Buenas Prácticas para diseñar una API RESTful-pragmatic (Parte I) […]


Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

A %d blogueros les gusta esto: