Header Ads Widget

Ticker

6/recent/ticker-posts

11 consejos para crear una guía de estilo de API


Una guía de estilo de API es una de las herramientas más efectivas para mantener la coherencia en un conjunto de API. Muchas grandes empresas ya tienen algún tipo de guía de estilo de desarrollo, pero incluso las plataformas más pequeñas están comenzando a implementar esto de manera proactiva, junto con otras mejores prácticas de gobernanza de API , ¡y usted también debería hacerlo!

Para que una guía de estilo de API sea más beneficiosa, debe cubrir varios temas de diseño de API comunes y estar escrita de una manera clara, fácil de actualizar y procesable. En esta publicación, cubriremos 11 consejos cruciales y elementos imprescindibles que debe tener en cuenta al crear la guía de estilo de API de su organización.

Elementos imprescindibles para cualquier guía de estilo API

Comencemos discutiendo los elementos básicos que debe incluir una guía de estilo de API:

1. Estilo de diseño y especificaciones

Una de las primeras cosas que debe cubrir una guía de estilo es qué estilo arquitectónico general usar. Por ejemplo, ¿deberían las API adherirse a REST, GraphQL u otro patrón de diseño ?

Además de esto, querrá que los desarrolladores sepan si deberían describir sus API con algún tipo de especificación (pista: probablemente deberían ) y, de ser así, cuál es esa especificación.

2. Autenticación y autorización

Un aspecto extremadamente importante del diseño de API es la seguridad, por lo que, después del estilo de diseño, debería ser uno de los temas principales en una guía de estilo. En particular, las guías de estilo deben explicar cómo los desarrolladores deben implementar la autenticación y la autorización .

En la mayoría de los casos, como el de la Guía de diseño de API de Cisco , esto significará usar OAuth 2.0 , un protocolo estándar de la industria.

3. Nomenclatura de terminales

Según un ingeniero senior de PayPal , el nombre de los puntos finales de la API es un aspecto del diseño de la API que a menudo se pasa por alto, aunque estos nombres tienden a quedarse. Como resultado, vale la pena dedicar una pequeña sección de su guía de diseño a las convenciones de nomenclatura; consulte nuestra guía aquí para conocer las mejores prácticas de nomenclatura de terminales .

4. Códigos de error

Otra consideración fundamental para su guía de estilo es el uso de códigos de error HTTP. Aunque no deberían variar demasiado entre organizaciones, los detalles aún merecen ser incluidos en su guía de estilo.

Si no está seguro de qué discutir exactamente en esta sección, consulte nuestra guía de mejores prácticas para el manejo de errores .

5. Control de versiones

La forma en que se tratan las versiones y los cambios importantes en las API puede variar de una organización a otra, por lo que esto es otra cosa que debe incluir en su guía de estilo para garantizar que sus API evolucionen de manera similar.

Una vez más, tenemos una guía completa de las mejores prácticas para el control de versiones .

6. Unidades, formatos y estándares

Por último, pero no menos importante, vale la pena definir las unidades, los formatos y los estándares que los desarrolladores deben cumplir dentro de su guía de estilo de API. Lo que tiene que definir a menudo dependerá de su industria, pero algunos tipos de datos, como las fechas y horas, son relativamente universales.

Para obtener información sobre algunas de las prácticas estándar de fecha y hora utilizadas en el desarrollo de API, consulte este recurso del arquitecto de API Jason Harmon.

Más consejos para una guía de estilo de API eficaz

Obtener el alcance correcto es solo la mitad de la batalla para crear una buena guía de estilo de API. El resto es dejarlo claro, fácil de actualizar y procesable. Para eso, consulte estos consejos:

7. Utilice una herramienta de control de versiones

Aunque una guía de estilo de la API podría adoptar la forma de un documento de texto sin formato que se distribuye en Slack, recomendamos encarecidamente una solución más iterativa que le permita actualizar la guía de forma transparente para que todos la vean.

GitHub es una gran herramienta para esto; diablos, tanto PayPal como Microsoft , entre otros, albergan sus guías de estilo API dentro de repositorios públicos de GitHub.

Otra solución es iterar en su guía de estilo usando una herramienta de control de versiones como GitHub, pero renderizar una versión estática con su propio estilo en otro lugar. Esto es precisamente lo que ha hecho Google con sus propuestas de mejora de API : la fuente está en GitHub , pero se muestra una versión estática más bonita en https://google.aip.dev/ .

8. Utilice los niveles de requisitos de RFC

No es obligatorio, pero debería considerar estandarizar los niveles de requisitos en su guía de estilo utilizando las palabras clave descritas en RFC 2119 . De esta manera, los desarrolladores sabrán exactamente cómo interpretar sus pautas:

Las palabras clave “DEBE”, “NO DEBE”, “REQUERIDO”, “DEBERÁ”, “NO DEBE”, “DEBERÍA”, “NO DEBE”, “RECOMENDADO”, “PUEDE” y “OPCIONAL” en este documento son para ser interpretado como se describe en RFC 2119.

9. Enlace frecuente a recursos externos

Su guía de estilo debe ser lo suficientemente breve como para que los desarrolladores puedan leerla en su totalidad, pero también debe ser lo suficientemente completa como para que los aspectos más mundanos del diseño de API puedan ser consistentes en toda su suite.

Una forma de lograr esto es mediante la vinculación frecuente a recursos externos, donde se describen con mayor profundidad estándares específicos o mejores prácticas. Estos pueden ser los propios recursos de su organización o incluso recursos de terceros confiables.

10. Insertar ejemplos de solicitud / respuesta

A menudo, la mejor forma de ilustrar las cosas es con ejemplos. En el caso de las API, eso significa mostrar solicitudes y respuestas de muestra con frecuencia en su guía de estilo.

Puede resultar especialmente útil incluir dos pares de solicitudes y respuestas para mostrar cómo los desarrolladores deben y no deben diseñar sus API.

11. Fomentar la colaboración

Nuestro consejo final es permitir la colaboración en su guía de estilo de API. Como mínimo, los desarrolladores de toda la organización deberían poder enviar comentarios o solicitar orientación sobre áreas específicas del diseño de API.

Este es otro beneficio más de usar una plataforma de control de versiones como GitHub: proporciona un entorno familiar para la colaboración. Una vez más, las propuestas de mejora de API de Google son un excelente ejemplo de cooperación y transparencia en el mantenimiento de la guía de estilo de API.

Conclusión

Como describe Chase Doelling , "las API escalables se crean a partir de la coherencia". Por lo tanto, una guía de estilo de API es una herramienta de gobierno fácil y eficaz para mantener la coherencia en todo su conjunto de API . En esta publicación, analizamos seis elementos que debe contener cualquier guía de estilo y cinco consejos para hacer que las guías de estilo sean lo más útiles posible.

Para obtener más información sobre qué incluir en su guía de estilo, consulte el API Stylebook de Arnaud Lauret. Es una compilación de pautas de diseño de más de una docena de organizaciones tecnológicas líderes, incluidas Atlassian, Cisco y Microsoft, clasificadas por tema.

Publicar un comentario

0 Comentarios