Header Ads Widget

Ticker

6/recent/ticker-posts

Prácticas recomendadas para crear documentación de API útil

 


La documentación de la API es la clave para una API útil y utilizable. Una API podría ser todopoderosa, versátil y completamente útil, pero no importará ni un poco si los usuarios no pueden descubrir cómo hacer que funcione. Crear la documentación adecuada de la API es una forma de arte en sí misma. Sin embargo, no todos los programadores son buenos escritores, al igual que no todos los autores son excelentes programadores. Crear documentación de API útil, informativa y comprensible es un conjunto de habilidades en sí mismo.

Para ayudar a que sus API sean más útiles, compartiremos algunas de las mejores prácticas para la documentación de API. Comenzaremos examinando los componentes esenciales que toda documentación de API debe contener. Luego, veremos algunas de las mejores prácticas de documentación de API.

Comprender la audiencia de la documentación de API

A los escritores se les suele decir que "conozcan a su audiencia". Para quién escribas influirá en tu escritura de diversas formas, desde el tono hasta la elección de palabras. Esto es igualmente cierto para los desarrolladores que crean documentación de API.

En términos muy generales, los consumidores de documentación API se dividen en dos categorías principales. Están los tomadores de decisiones que deciden qué API utilizar. Luego están los programadores que utilizarán las API. Esto significa que la documentación de la API debe cumplir dos funciones principales, simultáneamente.

Al elaborar la documentación de la API, tenga en cuenta: ¿quién es el consumidor desarrollador objetivo?

Primero debe ilustrar la utilidad de una API para convencer a los tomadores de decisiones. Piense en la hoja de especificaciones de un producto como ejemplo.

Sin embargo, los desarrolladores que usarán su API son la audiencia principal que debe tener en cuenta. Necesitarán pautas detalladas y completas. Esto significa explicar todas las funciones con ejemplos de código.

Ahora que comprende a su audiencia, debería comenzar a tener una idea de una plantilla básica para crear documentación API útil. Tener en cuenta las mejores prácticas de documentación de API mientras desarrolla su API lo ayudará a mantener el hábito de tomar notas sobre la marcha, lo que le ayudará a compilar la documentación de API una vez que haya terminado de codificar.

Los componentes esenciales de la documentación de API

Si bien cada API es diferente, la mayoría tiene algunos componentes básicos que casi todas las API incorporan. La documentación de su API debe incluir documentación para estas funciones, ya que son algunas de las primeras cosas que los desarrolladores buscarán cuando comiencen a usar su API.

Autenticación

La autenticación es una de las primeras cosas que encuentra un usuario cuando usa una API. Piense en la autenticación como una clave que desbloqueará su API para sus usuarios. Casi todas las API presentan algún tipo de esquema de autenticación, y casi todas son diferentes.

Para comenzar, la documentación de su API debe permitir que los usuarios sepan cómo acceder a su API. Puede echar un vistazo a la documentación de autenticación de Auth0 para ver un ejemplo de cómo se ve la documentación de autenticación completa y concisa.

Recursos de API

Los usuarios necesitan saber lo que puede hacer su API Enumere todos los puntos finales con comandos y respuestas estándar. Enumerar todos los comandos y respuestas lo ayuda a pensar como sus usuarios finales y a crear documentación completa y comprensible para cada respuesta. Piense en ello como hacer un diagrama de su programa y luego crear documentación para cada paso.

Por ejemplo, consulte la documentación de la API para WordPress . WordPress ofrece una lista completa y exhaustiva de todos los puntos finales API disponibles. Cada comando tiene su propia página, con documentación completa de todo su contexto, consultas y códigos de error. Cada página tiene un código de ejemplo, también, para ofrecer una guía sobre cómo comenzar con esa característica en particular.

WordPress organiza la documentación de la API con una página separada para cada función.

En general, esto proporciona una comprensión detallada de la estructura de la API. Como puede ver, hay más de 20 recursos para recuperar o modificar solo la información del usuario. Para documentación de API compleja como esta, la organización y la navegabilidad son clave.

La documentación de la API de WordPress también es un excelente ejemplo de usabilidad. Cada función presenta una etiqueta que le permite saber qué método HTTP requiere el comando, ya sea 'GET' o 'POST'. Esto le evita tener que leer cada página para tener una comprensión básica de cómo utilizar cada recurso de la API.

Considere también: Más de  10 mejores prácticas para nombrar puntos finales de API

Error de mensajes

Es probable que la depuración sea una de las principales razones por las que las personas consultan la documentación de la API. Querrá tener una sección completa que explique todos los mensajes de error que devuelve su API. Esto hará que su API sea más útil para sus usuarios, ayudándoles a evitar frustraciones y a tener buenos sentimientos hacia su API.

Tampoco limite la documentación de su API a enumerar los mensajes de error. Incluya un ejemplo o dos de cómo solucionar problemas comunes. Consulte la documentación de la API de Mailchimp para ver un ejemplo de documentación de errores completa y útil.

Desde 400 Bad Request hasta 500 InternalServerError, el glosario de errores de Mailchimp detalla los errores globales de la API de Mailchimp.

Lea también: Mejores prácticas para el manejo de errores de API

Términos de Uso

