¿Qué es ser developer friendly en el mundo de las APIs?

Los 3 principios de usabilidad

Developer friendly

Muchas veces decimos o hablamos de que una cosa u otra es developer friendly, pero, ¿qué es ser developer friendly de verdad?

Debemos pensar que los developers no dejamos de ser usuarios de herramientas, de programas o de APIs, y que deben cumplir los principios de usabilidad, como cualquier otra.

Por ello, es importante conocer los principios de usabilidad que aplican a los developers a la hora de consumir las APIs. A continuación se enumeran y definen dichos principios:

- Facilidad de aprendizaje

- Flexibilidad

- Robustez

1. Facilidad de aprendizaje

Si una API se parece a un estándar de mercado que el developer ya haya usado, le va a ser más fácil de utilizar. También si todas las APIs de una organización se parecen, puesto que una vez utilizada una no tendrá que volverse a aprender el formato.

Además, una de las cosas más complejas es la seguridad. Si la API utiliza estándar de mercado puede facilitar esta parte.

Para APIs complejas es mejor proporcionar a los developers SDKs, que ayuden a su integración.

Y por supuesto, una buena documentación de la API, enriquecida con ejemplos y una herramienta de try-out, ayudan al developer.

2. Flexibilidad

A menudo nos encontramos con APIs muy poco flexibles, que devuelven una gran cantidad de datos y con pocos niveles de datos de respuesta. Esto hace que, en ocasiones, el consumidor tenga que implementarse un backend para poder agrupar esta información.

A continuación se detallan unos parámetros especiales que estamos seguros que ayudarán a tu API:

$expand

Permite devolver en las respuestas varios niveles de información. Así, el usuario no tendrá que realizar una consulta por cada item. Por ejemplo, en una consulta de usuarios con pólizas, podríamos obtener ambas informaciones de una vez.

$select

Permite filtrar los atributos al devolver por la API. Por ejemplo, si mi usuario posee 50 atributos (lo más normal), me permite devolver sólo el nombre y apellidos.

$page, page_size, $order_by

Estos parámetros permiten paginar las respuestas, y sobre todo, lo más importante, ordenar la información. Muchas veces los developers obtienen todos los datos de una API sólo porque la ordenación no es la que necesitan.

$query

Permite hacer operaciones más complejas, como in, OR... todo esto utilizando el lenguaje de consultas de MongoDB

3. Robustez

La mayor parte de las APIs no están bien probadas. No se han probado todos los códigos de error, ya sea por falta de tiempo o bien porque no estaban definidos en ninguna parte.

Testear bien una API, con los formatos de entrada / salida, códigos de respuesta, rangos de valores.. es importantísimo para que a un developer le de confianza.

Para esto es aconsejable utilizar herramientas como Openapi2postman, que te permite generar el conjunto mínimo de pruebas.

En el este proyecto de Github puedes encontrar el código.

¿Quieres que tus APIs sean Developer Friendly?

Contacta con nosotros

Contacta

Roles y procesos en un gobierno de APIs

#apis #procesos

Marco Antonio Sanz Molina Prados