5 reglas de oro para un excelente diseño de API web

¿Alguna vez te preguntaste "¿qué estaban pensando?" al integrar un servicio web a través de su API? Si no, has tenido mucha más suerte que yo.

Cualquier desarrollador de software sabe lo fácil que es dejar que un proyecto se convierta en código espagueti, y las API web no son menos propensas a resultar en una red enredada. Pero no tiene por qué ser así. En verdad, es posible diseñar excelentes API web que la gente realmente disfrutará usando y que usted también disfrutará creando. ¿Pero cómo? La respuesta a esa pregunta es de qué se trata esta publicación.

Perspectiva

La mayoría de las veces, cuando crea soluciones, diseña para usuarios finales que no son programadores o que, en general, no son técnicamente sofisticados. Les está dando una interfaz gráfica y, si ha estado haciendo bien su trabajo, ha obtenido una idea bastante buena de lo que necesitan que haga la interfaz.

Pero el desarrollo de API es diferente. Estás diseñando una interfaz para programadores , probablemente sin siquiera saber quiénes son. Y quienesquiera que sean, tendrán la sofisticación técnica (o al menos pensarán que tienen la sofisticación técnica) para señalar cada pequeño defecto en su software. Es probable que sus usuarios critiquen su API tanto como usted lo haría con la de ellos, y disfrutarán mucho criticándola.

Y ahí radica parte de la ironía, por cierto. Si alguien debe entender cómo crear una API web que sea fácil de usar, eres tú . Después de todo, eres un ingeniero de software al igual que los usuarios de tu API, por lo que compartes su perspectiva. ¿no?

Bueno, aunque ciertamente entiendes su perspectiva, no necesariamente compartes su perspectiva. Cuando está desarrollando o mejorando su API, tiene la perspectiva de un diseñador de API, mientras que ellos tienen la perspectiva de un usuario de API.

Los diseñadores de API generalmente se enfocan en preguntas como "¿Qué debe hacer este servicio?" o "¿Qué necesita proporcionar este servicio?" , mientras que los usuarios de API se centran en "¿Cómo puedo usar esta API para hacer lo que necesito?" , o más exactamente, "¿Cómo puedo gastar el mínimo esfuerzo para obtener lo que necesito de esta API?" .

Estas diferentes preguntas conducen a dos perspectivas muy diferentes. Como resultado, el requisito previo necesario para diseñar una gran API es cambiar su perspectiva de la del diseñador de la API a la del usuario de la API. En otras palabras, hágase continuamente las preguntas que naturalmente haría si fuera su propio usuario. En lugar de pensar en lo que puede hacer su API, piense en las diferentes formas en que puede necesitar o desear que se use y luego concéntrese en hacer que esas tareas sean lo más fáciles posible para los usuarios de su API.

Si bien esto puede parecer fácil y obvio, es sorprendente la poca frecuencia con la que las API parecen diseñarse de esta manera. Piense en las API que ha encontrado en su carrera. ¿Con qué frecuencia parecen haber sido diseñados con esta perspectiva en mente? El diseño de API web puede ser un desafío.

Entonces, dicho esto, procedamos y hablemos sobre las 5 reglas de oro para diseñar una gran API web , a saber:

1. Documentación
2. Estabilidad y Consistencia
3. Flexibilidad
4. Seguridad
5. Facilidad de adopción

Regla 1: Documentación

Documentación. Sí, estoy empezando aquí.

¿Odias la documentación? Bueno, puedo empatizar, pero póngase su sombrero de "perspectiva de usuario" y apuesto a que lo único que odia más que tener que escribir documentación es tener que intentar usar una API no documentada. Yo descanso mi caso.

La conclusión es que, si desea que alguien use su API, la documentación es esencial. Simplemente tienes que hacerlo bien. Es lo primero que verán los usuarios, por lo que, en cierto modo, es como el papel de regalo. Presente bien, y es más probable que las personas usen su API y toleren cualquier idiosincrasia.

Entonces, ¿cómo escribimos una buena documentación?

La parte relativamente fácil es documentar los métodos API en sí; es decir, solicitudes y respuestas de ejemplo, junto con descripciones de cada uno de los elementos en ambos. Afortunadamente, existen cada vez más herramientas de software que facilitan y simplifican la tarea de generar documentación. O puede escribir algo usted mismo que introspeccione su API, puntos finales y funciones, y genere la documentación correspondiente para usted.

