Get best of the week

API Style Guide, o no hagas que los usuarios piensen



¡Hola! Mi nombre es Lesha Rutskoi y soy gerente de producto en Wrike. Antes de eso, trabajó en Adform y PandaDoc. Durante los últimos cinco años, he estado haciendo todo lo relacionado con integraciones y API.

Wrike es un producto de colaboración y gestión de proyectos SaaS. Queremos que los desarrolladores creen sus soluciones basadas en Wrike, y para esto necesitamos que nuestra API sea conveniente. Al mismo tiempo, tenemos 9 oficinas en todo el mundo, y 3 de ellas son oficinas de desarrollo. Es bastante difícil crear una API consistente utilizando equipos distribuidos que hablen diferentes idiomas. Hay una probabilidad creciente de que sus decisiones comiencen a contradecirse entre sí. En este caso, uno no puede prescindir de un conjunto uniforme de reglas para todos.

Si también trabaja de manera distribuida y crea su propia API, entonces la API de la guía de estilo puede ayudarlo. Quiero decirte qué problemas comunes resuelve y cómo facilita la vida de los desarrolladores. También compartiré mi experiencia al escribir e implementar mi propia Guía de estilo API en la empresa.

¿Por qué necesitamos una API conveniente?


Muchos lectores probablemente tuvieron que resolver problemas utilizando la API no tan conveniente. Sí, esto no es muy simple y lleva más tiempo, pero generalmente aún puede resolver el problema.

Entonces, ¿por qué perder el tiempo y el esfuerzo del equipo para mejorar la API? La respuesta es bastante simple: muy a menudo la decisión sobre el uso de su producto la toman los desarrolladores, especialmente cuando se trata de API e integraciones. Por lo tanto, es importante pensar no solo en la experiencia del usuario (UX), sino también en la experiencia del desarrollador DX.

Daré un ejemplo. Una vez trabajé en un equipo responsable de toda la integración del producto. A menudo, a mediados del trimestre, cuando nuestros planes ya estaban delineados, un vendedor venía y decía: “Z ha creado un nuevo mercado y lanzará la próxima versión de su plataforma. ¡Pronto tendrán un evento público genial donde podremos hablar sobre nuestra integración y éxito! Será genial si escribimos rápidamente esta integración ahora ”. ¿Qué hicimos en este caso? Si un desarrollador experimentado en un equipo pudiera hacer el prototipo mínimo de trabajo en tres días, la mayoría de las veces en dos o tres semanas logramos llevar la tarea a la condición perfecta. Si faltaban unos días, entonces la API y la documentación eran más o menos.No tenía sentido volver a dibujar los planes y emprender una nueva integración; de todos modos, nada valioso habría funcionado para la fecha de vencimiento. Recuerde que su producto puede estar en tal situación: los socios decidirán si tratarán con usted dependiendo de qué tan rápido y convenientemente pueda comenzar a trabajar con su API.

Pero casi nadie quiere diseñar una mala API. ¿Por qué todos se vuelven diferentes? Por lo general, una API se desarrolla así. Cuando una startup comienza a crecer y los primeros clientes llegan a ella, uno de los equipos establece su punto final y decide transferir la versión a la URL:

imagen

gradualmente aparecen nuevos clientes y nuevas necesidades. Los chicos del segundo equipo están incluidos en el trabajo, quienes creen que es mejor usar sus propios tipos de medios para el control de versiones:

imagen

después de un tiempo, llega el tercer equipo. En una conferencia, se enteran de que Stripe está versionando su API con las principales fechas de lanzamiento. Y deciden hacer lo mismo:

imagen

el resultado es una API en la que hay tres métodos de control de versiones. Todos los métodos funcionan, pero funcionan de manera diferente.

Como desarrollador, sería inconveniente para mí usar una API de este tipo. Y la razón no es que prefiera un enfoque para versionar a todos los demás. Solo usar varios métodos al mismo tiempo es inconveniente. Tendrá que escribir tres veces el código que funciona con la API, o usar tres bibliotecas diferentes. Y esto significa que habrá tres veces más errores.

Y hay fechas y horas. Incluso utilizando el enfoque estándar, los datos pueden transmitirse de diferentes maneras: por la zona horaria de su servidor, por GMT, por la hora del cliente, en la hora de Unix. Los clientes deberán llevar todos los datos a un formato.

Los mensajes de error generalmente hacen todo de manera diferente. Por ejemplo, así:

imagen

O así:

imagen

también está mi mensaje de error favorito: una respuesta vacía:

imagen

Bueno, solo un clásico: la respuesta es 200 OK, dentro de la cual se encuentra JSON con una descripción de lo que salió mal.

