Header Ads Widget

Ticker

6/recent/ticker-posts

Propuestas de mejora de API: la versión de Google de la guía de estilo de API

 


Cuantas más API tenga una organización, más crítica será la gobernanza de las API , la práctica de estandarizar y coordinar las API en una organización.

Un activo invaluable en la estrategia de gobierno de muchas organizaciones es una guía de estilo de API, que describe los estándares y las mejores prácticas para todas las áreas del diseño de API. Tener una guía de estilo de API podría ayudar a garantizar la coherencia, maximizar el rendimiento y mejorar la seguridad general.

Si bien una guía de estilo puede parecer simple, las dificultades comienzan a surgir a medida que aumenta el número de personas y API en una organización. Por un lado, se requiere un esfuerzo serio para garantizar que la guía de estilo permanezca estructurada a medida que se agregan nuevas pautas para áreas comerciales específicas. Además, se vuelve un desafío administrar los comentarios y los cambios, especialmente si la guía de estilo toma la forma de un documento de texto simple.

Los ingenieros de Google han ideado su propio enfoque para la guía de estilo de la API, llamado Propuestas de mejora de API. En este artículo, analizaremos en profundidad qué cubren estas propuestas, cómo se ven, cómo se administran, cómo puede implementarlas y los beneficios que ofrecen.

¿Qué son las propuestas de mejora de API (AIP)?

Las propuestas de mejora de API, o AIP , son documentos que describen las pautas de Google para el diseño de API. La mayoría de los AIP se centran en estándares de diseño universales, como el nombre de los recursos , la paginación o el manejo de errores , que se aplican a todos los servicios de la organización. Sin embargo, algunos AIP describen estándares específicos para ciertas áreas de productos, así como meta-AIP (que describen los AIP en sí mismos). Este también es el caso de las propuestas de mejora de Python (PEP), que probablemente hayan inspirado AIP.

Dado que a cada AIP se le asigna un número entre 1 y 9999, puedes hacerte una idea del alcance de estas propuestas mirando los bloques que Google tiene reservados:

General

  • 1–99: Meta-AIP
  • 100–999: diseño de API general

Áreas de productos de Google

  • 2700-2799: aplicaciones (GSuite)
  • 2500-2599: nube
  • 3000–3099: Acciones en Google
  • 3200–3299: Firebase
  • 4100–4199: bibliotecas de autenticación
  • 4200–4299: bibliotecas cliente
  • 4600–4699: Geo

Para aquellos que buscan usar AIP para administrar la guía de diseño interno, Google también ha reservado los números 9000 a 9999 para documentos de diseño privados. De lo contrario, todos los AIP se hacen públicos en https://google.aip.dev.

¿Qué aspecto tiene un AIP?

Hasta ahora, todo bien: tenemos una colección de documentos que describen las pautas de diseño de API de Google. Entonces, ¿qué hace que el enfoque AIP para la gobernanza de API sea especial? ¿Es así como se ven los propios documentos? Por el contrario, los AIP son, visualmente, bastante mundanos:

Aparte de los metadatos del lado derecho, los AIP son documentos de texto simples que utilizan el formato Markdown básico. Por lo general, constan de algunos subtítulos (según el tema), así como un breve registro de cambios al final.

En cuanto al estilo, quizás la convención más notable es el uso frecuente y apropiado de las palabras de requisitos - "DEBE", "NO DEBE", "DEBE", "NO DEBE" y "PUEDE", según se define en RFC 2119 .

Partes interesadas, ciclo de vida y gestión

Antes de adentrarnos en los beneficios de los AIP, hablemos de algunos de los conceptos básicos.

Interesados

Hay múltiples partes interesadas involucradas en la creación de cada AIP. Por supuesto, están los autores de propuestas, que a menudo son productores de API. Los autores no solo conciben la idea de la propuesta, sino que también sugieren su alcance y contenido. Además, están los editores, quienes determinan si un AIP es apropiado y ayudan a refinar las mejores prácticas incluidas en él. En el momento de redactar este documento, solo hay cuatro editores de AIP.

