spinner

¿Cómo no debo pensar cuando pienso en APIs?

La simplicidad es la máxima sofisticación (Leonardo da Vinci)

Una de las primeras fases cuando estamos creando una API es el diseño, pues será la fase en la que definiremos nuestro recurso principal o, lo que es lo mismo, nuestro objeto de negocio con las propiedades necesarias de nuestra funcionalidad. Estamos empezando pero ya en esta fase empieza a dificultarse el proceso, debido al enfoque que debe tener el recurso y a que esta puede sufrir muchos cambios. En este artículo veremos en qué puntos concentrarnos y, sobre todo, cómo no deberíamos pensar al crear un API.

Empecemos bien…¿Qué NO debo pensar al crear una API?

Al crear APIs generalmente las pensamos técnicamente, algo que, la verdad, no es que esté mal. No obstante, en mi experiencia, considero que debemos enfocarnos en que sea claro y fácil de usar para hacer más sencilla la vida de los consumidores.

También es importante alejarnos de la mentalidad de que una API son representaciones de bases de datos u objetos de nuestro backend. Del mismo modo, no debemos confundir las operaciones de creación, modificación y borrado con las que se realizan a ese nivel. Es importante tener en cuenta que, aunque se asemejen, no lo son, ya que realmente lo que estamos diseñando es un objeto de negocio.

Algunas razones por las que cambiar la mentalidad al hablar de APIs

  • La unidad que se maneja en las APIs es un recurso, algo que no es precisamente una representación de una tabla o un objeto técnico. Esto es así porque la información que compone un recurso puede estar distribuida en diferentes bases de datos o backends, e incluso estar formada por varias estructuras de datos que no aportan valor al negocio o consumidor. Ejemplos de esto pueden ser indicadores para procesos internos, como por ejemplo variables de auditoría, procesos batch o monitoreo de procesos que no concuerdan con el objeto de negocio de nuestra API.

 

  • El recurso debe estar compuesto por aquella información que le aporta valor al consumidor y es inherente a cómo esté compuesta la arquitectura/capa que implementa la API. Esto es porque al consumidor o negocio no le interesa qué arquitectura se maneja o cómo están distribuidos los servicios, tampoco si es monolítico ni si está siendo monitorizado o auditado. El servicio debe ser auto-descriptivo y sencillo.

Fuente: elaboración propia

¿Entonces cómo debo pensar?

Ya hemos visto algunas razones de por qué es importante cambiar la mentalidad con la que concebimos las APIs. Vamos a ver ahora algunos consejos sobre cómo debo pensar a la hora de crear una API.

Hay que tener claro que las APIs no son sólo un conjunto de endpoints, sino que en realidad son un producto que debe dar valor para los consumidores y, por consiguiente, para el negocio.

Esto nos cambia el enfoque totalmente, o debería hacerlo. No obstante, en nuestra vida diaria el mecanismo que seguimos se traduce en una frase: “¡Hemos desarrollado esta súperfuncionalidad! Y… ahora… ¿dónde están las personas que la quieren usar?”.

La verdad es que este enfoque pocas veces sirve (muy pocas). En su lugar deberíamos decir: “Las personas quieren esta súperfuncionalidad, entonces ¡la desarrollaremos!”

Ahora que sabemos la mentalidad que debemos practicar, nuestra perspectiva cambia y con ello también el flujo de feedback. El feedback no irá desde la API (nuestro producto) hacia los consumidores o negocio, sino que será al contrario: irá desde los consumidores hacia nuestra API (nuestro producto). Eso le dará mucho más valor porque sabremos lo que de verdad se quiere y se usará.

Lo podemos ver más claro en la siguiente imagen, en la que el feedback exterior se convierte en el producto y finalmente aporta valor al consumidor o nuestros usuarios finales.

Fuente: elaboración propia

Claves para dar el máximo valor a tus API

Vamos a ver algunas de estas claves:

1. Conocer el propósito de los servicios: Entender el servicio que estará en la API, lo que significa conocer y conservar su propósito, hacerlo accesible considerando su seguridad, privacidad y el interés de los usuarios finales.

2. Concentrarnos en consumidores: aunque el consumidor puede ser externo o interno es alguien que usará el servicio (que puede pagar o no por usarlo), pero sin duda es alguien que conoce el negocio y la funcionalidad, por eso el servicio debe:

• Ser auto-descriptivo, intuitivo y predecible

• Ser simple: fácil de aprender, fácil de implementar

• Tener bajo acoplamiento, evitar dependencias con otros endpoints

• Explorable para los consumidores y «descubrible» por las máquinas.

3. Buena experiencia de desarrollo: puede parecer que esto es simple pero es de lo más difícil. Imagínate, ¿sabes lo complicado que es que otro desarrollador entienda tu código? (seguro que sí).

Las APIs no tienen visibilidad sin documentación y si alguna funcionalidad no está incluida o está mal documentada es como si no existiera. Por eso, es importante que la documentación del servicio sea clara en cuanto a funcionalidad y propósito, algo que da un valor impresionante a la API, que es nuestro producto.

Siguiendo con esta línea, una vez leí una frase que me impactó, porque me resultó muy descriptiva. “Una API es casi tan buena como su documentación”. Por supuesto, aquí es importante no confundir cantidad con calidad, ya que la documentación debe tener claridad y es un punto que no debemos olvidar.

Así, cuando la experiencia que tiene el desarrollador es gratificante, es más sencillo comprender el propósito del servicio e implementarlo para crear nuevos productos a través de tu API.

Algunas conclusiones…

Cuando creamos una API siempre hay que tener en cuenta que esta es lo primero y que hay que tratarla como un producto. Ese valor se ve reflejado en las APIs cuando son fáciles de entender y de implementar, pero para ello hay que pasar por comprender la funcionalidad y obtener retroalimentación de los usuarios finales y del mercado, para conocer así qué es lo que se quiere y cómo debe evolucionar nuestra API.

Imagen: Shutterstock

Las opiniones vertidas por el autor son enteramente suyas y no siempre representan la opinión de BBVA Next Technologies.

¿Quieres saber que más cosas hacemos en BBVA Next Technologies?