Header Ads Widget

Ticker

6/recent/ticker-posts

5 ejemplos de excelente documentación de API (y por qué pensamos eso)

 


Si ha pasado mucho tiempo en el blog de las API nórdicas, sabrá que la experiencia del desarrollador es algo que nos apasiona. Crear una experiencia fluida y agradable para quienes implementan sus API es esencial con la cantidad de competencia que existe hoy en día, y la documentación de API es una de las claves del éxito.

En una publicación anterior, hablamos sobre las funciones sin las que la documentación de API no puede vivir y, en términos más generales, los ingredientes básicos para un centro de desarrolladores , pero hoy vamos a sumergirnos de lleno en el meollo de todo y analizar cinco ejemplos de excelente documentación de API .

Como advertencia rápida, estos documentos de referencia de API son excelentes por muchas más razones que una. Pero esta es una publicación de blog, no un libro, por lo que le daremos un resumen rápido del ejemplo y luego nos enfocaremos en solo una de sus características mejor ejecutadas. Sin embargo, para mantenerlo informado del panorama general, volveremos a consultar esta lista de verificación de cinco partes de los conceptos básicos de la documentación a lo largo de la publicación:

Guía de autenticación ☐ Guía de inicio
rápido ☐
Definiciones de punto final ☐
Fragmentos de código ☐
Respuestas de ejemplo ☐

1. Referencia de la API de Stripe

Lo desafiamos a encontrar una discusión sobre los mejores documentos de referencia de API que no incluyen Stripe. Alerta de spoiler: no hay ninguno. La documentación de la API de Stripe , o la referencia de la API de Stripe , es una obra de arte. Cuenta con un diseño elegante y fresco de dos paneles, con explicaciones escritas en inglés sencillo a la izquierda y prácticos fragmentos de código a la derecha. Como era de esperar, tiene toda la información crucial que necesita para comenzar de inmediato.

Lo que amamos de él

Es difícil señalar una sola característica interesante de la documentación de la API de Stripe. En verdad, no hay campanas y silbidos brillantes, y eso es probablemente lo que hace que la referencia de la API de Stripe sea tan buena. Tiene toda la información que necesita para comenzar, presentada de manera limpia y sensata. La lección: no se exceda.

¿Cumple con los requisitos?

Guía de autenticación ☑ Guía de inicio
rápido ☐
Definiciones de punto final ☑ Fragmentos de
código ☑
Respuestas de ejemplo ☑

2. Twilio Docs

Otro favorito de los desarrolladores que se cita con frecuencia son los documentos Twilio . Los Twilio Docs usan el mismo estilo de dos paneles que la Referencia de API de Stripe (de la que somos fanáticos). Sin embargo, la documentación de la API de Twilio se siente un poco más agradable a la vista, con una fuente bien elegida y enlaces brillantes y contrastantes. No debería ser necesario mencionar que hay muchos fragmentos de código que puede copiar y pegar de inmediato.

¿Cumple con los requisitos?

Guía de autenticación ☑ Guía de inicio
rápido ☑
Definiciones de puntos
finales ☑ Fragmentos de código ☑
Respuestas de ejemplo ☑

Lo que amamos de él

Lo que nos encanta de Twilio Docs es la profundidad que brindan, incluso para los principiantes. Basta con mirar hacia el panel de navegación lateral: han incluido páginas como "¿Qué es una API REST, de todos modos?" y "Cómo utiliza la API de Twilio los webhooks". Sus respuestas a estas preguntas brindan a los desarrolladores una visión rápida y ascendente de todo lo que necesitan saber. La lección: sé amigable para los principiantes.

3. Documentación de la API de Dropbox

La documentación de la API de Dropbox es otro ejemplo fantástico de excelente documentación de referencia. En lugar de usar el mismo diseño de dos paneles que otros competidores en esta lista, Dropbox le permite elegir primero el lenguaje de programación que prefiera y luego proporciona documentación personalizada para ese lenguaje.

Lo que amamos de él

Nos gusta el enfoque de Dropbox por su simplicidad. En lugar de bombardearlo con información que abarca toda la página, le brinda consejos de implementación específicos para el idioma elegido. La lección: atienda a entornos de desarrollo únicos .

¿Cumple con los requisitos?

Guía de autenticación ☑ Guía de inicio
rápido ☑
Definiciones de puntos
finales ☑ Fragmentos de código ☑
Respuestas de ejemplo ☑

4. Documentación de la API de GitHub

Los desarrolladores también elogian con frecuencia la documentación de la API REST de GitHub . Al igual que Dropbox, los documentos de Github no intentan poner demasiada información en una página. El menú simple en la parte superior derecha dirige a los desarrolladores en la dirección general correcta, con enlaces a material de referencia, guías y bibliotecas, y luego se reduce a artículos de publicación de blog bien ordenados para dirigir a los desarrolladores desde allí.

Lo que amamos de él

Como habrás notado, cada página de la referencia de API de GitHub tiene un pequeño widget que te dice el estado de la API. Es un pequeño toque, pero como cubrimos recientemente , pequeños ajustes como este se vuelven muy útiles. Si los desarrolladores tienen problemas con su implementación, un vistazo les dice si puede estar o no relacionado con el servidor. La lección: ahorre tiempo al desarrollador siempre que pueda.

¿Cumple con los requisitos?

Guía de autenticación ☑ Guía de inicio
rápido ☑
Definiciones de puntos
finales ☑ Fragmentos de código ☑
Respuestas de ejemplo ☑

5. Documentación de la API de Twitter

Aunque puede que no sea un ejemplo tan popular como los otros en esta lista, la documentación de la API de Twitter es uno de mis favoritos personales a nivel visual. El diseño de contenedor único, como con Dropbox y GitHub, dirige toda su atención a un solo lugar. Sin embargo, los documentos de la API de Twitter se sienten menos como una publicación de blog mundana y más como una guía interactiva: hay una nota rápida de cuántos minutos de lectura es la página, puede cambiar entre diferentes métodos dentro de la publicación y el final "Siguiente Steps ”siempre te apunta en la dirección correcta.

Lo que amamos de él

Los documentos de la API de Twitter tienen una sección de preguntas frecuentes (FAQ) para casi todas las páginas. En lugar de incluir demasiada información secreta en la explicación principal, todas las preguntas más comunes se encuentran en esas páginas de preguntas frecuentes. Personalmente, me encanta trabajar con preguntas frecuentes donde sé que puedo encontrar respuestas a mis preguntas inevitables. La lección: sea flexible con la forma en que presenta la información.

¿Cumple con los requisitos?

Guía de autenticación ☑ Guía de inicio
rápido ☑
Definiciones de puntos
finales ☑ Fragmentos de código ☑
Respuestas de ejemplo ☑

Pensamientos finales

Ahí lo tiene: cinco ejemplos de excelente documentación de API, con características únicas o particularmente bien ejecutadas para cada uno. Por supuesto, estos documentos de API tienen mucho más a su favor de lo que han discutido, pero debe leer nuestro artículo 7 elementos sin los que no puede vivir la documentación de API si desea obtener un resumen de todas las características principales que necesita para excelentes documentos de API.

Publicar un comentario

0 Comentarios