Ciclo vital

En términos de ciclo de vida, los AIP también son relativamente sencillos: cada propuesta tiene uno de siete estados diferentes en un momento dado:

  • Borrador : sus autores están determinando el alcance y el contenido del AIP.
  • Revisión : los editores están revisando el AIP. Los editores pueden proporcionar comentarios en esta etapa.
  • Aprobado : los editores han aceptado el AIP. Los ingenieros de Google deben seguir las pautas incluidas en la propuesta.
  • Retirada : sus autores han retirado el AIP. Los nuevos autores pueden continuar su desarrollo.
  • Rechazado : los editores han rechazado el AIP.
  • Diferido : el AIP no se ha actualizado durante un período de tiempo significativo.
  • Reemplazado : el AIP ha sido reemplazado por otro AIP.

Estos son similares a los estados utilizados para describir las propuestas de mejora de Python , con algunas pequeñas excepciones.

administración

Cuando se trata de cómo se gestionan los AIP, las cosas empiezan a ponerse interesantes. En primer lugar, los AIP no son solo una colección de documentos que se encuentran en un Google Drive en algún lugar. No, de hecho, todos son archivos alojados y editados en un repositorio de GitHub dedicado . La biblioteca AIP de cara al público en es simplemente una representación estática de estos archivos.https://google.aip.dev/

Esto hace posible utilizar todas las excelentes funciones de GitHub para administrar la creación, modificación y discusión de AIP. Por ejemplo, todas las propuestas nuevas comienzan su vida cuando los autores abren un número . De manera similar, la retroalimentación de los AIP existentes se envía abriendo un problema. Finalmente, el historial de confirmaciones de GitHub se encarga de la gestión de cambios.

¿Cuáles son los beneficios de usar AIP?

Aunque parecen simples, los AIP han logrado mejorar la coherencia entre las API de Google. Después de un análisis, creemos que podemos atribuir esta mejora a tres beneficios diferentes de los AIP:

Estructurado

Es tentador recopilar directrices de diseño en unos pocos documentos de texto y lanzarlas a la nube; sin embargo, está claro que el enfoque AIP tiene una estructura considerablemente mayor. Los meta-AIP no solo establecen cómo se dividen las pautas entre los AIP, sino que también definen los estándares para las propuestas en sí mismas, lo que garantiza que sean fáciles de consumir.

Colaborativo

Los AIP son un esfuerzo colaborativo que presenta a varios autores (que a menudo son productores de API que trabajan en primera línea) y diferentes editores. Esto significa que el consenso se establece desde el principio dentro de un grupo de contribuyentes variados. Sin mencionar que cualquiera puede proporcionar comentarios abriendo un problema en GitHub.

Iterativo

Alojado en GitHub, que se describe a sí mismo como una plataforma de control de versiones , los AIP siempre están listos para ser iterados. Aquí no hay reinvención de la rueda; es solo GitHub haciendo lo que mejor sabe hacer: ¡administrar el cambio!

Implementación de AIP internamente

Si cree que los AIP podrían beneficiar a su organización, la buena noticia es que a Google le complace que los implemente. Simplemente bifurque el proyecto GitHub, cambie algunas líneas en el _config.yaml, ¡y listo! Dado que los AIP se alojarán en su propio dominio, puede agregarlos, eliminarlos o editarlos según lo desee.

Para obtener más información sobre la adopción de AIP, consulte la guía oficial .

Pensamientos finales

Una parte esencial de cualquier programa de gobernanza de API es una guía de estilo completa, que describe los estándares y las mejores prácticas que los desarrolladores de toda la organización deben seguir. Las propuestas de mejora de API de Google son una versión única de la guía de estilo, que aprovecha GitHub para permitir la colaboración y la mejora iterativa.

Publicar un comentario

0 Comentarios