Header Ads Widget

Ticker

6/recent/ticker-posts

Uso de plantillas para el diseño de API basado en documentación

 

Uso de plantillas para el diseño de API basado en documentación

Como proveedor de API, es importante considerar cómo los consumidores interactúan con su API. Si bien la mayoría de la gente deja esta tarea para el final, el diseño de la API debería, de hecho, comenzar con una documentación clara y concisa. Esta práctica a menudo se denomina "Diseño impulsado por la documentación" o "Desarrollo impulsado por la documentación" y es seguida por muchos profesionales en todo el mundo. Tom Preston-Werner , fundador de GitHub, describe claramente algunas ventajas de este enfoque:

  • El proyecto se ejecuta mejor ya que tiene tiempo para pensar en todos los aspectos antes de la implementación.
  • Es mucho más fácil escribir documentación al comienzo del proyecto cuando tu mente está fresca y las ideas son más fáciles de poner por escrito.
  • Cuando usted (o su equipo) comience a implementar la API, hay una especificación clara a seguir.
  • Discutir ideas y posibles cambios es mucho más fácil cuando hay documentación escrita.

Si bien reconocer estos beneficios es fácil, lo que no es tan fácil es empezar de cero. Mirar una pantalla en blanco pensando en los puntos finales que debería tener tu API no te ayuda a progresar con la documentación. Este artículo lo ayuda a evitar ese estado inicial en blanco al resaltar las secciones de documentación de la API y sugerir las mejores prácticas que puede incorporar en su propio diseño. Entraremos en ejemplos más detallados, pero comencemos primero mirando qué componentes debe tener cualquier documentación de API.

 

Secciones de documentación de API fundamentales

Estas son las secciones que debe ofrecer toda documentación de API . Sin estas secciones, los consumidores tendrán muchas dificultades para comprender cómo se puede utilizar su API y, en muchos casos, simplemente se darán por vencidos.

  • Información de autenticación , que describe qué esquema de autenticación usa su API. Si está utilizando OAuth, no olvide explicar cómo configurar una aplicación OAuth y obtener la clave y el secreto de API.
  • Errores y cómo se comunican a los consumidores de API. Aquí debe explicar si sigue algún estándar de error, por ejemplo, los códigos de estado HTTP, y cómo los errores se comunican generalmente dentro de las respuestas.
  • Endpoints e información sobre cómo consumirlos, incluidas solicitudes y respuestas. Esta se considera la sección principal donde expone todos sus métodos de API, explica cómo se pueden alcanzar y observa qué tipo de parámetros están permitidos.

Con estas tres secciones, ha tenido un gran comienzo porque ya ha documentado la mayor parte de lo que se necesita para consumir su API y su oferta. Pero, como está a punto de descubrir, esto a menudo no es suficiente. A medida que obtenga consumidores más sofisticados, tendrá que ofrecerles documentación sobre aspectos no funcionales de su API.

Secciones de documentación de API de expertos

La incorporación de los siguientes puntos hará que su API se destaque de la competencia. Si bien es cierto que algunos consumidores pueden descuidar estas secciones en particular, los consumidores orientados a los negocios pueden considerar que son imperativas.

  • Términos de uso , incluidos los límites de API y otros términos y condiciones de mejores prácticas . Los permisos y las restricciones deben establecerse claramente para que los consumidores comprendan qué prácticas de uso de API están permitidas.
  • Ejemplos de cómo consumir su API, que incluyen comenzar desde cero, pero también mostrar casos de uso en los que su API sería útil. Incluya mucho código y, si es posible, estudios de casos con consumidores reales de API y aplicaciones de ejemplo.
  • Un registro de cambios que detalla las últimas actualizaciones y cómo podrían afectar a los consumidores de API. Esto ayudará a los consumidores a evaluar la estabilidad de la API y les ayudará a comprender si algún cambio realizado en las llamadas a la API podría afectar su integración.

Incluir estas secciones pondrá la documentación de su API en una posición mucho mejor. Ahora, cuando los consumidores potenciales vean su API, la encontrarán claramente documentada. El aumento de la conciencia con la información periférica de la API ayuda a establecer credibilidad, disminuye los problemas de incorporación y ayuda a generar confianza a largo plazo.

Pero decir es más fácil que hacer. ¿Cómo se pasa de un estado inicial en blanco a una documentación bien estructurada? Siga leyendo y vea cómo se pueden usar las siguientes plantillas para crear una documentación de API deliciosa.

3 Recursos de plantillas de documentación de API

Entre todos los formatos de documentación de API, tres de ellos merecen una mención porque le permiten diseñar su API de una manera que puede ser fácilmente consumida tanto por humanos como por máquinas :

  • Swagger : desarrollado por Reverb Technologies, le permite generar fácilmente su propio código de servidor API, código de cliente y también la documentación en sí.
  • RAML : Creado por MuleSoft, ofrece una manera fácil de especificar una API mediante el uso de patrones.
  • API Blueprint : mantenido por Apiary, es un estándar basado en el popular formato Markdown que le permite generar fácilmente código a partir de la documentación.

Documentación básica con el modelo de API

Apiary ha reunido varios ejemplos de API Blueprint que pueden ayudar a documentar una API sin tener que empezar desde cero. API Blueprint es una forma sencilla y sin complicaciones de documentar las API que utiliza Markdown como lenguaje de formato. Los archivos API Blueprint se pueden leer directamente y convertir a HTML, PDF o cualquier otro formato compatible con la documentación. Otra ventaja de usar API Blueprint es que el mismo archivo también puede ser manipulado directamente por más de una docena de herramientas útiles, incluida la generación de código , que le ayuda a seguir el enfoque de “Diseño basado en documentación” explicado anteriormente.

