Unas cuantas buenas prácticas cuando hablamos de APIs REST

De una A, dame una P, dame una I, APIIIIIIII... si, venga, va, la imagen es totalmente gratuita, lo reconozco.

Las APIs están de moda y las APIs REST ya ni digamos. Es por eso que navegamos mucho buscando bibliografía y referencias para realizar buenas APIs RESTful y no esas chustas que muchas veces nos encontramos y con las que otras tantas tenemos que luchar y bregar. Hace unos días nos topamos con las sugerencias de un desarrollador de APIs llamado Pierre-Olivier Bourgeois para construir buenas APIs, y como las suscribo al 100% pues nada mejor que compartirlas aquí, en Genbeta Dev.

• Versionar tu API, que así puedes updatear manteniendo la compatibilidad con las versiones anteriores. Tu piensa que si lo hace GitHub, por algo será.

• Usar nombres en vez de verbos...

• ... y a ser posible siempre en plural. Es decir, /products, no /getProducts, no /product.

• Las llamadas GET y HEAD siempre seguras, es decir, que no alteren el estado.

• Usa recursos anidados (/products/5/comments) y permite la paginación, alma de cántaro, no devuelvas siempre cientos de miles de resultados de golpe.

• Usa los códigos HTTP correctamente (he aquí la lista de los mismos).

• Y si la llamada es errónea, devuelve un error claro y bien formado. Te pitarán mucho menos los oídos, te lo aseguro.

Yo añadiría una más de mi cosecha, aunque muy obvia: documenta, documenta y documenta. Documentación clara, extensa y accesible. Que a veces parece que cobran por la palabra escrita en la documentación.

¿Qué más recomendaciones de buenas prácticas en la construcción de APIs REST se os ocurren? Los comentarios están abiertos y deseosos de recibir vuestras ingeniosas e interesantes propuestas.

Pd: ya que estamos, aprovecho aunque no venga a cuento: REST >>>>>>>>>>>> SOAP.

Vía | Pierre-Olivier Bourgeois
Imagen | Klearchos Kapoutsis