Las 4 reglas de oro para el mejor Web API Design

La mayoría de veces cuando diseñas soluciones, van orientadas a usuarios finales que no son programadores o que carecen de la sofisticación técnica necesaria. Y por lo general, si has hecho bien tu trabajo, no recibirás ninguna queja.

No obstante, si por el contrario desarrollas APIs, interfaces orientadas a programadores que no conoces, éstos tendrán la sofisticación técnica necesaria (o al menos creerán que la tienen) para sacar cualquier pequeño fallo en tu software. Serán tan críticos con tu API como tú serías con la suya.

Ya sea por mal diseño, falta de documentación, volatilidad, bugs sin resolver o, en algunos casos, todas las anteriores; las APIs Web son a menudo difíciles de usar por otros usuarios. Por ello, te traemos la guía definitiva para asegurar que tus APIs Web son limpias, están bien documentadas y son fáciles de usar

Cualquier desarrollador sabe lo fácil que es que un proyecto se convierta en código espagueti, y las APIs Web no son menos propensas a ello. Pero siguiendo estas 4 reglas de oro, diseñar APIs Web que los usuarios disfruten utilizando y los developers disfruten creando es más fácil de lo que crees. Te las contamos a continuación.

Regla 1: Documenta

¿Odias documentar? Lo entendemos, pero si lo ves desde el punto de vista del usuario, estamos seguros de que documentar te parecerá más agradable que tener que trabajar con APIs sin documentar. La conclusión es que, si quieres que alguien utilice tu API, documentar es esencial. Es lo primero que verán los usuarios, así que en cierto modo es como el papel de regalo. Si la presentas bien, es más probable que la gente use tu API y aguante cualquier idiosincrasia. Entonces, ¿cómo se documenta bien?

La parte relativamente fácil es documentar los propios métodos de la API; o puedes escribir tú mismo algo que introspeccione tu API, endpoints y funciones, y genere la documentación correspondiente. Pero lo que separa una documentación mediocre de una gran documentación es la inclusión de ejemplos de uso e, idealmente, tutoriales

Por ejemplo, si los desarrolladores de Twilio enumeraran cada clase, cada método y cada posible respuesta a su API, pero no se molestaran en mencionar que puedes enviar SMS, rastrear una llamada o comprar un número de teléfono a través de su API, el usuario de la API tardaría mucho tiempo en encontrar esa información y comprenderla de forma coherente. Si no pueden tener una integración básica con tu API en 15 minutos, tu trabajo no está bien hecho.

Para algunos ejemplos notables de documentación detallada, echa un vistazo a Twilio, Django y MailChimp.

Regla 2: Estabilidad y consistencia

Digamos, por ejemplo, que su API es accesible a través de la URL http://myapisite.com/api/widgets y proporciona su respuesta en formato JSON. Aunque esto puede no parecer un problema a primera vista, ¿qué ocurre si tienes que modificar el formato de la respuesta JSON?

Lo mejor que puedes hacer es planear por adelantado y versionar tu API desde el principio, incorporar explícitamente un número de versión en la URL (por ejemplo, http://myapisite.com/api/widgets?version=1 o http://myapisite.com/api/widgets/v1) para que los usuarios puedan confiar en que la versión 1 funciona y puede actualizarse a cualquier versión posterior cuando estén preparados para hacerlo. Si tienes que retirar una versión anterior, avisa con tiempo y ofrece algún tipo de plan de transición.

Cualquier cambio en el formato del output o en los tipos de datos soportados debería dar lugar a una nueva versión actualizada. En general, es aceptable mantener la misma versión si todo lo que estás haciendo es añadir claves al output, pero para evitar problemas, te recomendamos que actualices a una nueva versión cada vez que se produzcan cambios en el output.

Además, tus APIs deberán ser estables en el tiempo, por lo que debes manejar parámetros comunes de forma global dentro de tu API y utilizar la herencia o una arquitectura compartida para reutilizar las mismas convenciones de nomenclatura y manejo de datos de forma consistente en toda tu API.

Regla 3: Seguridad ante todo

La seguridad es un elemento clave para los servicios web, pero muchos desarrolladores dificultan su uso innecesariamente. Como proveedor de la API, deberías ofrecer ejemplos prácticos de cómo autenticar y autorizar el acceso a tu API. Tu objetivo es que el usuario no tenga que escribir código o que tarde menos de 5 minutos en hacerlo.

Para la mayoría de las APIs, lo mejor es una autenticación simple basada en tokens, en la que el token es un hash aleatorio asignado al usuario y que se puede restablecer en cualquier momento si hace falta. Permite que el token se pase a través de POST o un encabezado HTTP. Elige un token seguro, no un identificador numérico corto. Lo mejor es algo irreversible. 

Regla 4: Facilita su adopción

Esta es realmente la regla más importante, y se basa en todas las anteriores. Como hemos mencionado en la regla de documentación, pon a prueba tu API con gente que no esté familiarizada con ella. Asegúrate de que pueden realizar al menos una implementación básica de tu API, aunque sea siguiendo un tutorial, en alrededor de 15 minutos.

Aquí te dejamos algunas recomendaciones específicas para facilitar la adopción de tu API:

  • Asegúrate de que otros usuarios puedan siempre implementar tu API por primera vez sin problemas.
  • Hazlo simple y no utilices métodos de autenticación dudosos y nunca vistos antes, lo que quieres es que se pueda usar fácilmente.
  • Ofrece librerías de lenguaje específicas: puedes utilizar herramientas automáticas para que la generen por ti, como Alpaca o Apache Thrift.
  • Automatiza el proceso de inscripción y tras completarlo dirige al usuario inmediatamente a tu tutorial.

Si sigues los consejos de este artículo, te asegurarás de que tu API web sea limpia, esté bien documentada y sea fácil de usar. Este tipo de APIs son poco frecuentes y, por tanto, tienen muchas más probabilidades de ser ampliamente adoptadas y utilizadas.

Publicaciones Similares

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *


El periodo de verificación de reCAPTCHA ha caducado. Por favor, recarga la página.