Pero lo que separa una gran documentación de una documentación adecuada es la inclusión de ejemplos de uso e, idealmente, tutoriales. Esto es lo que ayuda al usuario a comprender su API y por dónde empezar. Los orienta y los ayuda a cargar su API en su cerebro.

Por ejemplo, si los desarrolladores de Twilio hicieran una lista de cada clase, cada método y cada posible respuesta a su API, pero no se molestaron en mencionar que puede enviar un SMS, rastrear una llamada o comprar un número de teléfono a través de su API, le tomaría mucho tiempo al usuario de la API encontrar esa información y comprenderla de manera coherente. ¿Te imaginas clasificar un árbol gigante de clases y métodos sin saber para qué se usaban, aparte de su nombre? ¿Suena terrible verdad? Pero eso es exactamente lo que hacen tantos proveedores de API, dejando sus API opacas para cualquiera excepto para ellos mismos. La guía para desarrolladores y API de Rackspace CloudFiles es uno de esos ejemplos; es difícil orientarse a menos que ya comprenda lo que están haciendo y lo que están proporcionando.

Por lo tanto, escriba tutoriales concisos que ayuden a que el desarrollador se ponga en marcha rápidamente, con al menos un esqueleto de lo que están tratando de hacer, y luego apúntelos en la dirección de la lista de funciones más detallada y completamente documentada para que puedan expandirse. en lo que tienen.

Una vez que haya terminado con su documentación, asegúrese de validar que tenga sentido para otras personas además de usted. Envíelo a otros desarrolladores en su red, no les dé más instrucciones que señalarles la documentación y pídales que sigan un tutorial o construyan algo realmente básico en aproximadamente 15 minutos. Si no pueden tener una integración básica con su API en 15 minutos, tiene más trabajo por hacer.

Para ver algunos ejemplos notables de documentación excelente y detallada, consulte Twilio, Django y MailChimp. Ninguno de estos productos es necesariamente el mejor en sus mercados (aunque todos son buenos productos), sin embargo, se distinguen por proporcionar parte de la mejor documentación dentro de sus mercados, lo que sin duda ha facilitado su amplia aceptación y participación en el mercado.

Regla 2: Estabilidad y Consistencia

Si alguna vez ha usado la API de Facebook, sabe con qué frecuencia desaprueban y reescriben por completo sus API. No importa cuánto respetes su cultura hacker o su producto, la suya no es una perspectiva amigable para los desarrolladores. La razón por la que todavía tienen éxito es porque tienen mil millones de usuarios, no porque su API sea excelente.

Pero probablemente no tenga el lujo de una base de usuarios y una participación de mercado tan gigantescas, por lo que necesitará tener una API mucho menos volátil, manteniendo las versiones antiguas en ejecución y con soporte durante un período de tiempo bastante largo. Tal vez incluso años. Entonces, con ese fin, aquí hay algunos consejos y trucos.

Digamos, por ejemplo, que se puede acceder a su API a través de la URL http://myapisite.com/api/widgets y proporciona su respuesta en formato JSON. Si bien esto puede parecer correcto a primera vista, ¿qué sucede cuando necesita modificar el formato de la respuesta JSON? Todos los que ya están integrados contigo se van a romper. UPS.

Por lo tanto, planifique con anticipación y cree una versión de su API desde el principio, incorporando 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 las personas puedan confiar en que la versión 1 funcione y puedan actualizar a cualquier versión posterior cuando estén listos para hacerlo. Si necesita eliminar gradualmente una versión anterior en algún momento, adelante, pero avise con suficiente antelación y ofrezca algún tipo de plan de transición.

Un buen esquema de URL incluirá versiones principales en la URL. Cualquier cambio en el formato de salida o en los tipos de datos admitidos debería dar lugar a una nueva versión principal. En general, es aceptable mantener la misma versión si todo lo que está haciendo es agregar claves o nodos a su salida, pero para estar seguro, cada vez que cambie la salida, cambie una versión.

Además de ser estables a lo largo del tiempo, las API deben ser coherentes internamente. He visto muchas API que cambian los nombres de los parámetros o los métodos de publicación de datos, según el punto final que se esté utilizando. En su lugar, debe manejar los parámetros comunes globalmente dentro de su API y usar la herencia o una arquitectura compartida para reutilizar las mismas convenciones de nomenclatura y el manejo de datos de manera consistente en toda su API.

Finalmente, debe registrar y publicar un registro de cambios para mostrar las diferencias entre las versiones de su API para que los usuarios sepan exactamente cómo actualizar.

