Header Ads Widget

Ticker

6/recent/ticker-posts

4 API que hacen muy bien la experiencia del desarrollador

 

La experiencia del desarrollador es un componente vital del diseño de API . La mejor experiencia de desarrollador dará como resultado una API mejor, más sólida y más útil y, por extensión, una experiencia de usuario final mejor, más sólida y más útil.

Si bien la experiencia del desarrollador es algo muy subjetivo que depende en gran medida del consumidor desarrollador , existen algunos elementos positivos recurrentes que comparten las API exitosas con una buena experiencia.

En este artículo, vamos a discutir exactamente eso. Describiremos cuatro cualidades que debe tener una API como parte de una experiencia integral de desarrollador y buscaremos cuatro API web  específicas que cuentan con estas cualidades.

Qué hace que una buena experiencia de desarrollador

Como ya se ha dicho, hay elementos subjetivos de cada API que un desarrollador puede encontrar más útiles que otro desarrollador. Dicho esto, hay algunas cualidades objetivas por las que las API deben esforzarse.

Comunicación

La principal de estas cualidades es ser comunicativo. Una API es tan buena como sus implementaciones apalancadas; en otras palabras, la mejor API del mundo no tiene valor si no se puede implementar. En consecuencia, una buena API debe contar con documentación y ejemplos de código completos y comunicativos .

Dicha documentación debe explicar claramente las implementaciones comunes en una variedad de lenguajes, así como discutir el funcionamiento interno de la API en términos de funcionalidad expuesta que podría ser necesaria.

Una API comunicativa debería:

  • Proporcione métodos de educación para una variedad de estilos de aprendizaje que documenten funciones comunes y casos de uso.
  • Presume de suficiente material de referencia sin depender demasiado de él.

Sensibilidad

Aunque la documentación es muy valiosa, la API en sí debería poder responder a la entrada en sí misma, en lugar de exigir que un desarrollador utilice una hoja de búsqueda o una tabla de referencia. Una API que sea receptiva, entonces, debe dejarse claras sus funciones para el desarrollador cuando la utilice, exponiendo fallas, errores y problemas a medida que surjan.

Una API receptiva debería:

  • Permita que las funciones y errores de la API se entiendan sin exigir un uso extensivo de materiales de documentación.
  • Comunicarse en lenguaje sencillo con el usuario y su sistema, evitando confusiones y complejidades innecesarias.

Interactividad

Una cualidad importante de una API y su documentación es que debe ser interactiva . Los usuarios y desarrolladores que utilizan una API no serán estáticos; tendrán preguntas y requisitos interactivos y dinámicos y, como tal, una API interactiva contará con una mayor facilidad de adopción, una mayor cantidad de comprensión y una mejor experiencia general para desarrolladores.

Una API interactiva debería:

  • Proporcione instalaciones de prueba en vivo para permitir la exploración y el descubrimiento. Esto se puede hacer utilizando parques infantiles o incluso entornos virtualizados .
  • Permita que los consumidores desarrolladores interactúen con el sistema directamente, en lugar de aprender sobre el sistema y luego utilizarlo.

Guia

La documentación es una cosa, pero la orientación es un concepto completamente diferente. Ser capaz de predecir casos de uso comunes y discutir la base del código en su totalidad es extremadamente valioso, ya que revela la mente del desarrollador.

Si bien tener una base de referencia sólida es útil, no hace nada para exponer por qué las cosas funcionan de la manera en que lo hacen: no hay información sobre los procesos de pensamiento detrás de los casos de uso específicos. Un sistema basado en la guía conecta al proveedor de API directamente con el usuario desarrollador, exponiendo la intención, los conceptos de diseño y los propósitos detrás de cada solución.

Una API guiada debería:

  • Eduque al desarrollador sobre cómo funciona una API sin tomar su mano directamente a través de cada proceso. En otras palabras, debería enseñar, no instruir.
  • Proporcione una gran cantidad de recursos para que el usuario se acerque según lo requieran el tiempo y la función.

Heroku : una API comunicativa

Heroku es un ejemplo perfecto de API comunicativa. Su documentación es clara, actualizada y muy completa. La documentación en sí está dividida en secciones lógicamente divididas que van de la menos compleja a la más compleja, y cada sección progresa de la misma manera. Esto imita el camino de aprendizaje natural y, en consecuencia, hace que sea mucho más fácil comprender temas complejos en partes en lugar de tratar de obtener una comprensión holística desde el principio.

Es importante destacar que la documentación de Heroku es uno de los ejemplos más extensos de esta lista. Se proporciona una amplia documentación, incluidos ejemplos, para Node.js, Ruby, Java, PHP, Python, Go, Scala y Clojure, que cubre la gran variedad de lenguajes más populares para la base de usuarios de Heroku.

Todo esto se recopila en un centro de aprendizaje " que ayuda a enseñar algunas funcionalidades específicas de la API de Heroku en los lenguajes dados, lo que ayuda a los desarrolladores a localizar datos específicos relevantes para lo que quieren hacer. También hay una poderosa sección complementaria llamada " Referencia " que se centra principalmente en el material de referencia para el trabajo sobre la marcha. Si bien esto es excelente para los desarrolladores que crean su API, también es extremadamente poderoso para depurar sistemas e identificar problemas específicos.

