Header Ads Widget

Ticker

6/recent/ticker-posts

Diseño de API: creación y aplicación de una guía de estilo interna

 

Creación y aplicación de una guía de estilo de API interna

En nuestra publicación reciente sobre sugerencias para comenzar un viaje de API públicas , mencionamos brevemente la idea de crear una guía de estilo que ayude a los proveedores de API a producir API consistentes y bien construidas como parte de su oferta de API pública. Sin embargo, la creación de una guía de estilo de API es relevante para los proveedores de API, independientemente de si están proporcionando API de manera externa o interna: proporciona el contexto para sus esfuerzos de desarrollo, ya sea que se subcontraten o se creen internamente y es una herramienta importante para lograr cierto nivel de gobernanza en toda la organización.

En esta publicación, hemos analizado más detalladamente lo que podría contener una guía de estilo y cómo podría aplicarse.

Enfoque general

La función principal de una guía de estilo de API es brindar a los desarrolladores de su organización la dirección sobre cómo crear sus API, incluidos los requisitos sobre la construcción de la API y las características que implementa. En términos de un enfoque general, el tono de una guía de estilo puede caer en cualquier lugar de un espectro entre autoritario y autónomo , y los desarrolladores tienen libertad de elección en relación con ella. Cada enfoque tiene implicaciones sobre cómo se escribirán y publicarán las API dentro de una organización:

  • Un enfoque autoritario es una guía de estilo de arriba hacia abajo, que dicta cómo los desarrolladores deben diseñar y construir sus API y exige la gran mayoría de su enfoque. Es más probable que este tipo de guía se implemente en organizaciones con una función de gobernanza arquitectónica "sólida" y un enfoque razonablemente homogéneo para el desarrollo de software; es probable que incorporen principios de diseño exhaustivos, como el estilo de las directrices API de Microsoft recientemente publicadas Este enfoque tiene beneficios donde las organizaciones deben ser prescriptivas en cómo se desarrollan las API para lograr un determinado nivel de consistencia, lo que beneficia la experiencia del desarrollador.para los consumidores de API, pero claramente limita la libertad de elección de los desarrolladores al crear una API. Lo más probable es que la aplicación de la guía de estilo provenga de procesos de revisión al estilo de un comité y un modelo promocional cerrado;
  • El enfoque autónomo es una guía de estilo más ascendente, con pautas generales para garantizar que el desarrollo de API dé como resultado API que se puedan describir, proporcionar y exponer o descubrir sin centrarse demasiado en cómo lograrlo. Este enfoque es análogo a los objetivos del enfoque de ingeniería de Spotify , con el objetivo de garantizar que los equipos estén alineados con la dirección de la organización, pero que puedan usar su iniciativa cuando realmente construyan las API de las que son responsables. Por lo tanto, es probable que la aplicación de la guía de estilo en este entorno descentralizado sea propiedad de los propios equipos, con la revisión del diseño de la API como parte integral de las prácticas de trabajo de los equipos y posiblemente incorporando una integración continua.características que verifican automáticamente la semántica de la API cuando se construye se activa,

Al leer estas dos descripciones, uno puede sentir que el enfoque autónomo es "mejor" que el enfoque autoritario, pero en realidad las definiciones no están diseñadas para transmitir un sentido de mejores prácticas: simplemente reconocen el hecho de que cada organización es diferente y necesitará abordar Desarrollo de API en consecuencia. Por ejemplo, en organizaciones que subcontratan regularmente el desarrollo de software será ventajoso contar con una guía de estilo autoritaria, ya que esta se puede incorporar fácilmente a las obligaciones impuestas al proveedor y formar parte del contrato.

Con el enfoque general en mente, hay varias áreas clave que una guía de estilo debe cubrir, a saber: construcción, descripción, datos, codificación, enlaces y control de versiones. Si bien esta lista no pretende ser exhaustiva, estas son las áreas que probablemente tendrán el mayor impacto en la creación de API en su organización.

