Liberarse de trabajar solo: aprender a colaborar en el desarrollo de API con Postman

El desarrollo de API es una gran parte de lo que me encanta del software. Ya sea que se trate de crear integraciones o crear API para aplicaciones web desacopladas, generalmente somos solo yo y el código .

La mayor parte del tiempo trabajo como desarrollador de API en solitario. Ir solo tiene sus ventajas: decisiones rápidas y control total. Pero es un arma de doble filo, ya que mantener todo en mi cabeza hace que los traspasos y la delegación sean complicados. Y trabajar solo limita el tamaño y la complejidad de los proyectos en los que puedo trabajar. Después de todo, soy sólo una persona.

Postman es mi herramienta principal para el trabajo de API: enviar solicitudes, administrar entornos y ejecutar pruebas. Estoy familiarizado con mi flujo de trabajo en solitario. Pero comencé a preguntarme: en un ambiente de equipo, ¿qué más puede ofrecer Postman? ¿Cómo podría mejorar la colaboración y agilizar el proceso de desarrollo?

Para explorar estas preguntas, comencé a trabajar en una API de ejemplo, a la que llamo "X Nihilo".

API de ejemplo: X Nihilo

X Nihilo te ayuda a generar tweets de 280 caracteres basados en los parámetros que almacenas o envías. Proporcionas un tema, un objetivo, una descripción del tono a adoptar y una descripción de la audiencia. Detrás de escena, la API enviará una solicitud a la API de OpenAI para completar el texto, lo que ayudará a generar el tweet.

Además, puede guardar las cadenas que utiliza para el tono y la audiencia y luego reutilizarlas en solicitudes de tweets posteriores.

Repasemos mi flujo de trabajo básico de desarrollo de API.

Hacerlo solo: mi flujo de trabajo en solitario

El primer paso en mi flujo de trabajo es diseñar la API y redactar una especificación de OpenAPI. En Postman, creé una nueva API y luego comencé una nueva definición de API.

Después de pensar un poco (y trabajar directamente con ChatGPT, lo cual fue excelente para generar una especificación inicial de OpenAPI basada en mis descripciones), escribí mi especificación:

Con mi especificación OpenAPI implementada, llegué a una bifurcación en el camino. ¿Debo configurar un servidor simulado y algunas solicitudes y respuestas de ejemplo para mostrar cómo sería interactuar con esta API? ¿O debería empezar a escribir código de implementación?

Como desarrollador en solitario, solo puedo ser productor o consumidor de API en un momento dado. Así que decidí: no había necesidad de crear simulacros: el consumidor que hay en mí tendría que esperar. ¡Escribamos algo de código!

Unos momentos después…

Usando Node.js con Express y hablando con una base de datos PostgreSQL, implementé mi API básica. Aquí hay un resumen de todo lo que necesitaba para construir:

• POST /signin toma un username y password , se autentica con los registros de la base de datos y luego devuelve un JWT firmado, que se puede utilizar en todas las solicitudes posteriores.
• POST /generateTweet genera un tweet de 280 caracteres (máximo). Se necesita un topic (cadena) y un goal (cadena). También toma un tone (cadena) o un toneId (ID entero de un tono almacenado), junto con una audience (cadena) o audienceId (ID entero de una audiencia almacenada). Siempre que se proporcionen cadenas tone y/o audience , la API las guardará en la base de datos.
• GET /tones devuelve una lista de ID de tonos y cadenas correspondientes. GET /audiences hace lo mismo con las cadenas de audiencia reutilizables.
• DELETE /tones toma una ID de tono y elimina ese registro de tono. DELETE /audiences hace lo mismo con los registros de audiencia.

Una vez realizada la implementación inicial, llegó el momento de volver a Postman para comenzar a ejecutar algunas solicitudes.

Crea un entorno con variables.

Primero, creé un nuevo entorno llamado "Prueba". Agregué variables para almacenar mi root_url junto con un username y password válidos.

