Las revisiones de diseño de API están muertas. ¡Larga vida a las revisiones de diseño de API!

Jul 28, 2023

Artículos de la página de inicio de InfoQ Las revisiones de diseño de API están muertas. ¡Larga vida a las revisiones de diseño de API!

22 de mayo de 2023 Lectura de 8 minutos

por

Jason Harmon

revisado por

Thomas Betts

En el proceso de diseño de API a escala, se necesita un esfuerzo deliberado para crear coherencia. La principal diferencia entre un montón de API y algo que parece una verdadera plataforma es la coherencia. En este caso, la coherencia simplemente significa que si utiliza varias API, factores como las convenciones de nomenclatura, los patrones de interacción como la paginación y los mecanismos de autenticación son estándar en todos los ámbitos.

Tradicionalmente, los comités de revisión han traumatizado a los desarrolladores de API con descubrimientos que provocan retrasos cuando se cree que el desarrollo está completo. Peor aún, el diseño por comité puede tomar el control, estancando el progreso o alentando a los desarrolladores a encontrar formas de eludir el proceso para evitar el dolor por completo.

Para desbloquear verdaderamente una plataforma moderna, la habilitación a través de una gobernanza descentralizada es un enfoque mucho más escalable y atractivo. Esto simplemente significa que cada dominio o área funcional tiene un experto en la materia que ha recibido formación sobre los estándares y la arquitectura general para ser una guía bien preparada para los desarrolladores de API.

Proteger las identidades. Servicios digitales seguros. Habilite el acceso de usuario escalable y seguro a aplicaciones web y móviles. Empiza la prueba gratuita.

Más importante aún, acordar el diseño de la API antes de que se complete la mayor parte del desarrollo puede evitar en gran medida descubrimientos de último momento que pongan en peligro los plazos de entrega (a menudo denominado enfoque de diseño primero). El uso de un formato de especificación como OpenAPI (el estándar de facto para las API HTTP/"REST") proporciona la capacidad de definir una API antes de cualquier desarrollo, lo que permite una alineación e identificación de problemas mucho más tempranas.

Con este contexto en mente, echemos un vistazo más de cerca a cómo realizar revisiones de diseño de API y cómo desarrollar procesos y preparar a la organización para evitar plazos prolongados y una falta de participación de los desarrolladores.

A continuación se detallan algunos requisitos previos clave para garantizar un proceso sin problemas:

El uso de API es una experiencia muy refinada y, como tal, el impacto del lenguaje es desproporcionadamente mayor que el de la mayoría de los otros ámbitos del diseño. Cada miembro del equipo puede tener una forma ligeramente diferente de definir y describir varios términos, lo que se manifiesta en confusión y menor productividad para los equipos de API.

Si bien los portales y la documentación de API son esenciales para una excelente experiencia de desarrollador, las API bien diseñadas deberían contar la mayor parte de la historia sin tener que pensar mucho en ello. Si los términos son familiares para el consumidor y los patrones de interacción son obvios, entonces la experiencia puede ser rápida e indolora. La coherencia es la principal diferencia en la experiencia entre un conjunto de API y algo que parece una sola plataforma.

Al establecer su programa API y su proceso de gobernanza, comience con un lenguaje compartido. Si bien puede parecer imposible al principio, definir un vocabulario/gramática compartidos centrados en el cliente para su plataforma es esencial y un acelerador general para una organización. Muchos términos pueden tener diversos significados dentro de una empresa y, para empeorar las cosas, suelen ser términos que los consumidores finales ni siquiera reconocerían.

Hacer esta tarea por adelantado evita conflictos sobre los nombres durante el diseño de las API. Trabaje en cada dominio con las partes interesadas relevantes para definir la terminología compartida y garantizar una amplia disponibilidad y conocimiento para los diseñadores de API. Y una vez que se haya decidido por la estandarización interna de los términos, no olvide comprobar si se ajusta también a sus necesidades externas. Usar el lenguaje del cliente y tener una visión del desarrollo de API centrada en el cliente ayuda a los equipos a evitar confundir a sus clientes con términos técnicos desconocidos, así que asegúrese de que haya sincronización entre su comprensión interna y externa.

Cuando los consumidores de API encuentran modelos o parámetros que varían entre las API, puede ser un proceso confuso, frustrante y que requiere mucho tiempo. Por ejemplo, si utiliza una API que hace referencia a información de contacto y la siguiente API en la misma plataforma utiliza un modelo completamente diferente, los consumidores a menudo tienen que resolver estas diferencias. Peor aún, pueden surgir diferencias sistémicas en el manejo de estos datos, creando diferencias funcionales.

