Header Ads Widget

Ticker

6/recent/ticker-posts

Elaboración de excelentes tutoriales de código API que reducen el tiempo de incorporación

 

Elaboración de excelentes tutoriales de código API

El éxito o el fracaso de un programa API se debe a varios factores: el valor comercial del producto o la plataforma que expone la API, la facilidad de uso de la API o la cantidad de formas en que se puede utilizar. Sin embargo, la clave para conseguir un programa de API correcto es deleitar al desarrollador asegurándose de que tenga lo que necesita para hacer su trabajo. En el corazón de este esfuerzo se encuentran ejemplos de código , libros de cocina y tutoriales de código.que proporcionan este conocimiento con el ejemplo. Un excelente tutorial que reduce el tiempo necesario para poner en marcha una API agrega enormes beneficios para todos los interesados: para el consumidor de API y su equipo de desarrollo, quienes informarán sobre lo buena que es la API y lo fácil que fue crear su software. integración, y también valor reputacional para el propio proveedor de API.

En esta publicación, analizamos lo que hace que un excelente tutorial de API y lo que se necesita para transferir su importante conocimiento de API a su comunidad de desarrolladores. Como una historia, que tiene un principio, un medio y un final, un tutorial de API tiene tres partes distintas que ayudan a crear una narrativa sobre cómo usar una API:

  • Establecer el contexto;
  • Explorando los detalles;
  • Creando una aplicación.

A lo largo de esta publicación, exploraremos cada una de estas partes, citando varios tutoriales de calidad que puede modelar al construir sus propias guías de desarrollo.

Establecer el contexto

En primer lugar, un tutorial de API debe asegurarle al lector que está en el lugar correcto: es probable que los visitantes comprendan lo que necesitan lograr funcionalmente, pero es posible que aún no sean conscientes de las implicaciones de la integración y es posible que no se den cuenta de todas sus API tiene para ofrecer.

Por ejemplo, al elegir entre las distintas API de Twitter , un desarrollador deberá elegir entre las versiones RESTful y de transmisión de la API. Alternativamente, diferentes API pueden tener diferentes modelos de seguridad y los desarrolladores deberán ser conscientes de cuál puede ser el impacto de implementar una API sobre otra.

Establecer el contexto significa dedicar palabras para explicar al lector la importancia de crear una integración con una API, el nivel de habilidad y el estado de aprovisionamiento requeridos, y qué tipo de comportamientos se deben exhibir. Aunque esta sección no será exhaustiva, debería incluir:

  • Refuerzo del tema : El tutorial primero debe reafirmar lo que hace la API y lo que el desarrollador puede lograr usando el tutorial, con la introducción de los temas tecnológicos centrales que se presentarán en todo el proceso, incluido el lenguaje de programación utilizado, el nivel de experiencia requerido y la seguridad. arquitectura. Por ejemplo, este tutorial en Instagram ejemplifica este punto al enfocar agudamente la mente en el objetivo en cuestión;
  • Requisitos de incorporación : el desarrollador debe saber qué se requiere para comenzar el tutorial. ¿Necesitan una clave API? ¿Está involucrada una cuenta de usuario? ¿Existe una cuenta de prueba genérica? ¿Hay números de tarjetas de prueba, números mágicos a la API de Twilio ? ¿Una caja de arena con un conjunto de datos completo? Las preguntas son obviamente específicas de la API en sí, pero deben ser en forma de una lista de verificación fácil de usar con enlaces a los recursos que explican o amplían cada punto de la lista o donde el desarrollador puede actuar sobre la información proporcionada. . Esta tutorial de integración de la API de Facebook de Appery demuestra bien el tipo de información requerida, con una serie de capturas de pantalla que describen cómo registrar una aplicación en Facebook (un requisito previo para realizar una llamada a la API). losLa guía de introducción a Braintree también proporciona un excelente ejemplo;
  • Comportamientos en tiempo de ejecución . Finalmente, el desarrollador debe conocer las restricciones que la API impone al uso, como la limitación de conexiones, las tasas de consumo o la aceleración del rendimiento . Proporcionar esta información antes de comenzar el tutorial asegurará que los desarrolladores comprendan cómo estos comportamientos afectarán el diseño de su aplicación y cómo mitigarlos. Nuevamente, no es necesario que el tutorial cubra los detalles en su totalidad, pero debe proporcionar enlaces a más información.

Armado con esta información, el desarrollador debe tener el contexto necesario para comenzar a explorar la API en detalle.

Consulte también: 7 ingredientes que conforman un excelente centro para desarrolladores

Explorando los detalles

