Características que debe tener una API

No es ninguna novedad dar la importancia que tienen las APIs en el desarrollo de negocio de las empresas. Tanto es así que se creó una denominación ad hoc para ello: economía API. De ahí que impulsar una cultura de buenas prácticas en el diseño de interfaces de programación de aplicaciones sea una obligación para compañías y desarrolladores. Es recomendable crear productos útiles, reutilizables y abiertos.

Como casi todos los productos de desarrollo, el código y el uso correcto del lenguaje de programación es un tema especialmente complejo. En muchas ocasiones son necesarios parches para mejorar el funcionamiento y eso provoca que, a medida que la API soluciona problemas en primer término, también se convierta en un producto más sucio, más complejo de usar, menos práctico. Esto pretende ser un código de buenas prácticas para los desarrolladores de APIs.

Una API fácil de usar y de aprender

Si una API no es fácil de usar y su adopción por un desarrollador no es intuitiva, la API no cumplirá con su cometido: captar clientes y expandir la influencia de una empresa más allá de las cuatro paredes de su oficina. No tiene sentido desarrollar una API que no es un tentáculo, una extensión de los valores, del talento para dar servicio y generar ingresos. En ese camino, la primera meta es que el desarrollador llegue lo antes posible a una implementación básica de la API.

●  La API es un instrumento, no una meta en sí misma: es preferible utilizar formatos conocidos y habituales como JSON que inventar la rueda. O seguir los pasos más racionales a la hora de desarrollar una API REST o SOAP.

●  Dar soporte para la corrección de errores: los desarrolladores pueden informar de fallos y posibles mejoras en una API si se genera un espacio para feedback. Así se puede perfeccionar la API y, al mismo tiempo, generar comunidad.

Si no es estable, es un problema

Una de las peores pesadillas para un desarrollador es una API que cambia continuamente. Las mejoras están bien, pero a veces se corre el riesgo de que vayan en contra de la propia estabilidad del servicio. Sobre todo si no existe la posibilidad de mantener sin cambios las versiones previas de la propia API. Eso provocó que en 2011, la interfaz de desarrollo de aplicaciones de Facebook fuera calificada como la peor API del mercado para la comunidad de desarrolladores. Una de las razones: los cambios continuos en la herramienta sin previo aviso.

Para evitar esos problemas, puede considerarse como una buena práctica en la mayoría de ocasiones el uso de un control de versiones en la API. Normalmente mediante la creación de distintas URLs por cada proceso de incorporación de nuevas características y su impacto en las aplicaciones de terceros. Eso genera también un listado de versiones con fecha y novedades en cada caso. Sucede, por ejemplo, con servicios como Microsoft Azure y Amazon Web Services. 

En la misma línea ha trabajado Facebook desde 2011, introduciendo un sistema de control de versiones más razonable para la comunidad de desarrolladores. En ese procedimiento, cada desarrollador sabe de antemano que habrá cambios en la API cada dos años, con fechas ya publicadas: la versión 2.3 se publicó el 25 de marzo de 2015 y está prevista su expiración en agosto de 2017. El cuadro siguiente es un ejemplo de cómo es el proceso de versiones de las APIs y los SDKs dentro de Facebook: 

No hay nada como algo seguro

El tema de la seguridad siempre es complejo. Tanto es así que ya hemos hablado en BBVAOpen4U de su enorme importancia y el papel que juegan los protocolos OAuth y OAuth2 en la necesidad de desarrollar APIs seguras en su uso por terceros. Los procesos de autenticación deben ofrecer las máximas garantías sin dificultar en exceso el acceso al servicio por parte de otras compañías.

OAuth 2 es un protocolo relativamente sencillo de implementar con bibliotecas en numerosos lenguajes de programación: PHP, Java, Python, Scala, Objective C, Swift, Ruby, JavaScript, Node.js o .NET. Es cuestión de entrar y escoger la que se desee. Lo que permite el protocolo OAuth 2 basado en la asignación de tokens de acceso seguro para la identificación de cada usuario es evitar ataques CSRF (Cross-Site Request Forgery – Falsificación de petición en sitios cruzados), un tipo de vulneración cada vez más frecuente basado en el uso de cookies para la identificación de usuarios. Añadir temporalidad a los tokens de acceso añade aún más solidez.

Las APIs que basan su seguridad en un protocolo de token de acceso lo que hacen es identificar a cada cliente que hace una petición HTTP mediante ese token que, previamente, ha sido almacenado en el lado del cliente (navegador) con JavaScript. En este artículo de Carlos Azaustre se explica a la perfección el proceso de token.

Cuando uno desarrolla una aplicación, el público objetivo es el usuario medio. El uso del producto debe ser claro, sencillo, intuitivo… Cuando se diseña una API, el público objetivo es un programador, un profesional con conocimientos técnicos. Aunque eso es así, la calidad de la interfaz final no solo depende del producto, también de la documentación que explica cómo hacer un mejor uso de él. Aunque ese usuario final tenga conocimientos técnicos, una buena documentación es clave.

Una de las APIs mejor valoradas hoy en día es la de Stripe, una pasarela de pagos online que compite en el mercado con PayPal o Braintree, por poner dos ejemplos. La razón fundamental por la que Stripe tiene una gran acogida entre la comunidad de desarrolladores es su interfaz de desarrollo de aplicaciones. Y uno de sus puntos fuertes es la documentación, que se basa en dos pilares esenciales:

●  Cada método de la API se documenta en varios idiomas y se utiliza un lenguaje sencillo, claro, sin excesiva jerga técnica. Es totalmente accesible.

●  No solo contiene información sobre especificaciones de la API, sino también tutoriales prácticos bien documentados sobre cómo enfrentar cada trabajo.