Lo antes posible, identifique los componentes comunes (modelos, parámetros, encabezados, etc.) y los sistemas que los respaldan. La vinculación a componentes compartidos en las definiciones de API garantiza que los cambios futuros en esos componentes sean más fáciles de implementar en toda la plataforma, además de reducir la carga cognitiva indebida sobre los consumidores de API.

Cuantos más componentes comunes tenga, mayores serán las oportunidades para lograr una mayor coherencia, reutilización, mayores oportunidades de colaboración y mayor eficiencia. A todos los que estamos en el mundo de los desarrolladores nos encanta el 'método DRY' (No te repitas), y cuantos más componentes compartidos haya, más fácil será innovar sin tener que hacer lo mismo desde cero una y otra vez. Los componentes compartidos también permiten que su equipo escale rápidamente, capacitando fácilmente a nuevos desarrolladores o partes interesadas fuera del equipo de API.

Para la gran mayoría de convenciones de nomenclatura simples, patrones de interacción y mecanismos de autenticación, se puede proporcionar automatización con guías de estilo para detectar inconsistencias lo antes posible.

Las primeras guías de estilo se desarrollaron entre 2013 y 2015, estableciendo expectativas de apariencia (también conocida como DX) para los equipos de desarrollo de API. La necesidad de coherencia en el diseño fue evidente desde el principio del desarrollo de la plataforma API, y los primeros esfuerzos de Paypal (¡de hecho, yo era parte de este equipo en aquel entonces!) y Heroku dieron como resultado algunas de las primeras guías de estilo de programas exitosos que se publicaron. compartido públicamente.

Si bien hay una variedad de herramientas de automatización disponibles para ayudar con las guías de estilo, la herramienta de código abierto Spectral se ha convertido en un estándar para definir conjuntos de reglas de linting API. Alinear por adelantado las convenciones para rutas, parámetros y más, y definir reglas de linting automatizadas evitará demoras por conflictos sobre qué convenciones son "correctas". Tenga la discusión una vez y defina reglas... trate de no volver a hablar de eso; ¡simplemente haz que los errores de pelusa desaparezcan!

Para los estándares de diseño que no se pueden automatizar, estos deben documentarse y ponerse fácilmente a disposición de los diseñadores de API. La capacitación que explica la importancia de las reglas automatizadas y verificadas manualmente puede generar motivación en los desarrolladores para apoyar plenamente la iniciativa y evitar sorpresas y fricciones.

Si bien debería existir un equipo de habilitación de API para seleccionar estos estándares de diseño y fomentar la comunidad, se debe habilitar la autoridad en cada área funcional o dominio.

Aunque los estándares API son importantes, el conocimiento del dominio sobre las limitaciones sistémicas, las necesidades específicas de los clientes y las fortalezas y debilidades de la organización es mejor que lo maneje un experto que sea parte de ese mundo. Si se espera que los miembros del equipo de habilitación de API centralizada sepan todo lo relacionado con la empresa, los cuellos de botella que provocan retrasos en la entrega y la falta de compromiso de los desarrolladores están casi garantizados.

Los talleres de capacitación pueden ser una técnica poderosa para crear conciencia sobre la importancia de los estándares API. Además, a menudo descubrirá las PYME adecuadas para proporcionar autoridad de gobernanza. Busque personas que expresen pasión por las API (a menudo me refiero a ellas como una "banda de rebeldes"), que muestren conciencia de la relevancia de la coherencia y los estándares, y que tengan el respeto técnico de sus pares y/o informes.

Desarrollar una API exitosa involucrará a muchas personas de su organización, a menudo con conjuntos de habilidades contrastantes, algunos que construirán e implementarán la API y otros que estarán en el lado estratégico del problema comercial identificando el valor de su API. No olvide también a las partes interesadas del negocio cuando se trata de a quién involucrar en la revisión del diseño. A menudo sólo incluimos el aspecto técnico, lo que puede provocar fallos en el futuro. ¡Cuantas más perspectivas, mejor!

Su plataforma debe tener gerentes de producto que estén de acuerdo con la composición general de la cartera/catálogo de API. Los catálogos vienen en muchas formas diferentes y organizan sus API para que sea más fácil encontrar lo que necesita sin necesidad de saber exactamente lo que está buscando. Permite a los usuarios potenciales navegar a través de las API disponibles agrupadas por funcionalidad u otras inquietudes de los usuarios.

Los buenos catálogos se pueden buscar o filtrar para que los desarrolladores puedan limitar fácilmente las opciones y ofrecen detalles comparables y digeribles para cada API del catálogo que ofrece un camino claro a seguir.