En mi opinión, lo más importante en una buena API es la consistencia . No importa qué enfoque de versiones elija, lo principal es que sea el mismo en toda la API. Una solución aún más exitosa sería adoptar el enfoque popular que otras compañías ya están tomando. Lo más probable es que sus clientes ya lo hayan encontrado y tengan un código listo para usar o una biblioteca. No necesita pensar de nuevo, puede usar herramientas listas para usar.

Un enfoque único para crear una API es especialmente importante para las grandes empresas con equipos distribuidos. Si diez personas en la sala crean una startup, entonces cada desarrollador puede simplemente golpear a un vecino en el hombro y aceptar o ver los principales problemas durante la revisión del código. En una gran empresa, se vuelve más difícil.

La API de la guía de estilo lo ayudará a resolver estos problemas. Este es un documento que describe los principios de diseño de su API. Si todos usan los mismos enfoques, parece que la API fue desarrollada por una persona y no por muchos equipos diferentes. Este enfoque es muy similar a la Guía de estilo de código cuando los equipos acuerdan cómo escriben el código. Una persona de un equipo puede mirar la base del código de otro equipo y comprender rápidamente lo que está sucediendo allí.

¿Cómo hacer tu propia guía de estilo API?


Arnauld Lauret (conocido como API Handyman ) creó un sitio genial: API Stylebook . Creó una Guía de estilo de acceso público, que varias compañías (Cisco, Google, Red Hat, agencias gubernamentales y muchas otras) pusieron en el dominio público.

Las pautas se dividen en temas en el sitio. Por ejemplo, si está interesado en el control de versiones, en la pestaña Control de versiones puede averiguar cómo diferentes empresas resuelven este problema.

¡Aprende de la experiencia de los demás! Pero copiar completamente la Guía de estilo de otra persona no es una buena idea. Aún así, resuelve los problemas de otra compañía, no la suya.

En su Guía de estilo, debe agregar temas cercanos a su empresa y resolver sus problemas. Tal vez tenga muchas aplicaciones móviles, y el tamaño de la respuesta es importante para usted. Luego describa los principios asociados con este aspecto. O estuvo de acuerdo con los equipos internos en que era hora de ver el monolito en microservicios que se comunicarían entre sí a través de Message Broker. En este caso, debe incluir los principios según los cuales va a utilizar Kafka o alguna otra herramienta en la Guía de estilo API.

Qué más incluir en la API de la Guía de estilo


Además, la Guía de estilo debe incluir los valores básicos y los enfoques de ingeniería a los que se adhiere la empresa.

¿Qué pueden ser?

  • Write APIs in English. , . - , , . Style Guide, , .
  • API First principle. API : , , frontend-. , API . , , .
  • Use REST y JSON. Esto puede ser importante si desea que la audiencia más amplia posible use su API o plataforma. A pesar de que GraphQL se ha vuelto cada vez más popular desde 2017, no todos lo saben. La mayoría de los desarrolladores, muy probablemente, nunca lo han usado, lo que significa que aumentarán el tiempo de inmersión y desarrollo. ¿Por qué crear complejidad?

Además, los principios básicos se pueden establecer sobre los temas. Por ejemplo, dentro del principio de usar REST y JSON, puede determinar fácilmente qué temas deben describirse en la Guía:

  • Prefiere API REST con cargas JSON
    • Solicitudes HTTP
    • Códigos de estado HTTP
    • Json

Más adelante en cada tema, puede llegar a las reglas que todos los equipos de la empresa deben seguir:

  • Solicitudes HTTP
    • DEBE usar los métodos HTTP correctamente
    • Los encabezados HTTP personalizados DEBEN seguir la convención de nomenclatura

Me gusta mucho el enfoque que describe la necesidad de seguir las reglas a través de los verbos DEBE, DEBE o MAYO (tomado de RFC 2119 ). Luego, todos los que lean la Guía de estilo distinguirán entre reglas obligatorias y recomendaciones.

Así es como, por ejemplo, se ve en Zalando :

imagen

Cosas a tener en cuenta al iniciar la Guía de estilo


  • . , . , , . , , . API management , . API.
  • . - 15- . rate limiting, .. — , , - .
  • . , OAuth, REST. , , , scopes .
  • . , , .
  • . , . , . . . , .
  • . , , .
  • . , , .. : , «user», , «user», .
  • . , — . , (OpenAPI-, -) . .

API Style Guide?


Ha creado su Guía de estilo API, y ahora queda por implementarla. Esto tampoco es fácil. Compartiré mi experiencia de implementar la Guía de estilo API en uno de los lugares donde trabajé. La compañía tenía una estructura compleja: cientos de ingenieros, docenas de equipos distribuidos en cuatro oficinas de desarrollo, sus colegas hablaban diferentes idiomas.

Primero necesitas convencer a los interesados. Y aquí a menudo hablamos de líderes técnicos en diversos campos y representantes comerciales. Todos deben entender qué problemas queremos resolver y cómo puede ayudar la Guía de estilo. En mi ejemplo, todas las partes interesadas entendieron que una buena API es una ventaja importante. Muchos clientes llegaron con tal solicitud, y los competidores no se durmieron y expandieron activamente el alcance de las oportunidades disponibles a través de su API.