Echemos un vistazo a algunos de los ejemplos, comenzando por uno muy simple y creciendo en sofisticación a medida que avanzamos. Este primer ejemplo (algunas partes eliminadas por mí) no ofrece todas las secciones requeridas que mencioné antes, pero es una forma rápida de familiarizarse con el formato API Blueprint.

FORMAT: 1A

# Named Resource and Actions API  
This API example demonstrates how to name a resource and its actions (...).

# My Message [/message]  
Note the URI `/message` is enclosed in square brackets. 

## Retrieve a Message [GET]  
This action clearly retrieves the message.

+ Response 200 (text/plain)

        Hello World!

## Update a Message [PUT]  
`Update a message` - nice and simple naming is the best way to go.

+ Request (text/plain)

        All your base are belong to us.

+ Response 204

La documentación anterior comienza describiendo lo que ofrece la API a los consumidores. Continúa describiendo un punto final ( /message) e incluye sus posibles operaciones. Como puede ver, el /messagepunto final le permite recuperar un mensaje realizando una GETsolicitud HTTP y también le permite actualizar un mensaje realizando una PUToperación HTTP La documentación también muestra cuáles son las solicitudes y respuestas esperadas para cada operación.

Mayor sofisticación mediante API Blueprint

Ahora que ha visto un ejemplo simple de API Blueprint en acción, trabajemos en un caso más completo , donde la información de autenticación y error también está presente. Comencemos mirando la descripción de la API:

## Gist Fox API  
Gist Fox API is a **pastes service** similar to [GitHub’s Gist](http://gist.github.com).

Se proporciona información general sobre para qué se puede utilizar la API. A continuación, se describe la autenticación:

## Authentication
*Gist Fox API* uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.

Como puede ver, esta API usa OAuth y explica lo que usted, como consumidor, tendría que hacer para obtener un token de OAuth y cómo se pueden consumir los recursos de la API después de tenerlo. A continuación, se describen los estándares de error:

## Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.

La API sigue el estándar de códigos de estado HTTP, informando al consumidor de qué esperar al consumir los puntos finales disponibles. Como las devoluciones de error siguen un estándar bien conocido, no es necesario explicar con más detalle cómo funciona (no obstante, el enlace a la lista de estado HTTP de GitHub es útil). Veamos ahora cómo se documenta un punto final de API:

## Star [/gists/{id}/star{?access_token}]  
Star resource represents a Gist starred status. 

The Star resource has the following attribute:

- starred

+ Parameters  
    + id (string) ... ID of the gist in the form of a hash  
    + access_token (string, optional) ... Gist Fox API access token.

Esta sección define el recurso Star y sus atributos, y le dice al consumidor qué parámetros se pueden pasar a este recurso para la autenticación; en este caso, un idtoken de acceso y uno porque se está utilizando OAuth. El siguiente cuerpo describe el modelo subyacente del recurso:

+ Model (application/hal+json)

    HAL+JSON representation of Star Resource.

    + Body

            {  
                "_links": {  
                    "self": { "href": "/gists/42/star" },  
                },  
                "starred": true  
            }

Esta sección utiliza el lenguaje de aplicación de hipertexto (HAL) para especificar el modelo de datos de recursos. Esto le da al proveedor de API una gran flexibilidad para documentar en detalle la información que un recurso determinado puede manejar. Veamos ahora una de las posibles operaciones en el starrecurso:

### Star a Gist [PUT]  
This action requires an `access_token` with `gist_write` scope. 

+ Response 204

Esta operación se realiza emitiendo una PUToperación HTTP al starrecurso, que está disponible en /gists/{id}/star{?access_token}, como se describió anteriormente. Explica cómo se puede acceder a la operación y cuál es una respuesta esperada: en este caso particular, necesitará un token de acceso válido y puede esperar recibir una respuesta HTTP 204, lo que significa que el servidor ha cumplido la solicitud pero no hay nada para responder.

Como estos son dos ejemplos básicos de lo que puede hacer con API Blueprint, le recomiendo que eche un vistazo a todo lo que puede hacer con él abriendo los enlaces compartidos en este artículo.

Conclusión

Todos están de acuerdo en que la documentación es una necesidad absoluta si desea garantizar que los consumidores y socios comerciales potenciales entiendan bien su API. Si bien algunas personas creen que comenzar un proyecto de API con documentación inicial es una buena idea, la mayoría de las personas tienen dificultades para escribir algo. En este artículo, ha aprendido las ventajas de seguir un enfoque de "diseño basado en documentación", así como las secciones más importantes que no desea olvidar.

Como comenzar desde cero es el problema real para la mayoría de las personas, este artículo compartió algunas plantillas que usa en su proyecto para ayudarlo rápidamente a comenzar. Si sigue los ejemplos de API Blueprint mencionados, no solo tendrá algo con lo que empezar, sino que también seguirá las mejores prácticas en términos de documentación. Una vez que termine su documentación, puede generar rápidamente el código para su API utilizando las herramientas API Blueprint.

¿Cómo está documentando su API? ¿Está siguiendo un enfoque de "diseño basado en documentación"? ¡Deje un comentario aquí o póngase en contacto para discutir esto más!

Publicar un comentario

0 Comentarios