Regla 3: Flexibilidad

Basura entra, basura sale (GIGO) es un mantra muy conocido para la mayoría de los programadores. Tal como se aplica al diseño de API web, este principio rector tiende a dictar un enfoque bastante rígido para solicitar la validación. Suena genial, ¿verdad? Sin desorden, sin problema.

Sin embargo, como en todo, debe haber cierto equilibrio. Como no es posible anticipar todas las formas en que los usuarios querrán emplear su servicio, y dado que no todas las plataformas de clientes son consistentes (es decir, no todas las plataformas tienen muy buen soporte JSON, una biblioteca OAuth decente, etc.), es bueno tener al menos cierto grado de flexibilidad o tolerancia con respecto a las restricciones de entrada y salida.

Por ejemplo, muchas API admitirán una variedad de formatos de salida, como JSON, YAML, XML, etc. al., pero solo admitirá especificar el formato en la propia URL. Con el espíritu de permanecer flexible, podría permitir que esto también se especifique en la URL (por ejemplo, /api/v1/widgets.json ), o también podría leer y reconocer un encabezado HTTP Accept: application/json , o admitir un variable de cadena de consulta como ?format=JSON , etc.

Y mientras estamos en eso, ¿por qué no permitir que el formato especificado no distinga entre mayúsculas y minúsculas, para que el usuario también pueda especificar ?format=json ? Ese es un ejemplo clásico de una forma de aliviar la frustración innecesaria del usuario de su API.

Otro ejemplo es permitir diferentes formas de ingresar variables. Entonces, al igual que tiene una variedad de formatos de salida, permita también una variedad de formatos de entrada (por ejemplo, variables POST simples, JSON, XML, etc.). Al menos debería admitir variables POST estándar, y muchas aplicaciones modernas también admiten JSON, por lo que esos dos son un buen lugar para comenzar.

El punto aquí es que no debe asumir que todos comparten sus preferencias técnicas. Con un poco de investigación sobre cómo funcionan otras API y a través del diálogo con otros desarrolladores, puede obtener otras alternativas valiosas que son útiles e incluirlas en su API.

Regla 4: Seguridad

La seguridad es, obviamente, una de las cosas más importantes para construir en su servicio web, pero muchos desarrolladores hacen que sea ridículamente difícil de usar. Como proveedor de API, debe ofrecer ejemplos utilizables de cómo autenticarse y autorizar al acceder a su API. Este no debería ser un problema difícil en el que un usuario final dedique horas a trabajar. Haga que su objetivo sea que no tengan que escribir ningún código o que les lleve menos de 5 minutos escribirlo.

Para la mayoría de las API, prefiero una autenticación simple basada en token, donde el token es un hash aleatorio asignado al usuario y puede restablecerlo en cualquier momento si se lo roban. Permita que el token se pase a través de POST o un encabezado HTTP. Por ejemplo, el usuario podría (y debería) enviar un token SHA-1 como variable POST o como encabezado en un formato como "Autorización: da39a3ee5e6b4b0d3255bfef95601890afd80709".

Además, elija un token seguro, no un identificador numérico corto. Algo irreversible es lo mejor. Por ejemplo, es relativamente simple generar un token SHA durante la creación del usuario y almacenarlo en la base de datos. Luego, simplemente puede consultar su base de datos para cualquier usuario que coincida con ese token. También podría generar un token con un identificador único y un valor de sal, algo así como SHA(User.ID + "abcd123") , y luego consultar cualquier usuario que coincida; por ejemplo, where TokenFromPost = SHA(User.ID + "abcd123") .

Otra muy buena opción es OAuth 2 + SSL. Debería usar SSL de todos modos, pero OAuth 2 es razonablemente simple de implementar en el lado del servidor, y hay bibliotecas disponibles para muchos lenguajes de programación comunes.

Si se supone que se puede acceder a la API que ha creado en un sitio web público a través de JavaScript, también debe asegurarse de validar una lista de URL por cuenta para el token. De esa manera, nadie puede inspeccionar las llamadas a su API, robar el token de su usuario y usarlo por sí mismo.

Aquí hay algunas otras cosas importantes a tener en cuenta:

