Header Ads Widget

Ticker

6/recent/ticker-posts

Cómo impulsar la adopción de API con buenas prácticas de documentación

 

Hombre de negocios exitoso sentado sobre una pila de libros que

Si bien casi todos parecen estar de acuerdo en que la documentación es de importancia clave al lanzar una API, se dice poco sobre cómo puede afectar realmente la adopción de la API. Jeffrey Hammond , analista principal de Forrester, afirma que "los patrones de adopción se están desplazando hacia los desarrolladores", lo que les da el poder de "bloquear o ayudar a la adopción de software". Esto significa que una manera importante de persuadir a los tomadores de decisiones para que elijan su software sobre el de sus competidores es ganarse la confianza de los desarrolladores.

Una de las mejores formas de aumentar el conocimiento y el interés de los desarrolladores en su producto es hacer que su API se pueda utilizar de la manera más inmediata posible. Esto comienza con la documentación.

¿Cómo afecta la documentación de la API a la adopción?

La documentación juega un papel central en la forma en que los desarrolladores perciben una API. Una documentación deficiente es a menudo una señal de una API mal mantenida, una que los desarrolladores intentarán evitar a toda costa. Cuanto más centre la documentación de su API en los desarrolladores, más aumentará su confianza y mejorará su experiencia.

Experiencia de incorporación

Empiece por la primera impresión. Un desarrollador no debería tardar más de cinco minutos en comprender su API y comenzar a usarla. La única forma de hacer que esto sea una realidad es proporcionar una experiencia de incorporación simplificada y concisa. La documentación debería llevar rápidamente a los desarrolladores a una etapa en la que ya estén usando la API con poco o ningún esfuerzo.

Una forma posible de hacer que esto suceda es crear un "entorno de caja de arena", donde los desarrolladores pueden jugar con la API sin llegar a afectar sus servidores de producción. Esto le permite ofrecer un proceso de registro mínimo, preguntando solo lo que realmente se necesita en lugar de un proceso de registro prolongado que puede alejar a muchos desarrolladores.

Una buena documentación debería informar claramente a los desarrolladores sobre lo que deben hacer para empezar y cómo hacerlo. Si su API funciona con tokens de API, genere uno sobre la marcha y deje que los desarrolladores lo utilicen de inmediato. Si usa OAuth, proporcione información falsa del consumidor e incluso un token de acceso , para que los desarrolladores puedan comenzar a realizar llamadas a la API de inmediato.

Recuerde que este es solo el primer paso de participación y los desarrolladores aún están evaluando su API. Debe dejar que experimenten tanto como sea posible, pero sin comprometer sus sistemas de producción o cualquier información real del usuario.

El poder de experimentar

Para permitir que los desarrolladores experimenten con su API, puede seguir cualquiera o una combinación de las siguientes estrategias:

  1. Ofrezca una consola API : este es el mínimo que debe ofrecer como herramienta de experimentación. Con una consola de API, se anima a los desarrolladores a probar inmediatamente lo que ven en la documentación y ver que se realizan llamadas de API reales.
  2. Ofrezca un SDK : publique un SDK de código abierto en tantos lenguajes de programación como utilicen sus desarrolladores de destino. Proporcione documentación completa del SDK y facilite la instalación y la configuración. Las formas populares de distribuir SDK incluyen npm para Node.js , Packagist para PHP , RubyGems para Ruby y PyPI para Python .
  3. Publique tutoriales : comience con una Guía de inicio rápido y siga con tutoriales que les muestren cómo implementar casos de uso interesantes con su API. Proporcione fragmentos de muestra utilizando los SDK en tantos idiomas como sea posible, para que los desarrolladores puedan simplemente copiar y pegar el código y comunicarse con su API con el mínimo esfuerzo.

Al seguir este enfoque, ofrecerá una documentación rica y completa con todas las herramientas que un desarrollador necesita para comenzar de inmediato. Los desarrolladores podrán elegir sus lenguajes de programación favoritos y seguir sus tutoriales sobre cómo implementar los casos de uso específicos que están buscando.

