Noticias

Jul 04, 2023

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

Diseño de API de artículos de la página de inicio de InfoQ

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 8 minutos de lectura

por

jason armon

revisado por

Tomas Betts

En el curso del diseño de API a escala, se necesita un esfuerzo deliberado para crear consistencia. La principal diferencia entre un montón de API y algo que se siente como una verdadera plataforma es la consistencia. En este caso, la consistencia simplemente significa que si usa 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 hacerse cargo, deteniendo el progreso o alentando a los desarrolladores a encontrar formas de eludir el proceso para evitar el dolor por completo.

Para realmente desbloquear una plataforma moderna, la habilitación a través de la 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 sido educado sobre los estándares y la arquitectura general para ser una guía bien habilitada para los desarrolladores de API.

Proteger identidades. Servicios digitales seguros. Habilite el acceso escalable y seguro de los usuarios 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 los descubrimientos de última hora que ponen 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") brinda la capacidad de definir una API antes de cualquier desarrollo, lo que permite una alineación e identificación de problemas mucho más temprana.

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 la falta de participación de los desarrolladores.

Estos son algunos requisitos previos clave para garantizar un proceso fluido:

El uso de las API es una experiencia muy destilada y, como tal, el impacto del lenguaje es desproporcionadamente mayor que en 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 disminución de la productividad para los equipos de API.

Si bien los portales/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 consistencia es la principal diferencia en la experiencia entre un montón de API y algo que se siente como una plataforma.

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

Hacer esta tarea por adelantado evita conflictos sobre los nombres en medio del 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 verificar si también se ajusta a sus necesidades externas. Usar el idioma del cliente y tener una visión centrada en el cliente del desarrollo de API 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 la comprensión externa.

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

Tan pronto como sea posible, identifique los componentes comunes (modelos, parámetros, encabezados, etc.) y los sistemas que los respaldan. La vinculación a componentes compartidos en 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 en los consumidores de API.

Cuantos más componentes comunes tenga, mayor será la oportunidad de aumentar la consistencia, la reutilización, más oportunidades de colaboración y una mayor eficiencia. Todos nosotros en el mundo de los desarrolladores amamos el 'método DRY' (No se repita), 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 le permiten a su equipo escalar rápidamente, capacitando a nuevos desarrolladores o partes interesadas fuera del equipo de API con facilidad.

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 señalar las incoherencias lo antes posible.

Las primeras guías de estilo se desarrollaron entre 2013 y 2015, estableciendo expectativas de apariencia (también conocido como DX) para los equipos de desarrollo de API. La necesidad de consistencia en el diseño fue evidente desde el comienzo del desarrollo de la plataforma API, y los primeros esfuerzos de Paypal (¡yo era parte de este equipo en ese momento!) y Heroku dieron como resultado algunas de las primeras guías de estilo de programas exitosos que se publicaron. compartida 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 de API. Alinearse por adelantado en 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 las reglas... trate de no volver a hablar de eso; ¡solo haz que los errores de pelusa desaparezcan!

Para los estándares de diseño que no se pueden automatizar, estos deben documentarse y estar fácilmente disponibles para los diseñadores de API. La capacitación que explica la importancia de las reglas automatizadas y verificadas manualmente puede motivar a los desarrolladores para que respalden completamente la iniciativa y eviten sorpresas y fricciones.

Si bien debe existir un equipo de habilitación de API para curar estos estándares de diseño y fomentar la comunidad, la autoridad debe estar habilitada en cada área funcional o dominio.

Si bien los estándares API son importantes, el conocimiento del dominio de las restricciones sistémicas, las necesidades específicas de los clientes y las fortalezas y debilidades de la organización son manejadas mejor por un experto que sea parte de ese mundo. Si se espera que los miembros del equipo centralizado de habilitación de API sepan todo sobre la empresa, los cuellos de botella que conducen a retrasos en la entrega y la desconexión de los desarrolladores están casi garantizados.

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

El desarrollo de una API exitosa involucrará a muchas personas en 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 se olvide de las partes interesadas del negocio cuando se trata de a quién involucrar en la revisión del diseño. A menudo, solo incluimos el aspecto técnico, y eso puede resultar en fallas más adelante. ¡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 en el catálogo que ofrece un camino claro a seguir.

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

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 tener una colección manejable de dominios. Como mínimo, es clave un lugar regular para que los PM de un dominio específico tengan discusiones de alineación.

Si bien eso puede parecer mucho, recuerde que los estándares API deben evolucionar a través de la iteración. A medida que se diseñe 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 la API! Si se trata de PYMES centradas en el dominio, la revisión del diseño a menudo se puede integrar 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 lint.

No todo se puede automatizar y, a veces, las necesidades del producto y la arquitectura 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 omitir y las discusiones asincrónicas a menudo pueden ser suficientes.

Lo que es más importante, vigile de cerca el tiempo del ciclo de revisión del diseño de API... debería disminuir claramente con el tiempo a medida que las pymes 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 ha 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 aprendizajes 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 el 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 con InfoQ.

Empecé a escribir noticias para la cola de InfoQ .NET como una forma de mantenerme al día con la tecnología, pero aproveché mucho más. Conocí a gente bien informada, obtuve visibilidad global y mejoré mis habilidades de escritura..

Convertirse 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 de tiempo completo para unirme al equipo internacional, 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 amplían los límites de lo que el software y los equipos pueden ofrecer!

Todos los martes se envía un resumen del contenido de InfoQ de la semana pasada. Únase a una comunidad de más de 250 000 desarrolladores sénior. Ver un ejemplo

Protegemos su privacidad.

Debe registrar una cuenta de 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 de 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