• Funcionalidad de lista blanca. Las API generalmente le permiten realizar operaciones básicas de creación, lectura, actualización y eliminación de datos. Pero no desea permitir estas operaciones para todas las entidades, así que asegúrese de que cada una tenga una lista blanca de acciones permitidas. Asegúrese, por ejemplo, de que solo los usuarios autorizados puedan ejecutar comandos como /user/delete/<id> . Del mismo modo, todos los encabezados útiles que se envían en la solicitud del usuario también deben validarse con una lista blanca. Si está permitiendo encabezados de tipo de contenido, verifique que lo que el usuario envíe realmente coincida con una lista temporal de tipos de contenido admitidos. Si no es así, envíe un mensaje de error como una respuesta 406 No aceptable. La inclusión en la lista blanca es importante ya que muchas API se generan automáticamente o, en su lugar, se usa una lista negra, lo que significa que debe ser explícito sobre lo que no desea. Sin embargo, la regla de oro de la seguridad es comenzar con absolutamente nada y solo permitir explícitamente lo que desea.

• Protéjase contra la falsificación de solicitudes entre sitios (CSRF). Si está permitiendo la autenticación de sesión o de cookies, debe asegurarse de que se está protegiendo de los ataques CSRF. El Proyecto de seguridad de aplicaciones web abiertas (OWASP) proporciona una guía útil sobre las formas de evitar estas vulnerabilidades.

• Validar el acceso a los recursos. En cada solicitud, debe verificar que un usuario tenga realmente acceso al elemento específico al que hace referencia. Por lo tanto, si tiene un punto final para ver los detalles de la tarjeta de crédito de un usuario (p. ej., /account/card/view/152423 ), asegúrese de que el ID "152423" haga referencia a un recurso al que el usuario realmente está autorizado a acceder.

• Valide todas las entradas. Todas las entradas de un usuario deben analizarse de forma segura, preferiblemente usando una biblioteca conocida si está usando entradas complicadas como XML o JSON. No construyas tu propio analizador, o te encontrarás con un mundo de dolor.

Regla 5: Facilidad de adopción

Esta es realmente la regla más importante del grupo y se basa en todas las demás. Como mencioné durante la regla de documentación, pruebe esto con personas que son nuevas en su API. Asegúrese de que puedan ponerse en marcha con al menos una implementación básica de su API, incluso si solo sigue un tutorial, en unos minutos. Creo que 15 minutos es una buena meta.

Aquí hay algunas recomendaciones específicas para facilitar y facilitar la adopción de su API:

• Asegúrese de que las personas realmente puedan usar su API y que funcione la primera vez, todas las veces. Haga que personas nuevas intenten implementar su API de vez en cuando para verificar que no sea confuso de alguna manera a la que se haya vuelto inmune.

• Mantenlo simple. No haga ninguna autenticación elegante. No haga un esquema de URL personalizado loco. No reinventes SOAP, JSON, REST ni nada. Utilice todas las herramientas que pueda que ya se hayan implementado y sean ampliamente aceptadas, de modo que los desarrolladores solo tengan que aprender su API, no su API + 10 nuevas tecnologías oscuras.

• Proporcione bibliotecas específicas del idioma para interactuar con su servicio. Hay algunas buenas herramientas para generar automáticamente una biblioteca para usted, como Alpaca o Apache Thrift. Actualmente, Alpaca es compatible con Node, PHP, Python y Ruby. Thrift es compatible con C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi y más.

• Simplifique cualquier registro necesario. Si no está desarrollando una API de código abierto, o si hay un proceso de registro de cualquier tipo, asegúrese de que al registrarse, el usuario sea dirigido rápidamente a un tutorial. Y haga que el proceso de registro sea completamente automático sin necesidad de interacción humana de su parte.

• Proporcionar un excelente apoyo. Una gran barrera para la adopción es la falta de apoyo. ¿Cómo manejará y responderá a un informe de error? ¿Qué pasa con la documentación poco clara? ¿Un usuario poco sofisticado? Los foros, los rastreadores de errores y el soporte por correo electrónico son fantásticos comienzos, pero asegúrese de que cuando alguien publique un error, realmente lo aborde. Nadie quiere ver un foro de pueblo fantasma o una lista gigante de errores que no se han solucionado.

Resumen de la API web

Abundan los servicios web y sus API. Desafortunadamente, la gran mayoría son difíciles de usar. Las razones van desde un diseño deficiente hasta la falta de documentación, la volatilidad, errores no resueltos o, en algunos casos, todo lo anterior.

Seguir la guía de esta publicación ayudará a garantizar que su API web esté limpia, bien documentada y sea fácil de usar. Dichas API son realmente raras y, por lo tanto, es mucho más probable que se adopten y utilicen ampliamente.