javisantana.com

Algunos consejos para diseñar un API

Cuando desarrollas un producto digital a menudo surge la necesidad (bueno, a veces surge sin haberla) de tener un API. Un API no deja de ser una forma clara de quitarte marrones de encima. Tú no vas a poder hacer toda la funcionalidad para todos los casos de uso, así que tiene sentido que otros la hagan por ti.

Por otro lado:

Después de la obvia pero necesaria introducción, os dejo aquí una serie de cosas que he aprendido durante 7 años diseñando, desarrollando y manteniendo un API (con millones de peticiones diarias)

Versionado

Si algo he aprendido en todos estos años, es que desde el mismo momento que un cliente desarrolla algo sobre tu API acabas de meter tu libertad entre barrotes. Recuerdas todos esos “lo dejamos así y ya lo cambiaremos”? Bien, no los vas a poder cambiar porque siempre hay algún cliente usándolo.

De ahí que tengas que tener un versionado del API desde el primer momento. No entro en el modelo técnico, da igual como lo hagas, pero hazlo.

Stripe tiene una serie de blogposts muy muy buenos sobre el tema, uno de ellos en su blog oficial y el otro en el blog de brandur del que deberías leerte cada artículo si estás desarrollando un API

Relacionado con el versionado:

Documentación

La documentación es producto. La documentación no es una cosa que está ahí y la revisas de vez en cuando.

La mejor forma de que una documentación sea producto (desde mi punto de vista, como todo lo que escribo aquí) es que sea una parte más del código, es decir, se testea, se despliega, se hacen code reviews. Por ejemplo, la documentación de airtable es viva, de hecho te dan a elegir con qué “tabla” ves los ejemplos de la documentación.

Por otro lado la documentación debería tener: introducciones, guías, tutoriales, ejemplos, documentación del propio API, FAQ, tags en stackoverflow, listas de correo, grupos de google… Recuerda que ahora la gente no programa, busca el ejemplo más cercano a lo que necesitan y los modifican.

Auth

Usa el sistema que quieras y más adecuado para tu caso de uso pero, salvo casos muy concretos, nunca dejes usar tu API sin pasar por un paso previo para obtener una credencial. Echad un ojo al cristo que ha montado google con el api de google maps que al principio no necesitaba ningún API key

REST o no REST

Aquí la tendencia es a hacer REST (y a discutir qué es REST y qué no lo es) pero a veces no encaja. Es cierto que da cierta familiaridad al desarrollador que lo está usando pero a veces tu modelo no encaja con REST, no fuerces la máquina, usa lo que encaje.

Clientes

Hacer clientes para python, javascript, ruby, rust, go, java…idealmente, si puedes hacerlos porque tienes recursos, hazlos (si no, mejor poco y bien que mucho y mal):

Por contra:

Mucha gente adopta la técnica “open source”. Los saco open source y la comunidad los mantiene. Tiene sentido pero también me causa ciertos dilemas morales.

No olvidemos cosas con OpenAPI, Postman, RunKit, CodePen y compañía que siempre ayudan.

API específica para UI o no

“Hemos creado un API para que lo use nuestro UI, publicamos ese API o creamos uno nuevo bien hecho”. Pasa en las mejores familias, lo habitual es que el interfaz sea un caso muy específico de tu API así que podría tener sentido tener un API paralelo.

Mi experiencia es que el API expuesta para el UI es API pública aunque no esté documentada, sobre todo porque seguramente hace algunas cosas que los desarrolladores quieren.

Por otro lado hay veces que tienes que tener más de una vista del API para diferentes clientes. Por ejemplo, es común tener un api diferente para móvil que para desktop depende del caso de uso.

Errores

Los errores deberían ser accionables y sinceros:

Más allá de los errores, que son fundamentales, los warnings suele ser muy informativos para avisar de ciertas cosas.

Límites

Si tu API no tiene límites te va a dar muchísimos problemas en cuanto tengas cierto tráfico. Siempre hay un cliente que hace alguna burrada y como estamos en entornos donde se comparten recursos, vas a morir.

Aquí hay un problema y es que en general no sabemos cuanto es capaz de tragarse nuestro backend (que este es otro tema para tratar largo y tendido) pero marcar unos límites mínimos sobre:

Buenos ejemplos son, por ejemplo, el de github o mapbox

Por otro lado esto te permite, no solo poner tener un SLA, sino que harás que tu equipo on-call duerma mejor y además les darás razones a tus comerciales para hacer upsell.

SLA

Los SLA son básicamente los padres por varias razones:

Y obviamente para medir el SLA tienes que poder medir cuando estás caído.

El meta API

Cuando llegas a un nivel necesitas poder tomar decisiones en función de lo que está pasando y para eso tienes que tener analítica. El problema es que la analítica suele ser complicada porque si tienes varios millones de peticiones al día en unos meses ya necesitas algo serio.

Por otro lado los clientes empiezan a querer tener dashboards y métricas de uso (sí, deberían tenerlas ellos, pero no las van a tener y además puedes cobrar por ellas) y los desarrolladores y soporte ahorrarán horas y horas intentando saber qué pasó hace 1 día con el cliente XXX.

Da igual lo que uses, kibana, cloudwatch recuerda que:

Si estás en este punto tal vez te interese hablar con nosotros.

Otras cosas sin un orden claro

Algunas API que me gustan

Si conoces algún API que creas que sirva de referencia y merezca la pena poner aquí, enviame un tweet, un correo o una pull request y cuéntame la razón.

Por último, obviamente estas cosas no se implementan de la noche a la mañana, ni todas aplican a todos los casos, ni lo que está aquí es todo lo que hay, de hecho, de la parte más importante, la del diseño del API, ni he hablado.