Los Términos de uso son el acuerdo legal entre usted y sus usuarios. En la sección Condiciones de uso de la documentación de la API, debe incluir los límites, las restricciones, las pautas de marca y el uso aceptable de la API.

Consulte los Términos de servicio de Spotify como modelo.

Relacionado: Una guía humana para redactar la política de la plataforma API

Registro de cambios

La sección Changelog de la documentación de su API permite a sus usuarios saber qué tan estable es su API. También les permite saber si algo ha cambiado, en el caso de que una de sus llamadas deje de funcionar. Puede echar un vistazo al registro de cambios de GitHub para ver un ejemplo de documentación exhaustiva del registro de cambios.

El registro de cambios del desarrollador de Github proporciona actualizaciones sobre la disponibilidad general, las bajas y el tiempo de inactividad de varios servicios.

Prácticas recomendadas para la documentación de API

Ahora que hemos echado un vistazo a algunos de los componentes esenciales que la documentación de la API debería tener para ser útil en última instancia, consideremos algunas de las mejores prácticas para que su documentación realmente brille tanto para los desarrolladores como para los responsables de la toma de decisiones.

Evite la jerga

Recuerde, tiene muy poco control sobre quién consumirá su API. Habrá usuarios de todos los diferentes niveles de experiencia utilizando su API y leyendo la documentación de su API. Desea que tanto los usuarios avanzados como los sin experiencia puedan encontrar tanto su API como su documentación útiles y acogedores.

La jerga excesiva es un escollo en el que pueden caer los desarrolladores y tiene muchos inconvenientes. En primer lugar, los responsables de la toma de decisiones financieras a menudo no son tan expertos en tecnología. Si está tratando de convencerlos de que inviertan en su API, el lenguaje sencillo irá mucho más allá de la jerga técnica avanzada.

En segundo lugar, y lo que es más importante, desea que su API sea útil para tantos programadores, de todos los niveles de habilidad, como sea posible. Si tiene que utilizar jerga técnica, debe incluir un enlace a un glosario, definición o tutorial que explique ese concepto en la documentación de su API.

¡A veces, ser prolijo ayuda! Eche un vistazo a la documentación de la API de YouTube para ver un ejemplo de documentación completa y útil escrita en lenguaje sencillo.

Documente todas las solicitudes y respuestas a fondo

No existe demasiada información en la documentación de la API. De todos modos, no es probable que los usuarios lean todo de una vez. Cuando un usuario recién está comenzando con su API, es probable que necesite un poco de agarre hasta que lo haya integrado en su flujo de trabajo.

Con eso en mente, debe incluir documentación de cada llamada que su API puede recibir y proporcionar algún contexto tanto para los parámetros como para las respuestas. También documente las respuestas, ya que les permitirán a sus usuarios saber que las cosas están funcionando como deberían. Documente también todos los posibles mensajes de error. Todo esto tiene como objetivo permitir que sus usuarios vean exactamente lo que se devolverá a partir de una solicitud de API. Esto les evitará la molestia de tener que recurrir a Google para solucionar problemas si algo sale mal.

Incluir recursos adicionales

Si algo está fuera del alcance de la documentación de su API, debe incluir enlaces a la información necesaria para sus usuarios. Nuevamente, no desea que sus usuarios tengan que buscar respuestas a través de un motor de búsqueda, lo que puede ser frustrante y dejarlos con una asociación negativa hacia su API.

Lea también:  8 pequeños ajustes en los documentos de API que ofrecen grandes resultados en DX

Incluya una guía de introducción

Quiere que los usuarios puedan empezar a utilizar su API lo más rápido posible, para que puedan ver lo útil que es. Una guía rápida sobre cómo comenzar a usar su API es la forma más fácil de hacer que esto suceda.

Puede consultar la documentación de introducción de Braintree para ver un ejemplo de una excelente guía de introducción.

Incluir código de muestra

La forma más rápida y sencilla de poner en marcha un nuevo usuario con su API es incluir algún código de muestra en su documentación . El usuario simplemente necesita reemplazar la clave API en el código de muestra con su propia clave y estará listo y funcionando.

El código de muestra también les da a los desarrolladores la oportunidad de ver el código terminado que implementa su API para que puedan realizar ingeniería inversa y diseñar sus propios programas. Puede considerar tener documentación para cada sección individual y luego tener un código de muestra al final que muestre todas las funciones en funcionamiento.

Mejores prácticas para la documentación de API: pensamientos finales

Una buena documentación de API es la base de una experiencia de desarrollador de calidad . Es lo que separa a su API de ser utilizable y útil de ser frustrante y no esencial. ¿De qué sirve tu API si nadie sabe cómo usarla? ¿Cómo deben los usuarios saber para invertir tiempo, energía o recursos de dejar que el dinero solo si está liberando una API comercial si no saben lo que su API hace o cómo se pueden beneficiar su negocio.

Tener una buena documentación de la API a menudo también significa la diferencia entre una recomendación o una revisión negativa. Quiere que los usuarios estén entusiasmados con su API, cantando sus elogios a su red y comunidad. Una buena documentación de la API es una de las formas más esenciales en que puede hacer que eso suceda, ofreciendo información útil, instrucciones claras y ejemplos fáciles de seguir.

Publicar un comentario

0 Comentarios