Crear una colección y una solicitud.

Luego, creé una nueva colección y agregué mi primera solicitud: una solicitud POST a /signin , para probar la autenticación.

Con mi servidor API ejecutándose en una ventana de terminal, envié mi primera solicitud.

¡Éxito! Obtuve mi token, que necesitaría en futuras solicitudes.

Creé una nueva solicitud, esta vez para generar un tweet.

Me aseguré de configurar la Autorización para usar "Token de portador" y proporcioné el token que acabo de recibir de la solicitud anterior.

Aquí está la respuesta:

¡Funciona!

Resumiendo el enfoque en solitario

Este es un adelanto básico de mi flujo de trabajo en solitario. Por supuesto, haría algunas otras cosas en el camino:

• Escriba un script de solicitud previa para realizar una solicitud /signin y luego establezca una variable de entorno basada en el token de la respuesta.
• Cree solicitudes para todos los demás puntos finales en la especificación OpenAPI.
• Escriba pruebas para cada punto final, asegurándose de cubrir mis casos extremos.

Si trabajo solo, este flujo de trabajo básico me acerca bastante a la meta. Si bien está bien, sé que probablemente solo estoy arañando la superficie de las funciones disponibles en Postman. Y sé que necesitaría mucho más de Postman si estuviera trabajando en un equipo.

El momento ajá: ¿Por qué considerar a Postman para los equipos?

¿Qué pasaría si ya no pudiera ser un desarrollador de API en solitario para X Nihilo? Esto podría suceder por varias razones:

• X Nihilo crece en tamaño y complejidad, y un único desarrollador de API ya no es suficiente para soportarlo.
• X Nihilo es solo una pequeña parte de un proyecto API más grande que involucra a varios desarrolladores de API o incluso a varios equipos de API.

No todos mis proyectos de API para clientes serán pequeños que pueda construir por mi cuenta. A veces, necesitaré ser parte de un equipo que cree una API. Puede que incluso necesite liderar el equipo de API.

Cuando eso suceda, tendré que dejar atrás mi mentalidad solitaria y dejar mi forma solitaria de hacer las cosas en Postman. Eso me motivó a investigar las características relacionadas con el equipo de Postman.

Explorando las características del equipo (empresarial) de Postman

Postman tiene un nivel gratuito y ofrece algunas funciones de colaboración limitadas, que pueden ser suficientes si eres un equipo pequeño (es decir, no más de tres desarrolladores). Postman tiene funciones adicionales como parte de su nivel Enterprise Essentials. Son excelentes para los equipos de API en organizaciones más grandes que utilizan Postman en todos los ámbitos.

Compartir espacio de trabajo

Un espacio de trabajo permite a sus equipos colaborar en múltiples proyectos API. Esto es excelente si tiene diferentes equipos trabajando en diferentes API, pero esas API interactúan entre sí (lo que suele ser el caso en organizaciones de software más grandes).

Los espacios de trabajo son excelentes para permitir la colaboración en tiempo real. Los miembros del equipo pueden editar la documentación de la API, trabajar juntos en la elaboración de solicitudes o escribir pruebas y crear un servidor simulado que todo el equipo pueda usar. A medida que se realizan modificaciones, se sincronizan con todo el equipo en tiempo real.

Control de versiones

Si bien me preocupaba el control de versiones de mi código, como desarrollador de API en solitario, no me importaba mucho el control de versiones de mis colecciones o entornos de Postman. Si cambio algo (modifico una solicitud, actualizo una prueba, elimino una variable de entorno), soy el único afectado. No es gran cosa.

Cuando trabajas en un equipo, definitivamente quieres saber cuándo cambian las cosas. Y a veces es necesario revertir los cambios. Afortunadamente, para los equipos que utilizan Postman Enterprise, Postman les brinda acceso a un registro de cambios para colecciones, espacios de trabajo y API. Puede revertir las colecciones a momentos anteriores en el tiempo. Como desarrollador de API en un equipo, necesitará esto. La mayoría de las veces es porque Bob arruinó la colección. A veces, sin embargo, eres Bob.