Construir todo esto desde cero no es tarea fácil. La documentación es algo que necesita mucho enfoque en los detalles y debe reflejar continuamente los últimos cambios de API. Nuestro consejo es seguir siempre los estándares de la industria y utilizar métodos y herramientas probados.

Herramientas que le ayudan a crear una excelente documentación

Entre todas las herramientas relacionadas con API, la documentación es probablemente el área que muestra el mayor crecimiento. Esto es particularmente interesante porque la documentación es tradicionalmente algo a lo que los desarrolladores prestan poca atención cuando lanzan código. En la actualidad, existen varios estándares y herramientas que reducirán drásticamente el tiempo de implementación de la documentación.

Swagger , por ejemplo, es una cadena de herramientas de código abierto que le permite crear fácilmente documentación interactiva. Apigee está usando Swagger en su kit de herramientas Apigee-127 . Apigee-127 es un kit de herramientas de primer modelo para crear API ricas de clase empresarial que se ejecutan en cualquier proveedor de PaaS que admita Node.js. Para usar el kit de herramientas, comience modelando su API con un editor Swagger incorporado y, a partir de ahí, su código API se genera automáticamente.

RAML , o RESTful API Modeling Language, es una especificación y un conjunto de herramientas que le permite modelar su API y proporcionar documentación a partir de ella. Ha ido ganando mucha adopción en el espacio empresarial, probablemente porque sigue tres principios fundamentales: es legible por humanos, simple y se puede dividir por patrones.

Con un enfoque aún más humano, API Blueprint le permite escribir su especificación API en Markdown y servirla como su documentación. El mismo archivo Markdown también es utilizado por una variedad de herramientas para generar código, ejecutar pruebas de integración y depurar la API. La cantidad de formas en que se puede manipular API Blueprint es impresionante, ya que hay más de 15 herramientas que pueden convertirlo a otros formatos.

Read the docs es un servicio de documentación alojado que le permite escribir documentación sin preocuparse por alojarla usted mismo o mantener sus cambios. Sin preocuparse por estos detalles, simplemente puede concentrarse en la calidad de la documentación. Al final, esto es lo que más importa. Además, una característica interesante es su soporte de webhook . Esta característica le permite conectar fácilmente su sistema de control de versiones (por ejemplo, GitHub ) e iniciar una actualización de la documentación automáticamente cada vez que realiza una confirmación.

Conclusión

Dado que la documentación es cada vez más el principal impulsor de la adopción, lo que abre el camino para que los desarrolladores comprendan y aprecien su API, debería ser lo más importante en su agenda. Según numerosas autoridades en el ámbito de las API , los desarrolladores están desempeñando un papel cada vez más importante en el proceso de toma de decisiones al considerar un nuevo producto o servicio.

La documentación es la cara de su API y es lo primero que ven los desarrolladores cuando llegan a su sitio web. Debe hacer que su experiencia sea lo más fluida posible y ofrecer un proceso de participación que pueda comenzar con una incorporación fácil y rápida, y llevarlos a experimentar su API mediante la implementación de sus casos de uso preferidos. Debería considerar ofrecer SDK en lenguajes de programación populares y una variedad de tutoriales y guías para que la implementación de la integración sea muy sencilla.

Al final, si la opinión de los desarrolladores sobre tu API es positiva, recomendarán tu producto sobre el de la competencia. ¡El resultado es que ganarás nuevos clientes!

¿Tiene más ideas o ejemplos de formas de mejorar la documentación de API y aumentar la adopción? Si es así, compártelo en un comentario aquí o háznoslo saber en Twitter o Facebook .

[Nota del editor: las API nórdicas son una publicación independiente y no han sido autorizadas, patrocinadas ni aprobadas por ninguna de las empresas mencionadas en este artículo; sin embargo, Apigee ha sido anteriormente un socio de eventos de API nórdicas.]

Publicar un comentario

0 Comentarios