Este artículo se centra en los componentes básicos de una guía de estilo de API con vistas a escribir la suya propia. Sin embargo, si se adapta a sus propósitos (especialmente si es nuevo en las API), no hay nada de malo en bifurcar una guía de estilo hecha pública por un proveedor de API existente para darle un punto de partida. Por ejemplo, la guía de estilo de PayPal se ha bifurcado 64 veces al momento de escribir este artículo.

Construir

Construct es un catchall que cubre los bloques de construcción fundamentales de una API. Probablemente los más importantes sean:

  • Recursos (URI);
  • Métodos HTTP;
  • Encabezados HTTP;
  • Parámetros de consulta;
  • Códigos de retorno.

Cualquiera que observe estas cinco áreas y sea experto en HTTP y API REST argumentaría que todas ellas están diseñadas para propósitos específicos y claramente solo deben usarse con esos propósitos en mente; Ciertamente, muchos percibirán que DESCANSO está bien, DESCANSO. Sin embargo, es muy posible que muchos desarrolladores que crean su API no sepan (y en algunos casos realmente no les importe ) las distinciones o los principios fundamentales de REST; muchos simplemente verán formas pragmáticas de hacer su trabajo, a menudo basándose en su conocimiento y experiencia previos, y elegirán un enfoque en consecuencia.

El trabajo de la guía de estilo es, por lo tanto, detallar cuándo y cómo usar cada uno de ellos: limita la interpretación cuando es necesario establecer límites. Un ejemplo de conjunto de pautas podría ser:

  • Los recursos deben describir los "objetos" que describe su API, con un identificador que identifique de forma única cada objeto;
  • Los métodos HTTP se utilizan para "cambiar" el estado del objeto, con una lista obligatoria de métodos compatibles;
  • Los encabezados HTTP se utilizan para pasar argumentos obligatorios como autenticación, tipos de contenido aceptados, etc .;
  • Los parámetros de consulta se utilizan para argumentos opcionales y se pueden omitir según sea necesario;
  • Los códigos de retorno deben reflejar el significado y la semántica de la especificación HTTP central , asegurando que el código sea informativo y esté adornado con información adicional en la carga útil cuando sea necesario.

La idea de tales pautas es, por lo tanto, diseñar claramente para los desarrolladores cómo tratar cada uno de estos tipos de construcciones: para definir para qué sirve y cómo implementarlo. Las guías de estilo más autoritarias se sumergirán en áreas como las construcciones de recursos exactas y los encabezados HTTP permitidos, por lo que dejarán pocas dudas en la mente del desarrollador.

Vea también cómo la elaboración de una guía de marca para desarrolladores de API puede ayudar a su negocio de API

Descripción

Además de estandarizar la descripción, la guía de estilo de una organización también debe definir cómo se describen sus API; los dos temas en realidad complementan cada uno cuando una organización busca utilizar el diseño de API primero, dado que los desarrolladores considerarán activamente cómo describir sus API antes de escribir cualquier código.

Sin embargo, para describir una API, una organización necesita definir un método para hacerlo y la guía de estilo debería ayudar al desarrollador a definir las expectativas. En un extremo del espectro, una guía autoritaria exigirá un formato de descripción de API determinado (OpenAPI, RAML, etc.) y detallará los estándares organizativos, como los campos obligatorios y las extensiones personalizadas que sean necesarias. Por otro lado, una guía de estilo autónoma podría definir pautas más flexibles simplemente indicando que se debe describir una API y luego dejando que los equipos seleccionen su especificación preferida; la guía de estilo también puede incluir notas sobre el uso de API Transformer o api-spec-converter para saltar entre diferentes formatos de especificación.

También es importante tener en cuenta que su elección del formato de descripción de API también puede excluir ciertas prácticas de diseño; Lo que se puede expresar fácilmente en una especificación OpenAPI puede ser imposible de expresar en una especificación API Blueprint , por ejemplo. Por lo tanto, su elección del formato de descripción de la API debe complementar su guía de estilo tanto como sea posible.