Acceso basado en roles y organización de usuarios

No todos en un espacio de trabajo de Postman deberían tener el mismo nivel de permisos. Algunos miembros del equipo son evaluadores y solo necesitan la capacidad de enviar solicitudes y ejecutar pruebas, pero no modificarlas. Otros pueden ser diseñadores a quienes solo se les permite modificar las definiciones de API.

En Postman, puedes asignar roles a los miembros del equipo. Esto afecta el tipo de acceso y nivel de permiso que cada miembro del equipo tiene dentro de un equipo o espacio de trabajo.

Los equipos también pueden tener espacios de trabajo privados, restringiendo el acceso de otras personas ajenas al equipo.

También noté que Postman Enterprise admite la "captura de dominio". Básicamente, esto significa que puede configurar todos los usuarios de su organización dándoles acceso a todos desde el dominio (por ejemplo) mycompany.biz .

Comentarios y debates en línea

Postman tiene una función de colaboración, que está disponible en todos sus planes, no solo en Enterprise Essentials. Esta es la capacidad de los miembros del equipo de agregar comentarios a las colecciones (en carpetas, solicitudes, ejemplos o solicitudes de extracción). Poder comentar y discutir directamente en Postman es fundamental para el desarrollo de API en equipo. Dado que la mayor parte del trabajo de desarrollo de API de su equipo se realizará en Postman, tiene sentido tener la discusión allí (en lugar de en GitHub o algún otro servicio externo).

Desarrollo de API en equipo: cartero para la victoria

Cada vez que me uno a un equipo, traigo las herramientas que me encanta usar, pero realmente no se las presiono a mis compañeros de equipo. Me imagino que tienen sus propias herramientas. Así que a cada uno lo suyo. Pero tengo la sensación de que la mayoría de los desarrolladores de API tienen a Postman en su caja de herramientas. Sería una pena que varios desarrolladores de API de un equipo usaran Postman individualmente, con una mentalidad individual y sin aprovechar algunas de estas características del equipo. Si aprovecharan las funciones de Postman Enterprise, obtendrían...

Eficiencia incrementada

En un espacio de trabajo compartido, puede comenzar con la definición de API compartida. Cada vez que un miembro del equipo edita la definición (o la documentación, las pruebas o los entornos), las ediciones se sincronizan y todos tienen lo último y lo mejor.

Todos trabajan con el mismo conjunto de solicitudes en una colección y todos tienen acceso a todas las pruebas que se utilizarán. Todas estas comodidades mejorarán la eficiencia de un equipo, lo que a su vez disparará su velocidad de desarrollo.

Menos malentendidos

Cuando todos trabajan desde la misma fuente de verdad (su espacio de trabajo) y pueden hacer comentarios y conversar dentro de la herramienta que están utilizando para el desarrollo, esto conducirá a menos malentendidos. Su equipo no perderá tiempo en confusión sobre si se suponía que ese punto final debía aceptar parámetros de consulta o parámetros de ruta. Todo quedará claro.

Conclusión clave

No sabía que Postman era para equipos y empresas. Ahora que lo sé, esta es mi gran conclusión: los jugadores del equipo utilizan herramientas que son buenas para el equipo.

Postman ha sido excelente para mí cuando soy desarrollador de API en solitario. Afortunadamente, también tiene características que lo harían excelente para mí cuando esté en un equipo de desarrollo de API. Para mí, eso es sincronización en tiempo real de ediciones dentro de colecciones, registros de cambios y control de versiones, y permisos granulares de acceso. Ahora estoy emocionado de asumir proyectos de API más grandes con equipos más grandes.

¡Feliz codificación!

También publicado aquí .