Con el contexto establecido, es tentador sumergirse directamente en la creación de una solución y permitir que los desarrolladores comprendan la API a partir del código fuente de una solución construida. Sin embargo, si un tutorial de API va a lograr el objetivo de reducir el tiempo de incorporación, debe ser inclusivo y dirigirse a la mayoría de las audiencias; no solo aquellos con habilidades y capacidades para descifrar la información importante del código.

Más bien, ayude a los usuarios a comprender el código con una serie de declaraciones explicativas acompañadas de fragmentos de código que construyen una imagen completa de la integración de la API desde cero hasta una llamada API exitosa. Los fragmentos no tienen por qué equivaler a una aplicación funcional, pero si todos se reunieron, deberían equivaler a algo parecido a un paquete, clase o secuencia de comandos funcional (dependiendo de la tecnología que esté utilizando en el curso del tutorial) - construyendo hacia el solución completa discutida en la siguiente sección. Los desarrolladores con habilidades más avanzadas obviamente pueden saltarse la sección de exploración y pasar a la solución completa.

Los propios fragmentos deben presentar una serie de características importantes:

  • Explique qué paquetes o bibliotecas están involucrados : esto le dará al lector una mejor idea de lo que necesita comprender junto con la API o le permitirá correlacionarlos con alternativas que ya puede usar. Por ejemplo, si usa un paquete o biblioteca OAuth, explique brevemente por qué eligió ese paquete en particular y los beneficios que ofrece al desarrollador;
  • Atrévete a ser detallado : la mayoría de los desarrolladores escriben código y luego lo refactorizan para hacerlo lo más conciso posible: de hecho, es una de las cosas que generalmente pone una sonrisa en la cara de un desarrollador. Sin embargo, esta concisión puede ser un desafío para los desarrolladores junior: además, en el tutorial, hablará con desarrolladores que no tienen experiencia en el idioma en el que está escrito, pero necesitan usarlo como referencia para implementar su aplicación en su propio idioma de elección (aunque algunos proveedores de API como Twilio pueden proporcionar tutoriales en varios idiomas , no todos los proveedores de API tienen los recursos disponibles para hacer esto). Por ejemplo, si más desarrolladores pueden entender mejor la comprensión de una lista de Python a través de una sintaxis detallada, considere hacerlo:
# Less Pythonistic but easier to understand for a non-Python developer

verbose_payments_list = list()

for payment in payments:
    If payment.amount > 0:
        payments_list.append(payment)

# More Pythonistic approach:

terse_payments_list = [payment for payment in payments if payment.amount > 0]
  • Comentarios, comentarios, comentarios : asegúrese de que los fragmentos contengan muchos comentarios o estén bien anotados con texto que etiquete claramente las intenciones de su código. Continuando con el tema de la verbosidad, comente más de lo que normalmente haría para guiar al lector en cada paso. Un gran ejemplo es este tutorial de Rails sobre la integración de Stripe , que explica claramente el propósito de cada fragmento.

Crear una aplicación

El último paso en la creación de un gran tutorial es dar vida a lo que ha explicado mediante la creación de una aplicación que un desarrollador pueda ejecutar. Dependiendo de la profundidad y el detalle de la solución en sí, esto podría ser un simple fragmento de código, una esencia, un proyecto de GitHub o una imagen de Docker que se puede ejecutar con un esfuerzo mínimo por parte del desarrollador. Naturalmente, no va a recorrer toda la solución en el tutorial, así que asegúrese de resumirlo con algunas capturas de pantalla bien elegidas .

Los límites de su aplicación dependen completamente de su imaginación, habilidades y las necesidades de su comunidad de desarrolladores, pero debe buscar hacer lo siguiente:

  • Asegúrese de que se pueda ejecutar en un número mínimo de pasos;
  • Al igual que los fragmentos de código, inserte una gama completa de comentarios y sugerencias que expliquen la importancia de la implementación;
  • Demuestre un caso de uso realmente convincente para su API.

Asegurarse de que su aplicación demuestre estas características realmente lo ayudará a concluir su tutorial y garantizar que todos los puntos que ha planteado se refuercen.

Pensamientos finales

En esta publicación, hemos explorado lo que hace que un excelente tutorial de API y hemos resaltado los temas centrales que facilitan a su comunidad de desarrolladores comprender y digerir la información clave sobre su API.

No hace falta decir que no todos los tutoriales de API mostrarán todo lo que se discute aquí; sin embargo, si se concentra en los puntos planteados, debería lograr crear una narrativa convincente que no solo mantenga el interés del lector, sino que cumpla con el objetivo de disminuir el tiempo que lleva incorporarse a su programa API.

Publicar un comentario

0 Comentarios