Sin embargo, lo más importante es la sección Introducción " que se ofrece. La sección ofrece algunas piezas clave de código, explicaciones y sugerencias generales para implementar Heroku en su situación dada. Por todas estas razones, la API de Heroku es extremadamente comunicativa y cuenta con una experiencia de desarrollador de calidad .

El centro de desarrollo de Heroku ofrece una experiencia de desarrollo de calidad

Zalando : una API receptiva

La biblioteca Zalando implementa el manejo de errores IETF HTTP API como está estandarizado en RFC 7807.

Zalando es una API muy específica de función diseñada para implementar application / problem + json Content-Type, que se define en RFC 7807 . Este RFC es una implementación de una definición de "detalle de problema", que es una forma estandarizada de llevar detalles legibles por máquina para fallas y errores en la respuesta HTTP .

Lo que esto significa funcionalmente es que las API HTTP, y en este caso Zalando, pueden evitar la necesidad de realizar sus propias respuestas de error HTTP personalizadas y, en su lugar, utilizar una metodología estandarizada . De esta manera, Zalando es extremadamente receptivo, ya que el error es inmediatamente comprensible. No hay razón para buscar un código de error, verifique el material de referencia: la API responde al error y describe el error directamente.

Esto es extremadamente poderoso, y aunque el resto de la documentación puede ser algo complejo para aquellos que no están familiarizados con GitHub, el hecho de que la API describa sus propios errores es enormemente poderoso.

Marvel : una API interactiva

Marvel es una de las API más interactivas que podría pedir un desarrollador. Todos los aspectos de la API, desde la forma en que obtiene caracteres hasta la forma en que se llama una ID de cómic, se pueden probar directamente desde un panel interactivo de las llamadas públicas más comunes. El evaluador integra automáticamente su clave API, llenándola por usted para cada llamada de prueba.

Una vez que se realiza una llamada de prueba, se proporcionan un conjunto de notas de implementación, un modelo de clase de respuesta y un esquema de modelo, una serie de parámetros y una lista de códigos de estado de error. Este nivel de interactividad con las soluciones de prueba es poco común y la capacidad de probar directamente la API y probar las permutaciones es extremadamente poderosa por dos razones principales.

Primero, esto ayuda en el desarrollo de aplicaciones que utilizan la API de Marvel. Al exponer la funcionalidad de la API en un formato comprobable, el desarrollador puede comenzar a comprender la estructura y el esquema internos de la API y sus innumerables funciones. En general, esto mejora la experiencia de desarrollo, aumenta la confianza del código y disminuye la complejidad general.

En segundo lugar, esto ayuda a descubrir errores . Ser capaz de encontrar si el error ocurre internamente o como resultado de un parámetro dado es muy valioso y conduce a una API más segura que es más predecible, más confiable y más extensible.

Documentación de la API interactiva de Marvel

API de escala : una API guiada

Para ver un ejemplo de una API guiada, pasaremos a Scale API . Si bien Scale API tiene la parte estándar de páginas de documentación y ofertas, el verdadero atractivo aquí es que cada sección de documentación está acompañada de una barra lateral de explicaciones y ejemplos extensos . Si bien la documentación, al igual que la API, es bastante espartana, el hecho de que cada función esté bien explicada es extremadamente útil y guía al desarrollador hacia la funcionalidad esperada.

Los ejemplos de código en la columna de la derecha ayudan a guiar la implementación de la API de escala

Sin embargo, incluso más importante que la explicación de la función básica es la inclusión de lo que se puede esperar con una mala respuesta . Al delinear cómo se ve una mala respuesta y lo que puede esperar el desarrollador, los usuarios obtienen una comprensión sistémica sobre la cual desarrollar.

También debe indicarse que el portal de desarrolladores de Scale es estéticamente agradable . Si bien el aspecto de la documentación no es necesariamente un factor determinante de la calidad, cuando la documentación en sí es de alta calidad, un buen diseño gráfico solo refuerza la confianza y fomenta la conversión. La documentación se presenta de una manera muy hermosa y está organizada de manera lógica . Esto resulta en una gran experiencia, casi divertida.

Conclusión

En la prisa por proporcionar sistemas más complejos, interesantes y útiles, a menudo olvidamos que la experiencia del desarrollador es una gran parte de esto. Ser capaz de proporcionar documentación extensa y bien formada es de vital importancia. Más que eso, poder brindar dicha documentación en un formato único que agregue valor a la experiencia del desarrollador lo es aún más.

Si bien no necesariamente tiene que hacer todo lo que se indica en este artículo, tomar incluso una pequeña pista de estos ejemplos puede conducir a un mejor producto, una mejor experiencia y un mejor resultado final en general.

¿Qué crees que hace una buena experiencia de desarrollador? ¿Hay alguna API que brille como un ejemplo de oro? ¡Háganos saber en los comentarios a continuación!

Publicar un comentario

0 Comentarios