WR 43: No discutas con tu API, ¡habla con ella!

Estamos en tiempo de vacaciones y en el newsletter dominical publicamos #CódigoPlayero.

¿Qué es esto? Pequeños tutoriales prácticos para programar al sol cosas que molan. Suscríbete y lo descubrirás.

Además tenemos activa por última semana la encuesta del oyente, Aún estás a tiempo de participar. :)

Esta semana en Fenómeno Mutante hablamos de por qué montamos nuestros propios negocios. Nos “abrimos las carnes” y te contamos nuestra historia.

¿Qué es una API? ¶

Escucha el episodio, pero si tienes dudas en este vídeo te cuento lo que es una API en 5 minutos.

¶

Suscríbete a mi canal de YouTube

Errores en el diseño de una API ¶

Te contaré mi experiencia de estos últimos meses trabajando con dos APIs. Una como cliente, consumiendo desde un servidor. Otra, justo al revés, siendo yo el que expone los datos de una web en forma de API.

Detecté algunos fallos, tanto en un sentido como en otro que quiero repasar contigo en el podcast. Pulsa el play de más arriba, esto es sólo un resumen.

Mensajes de error poco claros ¶

Es mejor un mal mensaje que la ausencia del mismo. Aunque esté sin traducir.

Evitemos las respuestas a peticiones con errores crípticos o de formatos dispares. Hay que ayudar al que consume la API a entender que está pasando.

Qué es una API

Uso de verbos en las URL’s ¶

Si vamos a traer información la ruta de la API no tiene que incluir el verbo “get”. Basta con que ese sea el método que usemos en la cabecera de la petición.

Evitemos en la medida de lo posible utilizar POST para todo.

Mal esquema de URL’s para la API ¶

Fruto de la improvisación o de utilizar lo que el backend nos ofrece, el esquema de las carpetas de las peticiones de la API puede no tener sentido.

Es mucho más fácil para el cliente tener una secuencia y organización lógica para que sea autoexplicativa.

Autenticación pobre o inexistente ¶

Los datos que provienen de una API, salvo que sea la de chistes de Chuck Norris, siempre son delicados y relevantes.

Pongamos nuestros recursos detrás de un sistema de autenticación y autorización, por sencillo que sea, para evitar problemas futuros.

Exceso de endpoints hechos a la medida ¶

Está muy bien trabajar a la medida de lo que necesita el cliente, pero un exceso de recursos disponibles para consultar la API puede ser contraproducente.

Es más código a mantener y si surgen por el efecto de “cajas apiladas en el trastero” tendremos una API difícilmente gobernable.

También hicimos cosas bien ¶

Una interfaz intermedia de pruebas y testeo independiente de plataforma: Postman
API autodocumentada
Usamos un formato JSON de formato claro y a la medida
Solo se cargan los datos necesarios
El idioma se pasa como cabecera (Accept-Lenguage)
El uso de Hypermedia para que la API tuviera enlaces de autodescubrimiento para saber si había más resultados (paginación)

Enlaces del programa ¶

Encuéntranos por en el canal de telegram t.me/webreactiva o en twitter como @webreactiva con referencias y recursos sobre cosas que seguro te interesan.