El siguiente paso es encontrar un equipo que haga esto. En mi caso, la compañía ya tenía un equipo separado que soportaba una API externa. Ella entendió mejor la necesidad de cambio, porque constantemente se enfrentaba a dificultades en su trabajo. Los miembros de este equipo estuvieron encantados de participar en el proyecto.

¿Cómo implementó el equipo la API de la guía de estilo?

  • Ella habló sobre la iniciativa en conferencias internas y hackatones para que todos en la empresa entiendan lo que se está discutiendo. Esto ayudó a atraer personas de ideas afines que fueron muy útiles en las siguientes etapas.
  • Preparó un borrador de la Guía de estilo, que posteriormente estuvo de acuerdo con los campeones de la API (sobre ellos un poco más).
  • Presentó el proyecto a los equipos. Los chicos fueron a cada oficina de desarrollo y hablaron con casi todos los equipos, explicaron el significado del proyecto y realizaron capacitaciones.
  • Ayudado con el diseño de la API. Fue difícil para muchos equipos hacer todo en la guía la primera vez. La ayuda y las explicaciones adicionales fueron útiles aquí, especialmente en situaciones inusuales.
  • Realizó una revisión. Era importante verificar que todos los equipos actúen de acuerdo con la Guía de estilo.

Es muy difícil para un equipo de una gran empresa implementar cambios tan significativos. Necesita ayuda. Aquí los campeones de API estaban conectados: arquitectos y tecnólogos de cada dirección que ayudaron a integrar la idea en sus equipos y divisiones.

Cuando se producen cambios clave, a menudo aparece el descontento. En este caso, necesita autoridad que pueda convencer a estas personas de la necesidad de un cambio. Los tehlids son las personas más adecuadas para esto.

Los campeones de la API en un canal separado de Slack discutieron problemas emergentes y sugerencias. Los cambios menores se introdujeron de inmediato, mientras que los más grandes requirieron una discusión detallada. En este caso, el iniciador escribió una propuesta oficial: qué problema debe resolverse, qué métodos de solución ya existen, qué ventajas y desventajas tienen. Luego, durante 1-2 días, nos reunimos fuera de la oficina, discutimos ideas, elegimos una solución y la arreglamos. Luego les contamos a nuestros equipos sobre la decisión que tomamos: por qué la tomamos y qué debemos hacer a continuación.

Además, los campeones de API ayudaron a hacer revisiones en sus áreas. Los chicos de sus equipos primero se volvieron hacia ellos, y luego la revisión final fue realizada por el equipo que estaba creando la Guía de Estilo.

Después de un tiempo, una comunidad API comenzó a formarse en la empresa. Incluyó a personas que pasaron por varios ciclos de revisión, descubrieron qué es un diseño bueno y correcto, por qué es necesario y cómo hacerlo. Creamos un gran chat en el que todos podían hacer una pregunta, y los miembros de la comunidad API ayudaron a resolverlo.

No puede implementar el enfoque solo a nivel de ingeniería. Los equipos de ventas, soporte y marketing también deben comprender qué escenarios de usuario cubre la API, qué valor conlleva, cómo se relaciona con la estrategia de la empresa y cómo transmitir adecuadamente la información al respecto a los clientes.

Intentamos introducir todo esto en la incorporación de la mayoría de los equipos de la empresa, incluidos los que no son de ingeniería. Esto también es necesario para que todos entiendan cuándo, en qué casos y a quién puede acudir en busca de ayuda.

Automatización


El último tema importante es la automatización de los procesos rutinarios. La revisión puede servir como un excelente ejemplo. En una gran empresa con una gran cantidad de equipos, lo más probable es que tenga que hacer muchas revisiones. No tengo ganas de perder el tiempo en problemas básicos como una descripción de error que falta o un formato de ID incorrecto.

Algunas herramientas pueden ayudar con esto:

  • Zally de Zalando comprueba si la especificación OpenAPI coincide con su Guía de estilo API. La configuración básica de Zally verifica el cumplimiento de la Guía de estilo de Zalando, pero puede redefinir y agregar sus propias reglas.
  • Apiary's Dredd verifica si la implementación final de la API REST coincide con su diseño, es decir, las especificaciones OpenAPI, Blueprint o RAML.

Este artículo es una transcripción de mi charla con la Conferencia de Desarrolladores de Plataforma de Miro . Puedes encontrar el video del discurso aquí .

Estaré encantado de responder a sus preguntas sobre la implementación de la Guía de estilo API. ¡También será genial si compartes una experiencia similar!

¡Un agradecimiento especial a Daria Ivanova por su ayuda en la preparación de este artículo!

More articles:


All Articles