Para cualquier API nueva propuesta, se debe revisar lo antes posible una descripción general funcional con casos de uso y nombres básicos. Esto garantiza la alineación del lenguaje, la reutilización y el "ajuste" general de una nueva API con la perspectiva de la plataforma más amplia.

Su equipo de habilitación debe tener gerentes de producto que sean dueños del proceso de alineación de la cartera, y cada uno debe poseer una colección manejable de dominios. Como mínimo, es clave contar con un lugar regular para que los PM de dominios específicos mantengan discusiones sobre alineación.

Si bien esto puede parecer mucho, recuerde que los estándares API deben evolucionar a través de la iteración. A medida que se diseña cada API, reconocerá oportunidades para perfeccionar los estándares. Con eso en mente, asegúrese de que los conceptos básicos estén cubiertos en su tarea inicial y asegúrese de que los gobernadores de API tengan una comprensión clara de cómo proponer y adoptar cambios en los estándares.

Si ha completado los requisitos previos anteriores, ¡no hay mucho que hacer en la revisión del diseño de API! Si se trata de PYME centradas en un dominio, la revisión del diseño a menudo puede integrarse en gran medida en los esfuerzos de diseño en curso. Si el "ajuste" en la plataforma se alinea temprano, los revisores de diseño deben tener la confianza de que esta API pertenece al panorama general. Además, si los diseñadores de API ven errores de linting mientras iteran, no debería haber discusiones sobre convenciones básicas más allá de educar a los desarrolladores sobre la relevancia de varias reglas de linting, o simplemente cómo resolver errores de linting.

No todo se puede automatizar y, a veces, las necesidades de arquitectura y producto pueden entrar en conflicto. Haga que la revisión del diseño de su API sea un momento en el que se verifiquen las convenciones aplicadas manualmente, se valide el lenguaje del cliente (ya que esto es difícil de automatizar) y se consolide la alineación final. Con ese alcance en mente, las reuniones a menudo se pueden evitar y las discusiones asincrónicas a menudo pueden ser suficientes.

Lo más importante es estar atento al tiempo del ciclo de revisión del diseño de API... debería disminuir claramente con el tiempo a medida que las PYME más descentralizadas se sientan más cómodas con los estándares existentes y cómo adoptar nuevos estándares.

Escribir para InfoQ ha abierto muchas puertas y aumentado las oportunidades profesionales. para mí. Pude interactuar profundamente con expertos y líderes de opinión para aprender más sobre los temas que cubrí. Y también puedo difundir mis conocimientos a la comunidad tecnológica en general y comprender cómo se utilizan las tecnologías en el mundo real.

¡Descubrí el programa de colaboradores de InfoQ a principios de este año y lo he disfrutado desde entonces! Además de brindarme una plataforma para compartir aprendizaje con una comunidad global de desarrolladores de software, el sistema de revisión entre pares de InfoQ ha mejorado significativamente mi escritura. . Si está buscando un lugar para compartir su experiencia en software, comience a contribuir a InfoQ.

Comencé a escribir noticias para la cola InfoQ .NET como una forma de mantenerme actualizado con la tecnología, pero saqué mucho más provecho de ello. Conocí gente conocedora, obtuve visibilidad global y mejoré mis habilidades de escritura..

Convertirme en editor de InfoQ fue una de las mejores decisiones de mi carrera . Me ha desafiado y me ha ayudado a crecer de muchas maneras. . Nos encantaría tener más gente.Unete a nuestro equipo.

InfoQ busca un editor en jefe a tiempo completo para unirse al equipo internacional y siempre remoto de C4Media. Únase a nosotros para cubrir las tecnologías más innovadoras de nuestro tiempo, colabore con los profesionales de software más brillantes del mundo y ayude a más de 1,6 millones de equipos de desarrollo a adoptar nuevas tecnologías y prácticas que superan los límites de lo que el software y los equipos pueden ofrecer.

Todos los martes se envía un resumen del contenido de la semana pasada en InfoQ. Únase a una comunidad de más de 250.000 desarrolladores senior. Ver un ejemplo

Protegemos su privacidad.

Debe registrar una cuenta InfoQ o iniciar sesión o iniciar sesión para publicar comentarios. Pero hay mucho más detrás de estar registrado.

Aproveche al máximo la experiencia InfoQ.

HTML permitido: a,b,br,blockquote,i,li,pre,u,ul,p

HTML permitido: a,b,br,blockquote,i,li,pre,u,ul,p

HTML permitido: a,b,br,blockquote,i,li,pre,u,ul,p