Los datos, la codificación y los enlaces forman un triunvirato de factores que pueden moldear cómo se construye la carga útil de respuesta de una API. Al igual que con nuestras otras áreas, el enfoque general de la guía de estilo puede influir significativamente en cómo se definen estas áreas:

  • Un enfoque autoritario será explícito con lo que se permite y no se permite incluir, con referencias específicas al modelo de datos de la empresa y la procedencia de cualquier campo en la carga útil;
  • Un enfoque autónomo, por otro lado, permitirá cierto grado de flexibilidad, permitiendo a los equipos definir su carga útil y construcciones de datos de la manera que mejor se adapte a ellos.

Cualquiera que sea el enfoque que prevalezca, hay algunos aspectos fundamentales sobre este tema que deben encontrarse en cualquier guía de estilo:

  • Qué datos deben devolverse: por ejemplo, cómo debe expresarse un identificador único para un miembro dado de una colección, soporte para la paginación, filtrado de GET grandes, etc .;
  • Qué codificación debe admitirse: la mayoría de las API web nuevas tienden a implementar solo JSON, pero hay casos en los que las API admiten especificaciones de codificación alternativas, como XML . La guía de estilo debe definir qué es obligatorio, qué alternativas se pueden implementar y cómo abordar la transposición entre diferentes especificaciones;
  • El uso de enlaces: las API de hipermedia han sido consideradas durante mucho tiempo por muchos en la industria como la forma de implementar enlaces de datos en múltiples puntos finales o API, con identificadores para elementos de datos relacionados implementados como enlaces en lugar de un simple identificador sustituto o canónico. Sin embargo, hacerlo de manera coherente en toda la organización exige una singularidad de propósito que una guía de estilo puede ayudar a cumplir. Además, hay ocasiones en las que es deseable incluir en lugar de vincular los datos con fines de eficiencia. Por lo tanto, la guía de estilo debe definir un enfoque organizacional para las API de hipermedia y, cuando se promuevan, definir pasos prácticos para hacerlas funcionar.

Al igual que las construcciones de su API, garantizar la coherencia en estas áreas ayudará a garantizar la facilidad de uso para sus consumidores de API y generará un nivel de familiaridad cada vez que trabajen con una de sus API.

Lea también: Una guía humana para redactar la política de la plataforma API

Control de versiones

Obtener el control de versiones correcto puede tener un gran impacto en la forma en que los consumidores de API perciben su API interna o externamente, y también puede dificultar la administración de su estado de API si está mal concebido. Por lo tanto, el control de versiones es una parte importante de una guía de estilo y probablemente sea más importante crear una política de manera exhaustiva en toda su organización; Si todos los equipos adoptaran enfoques diferentes, como lo harían en un modelo autónomo, la gestión de las dependencias entre las API en toda su organización será realmente muy difícil.

Por lo tanto, se debe definir una política de control de versiones de arriba hacia abajo, con pautas claras sobre cuándo y por qué versionar sus API; por ejemplo, la importancia de los cambios importantes, el uso de versiones mayores y menores, etc. Se debe otorgar cualquier flexibilidad a los equipos en el cómo , permitiéndoles implementar las solicitudes de versión como mejor les parezca (en encabezados personalizados, el encabezado Accept o como parte del URI).

Pensamientos finales

En esta publicación, hemos tratado de centrarnos en lo que debe contener una buena guía de estilo y cómo la estructura del equipo y el enfoque organizacional pueden influir en ella. Independientemente de la corrección técnica, el aspecto más importante de la guía de estilo es establecer el tono para el desarrollo de API ; ayudará a definir su personaje como proveedor de API y proporcionará cohesión en toda su organización a medida que emprende su viaje de API.

Publicar un comentario

0 Comentarios