Desarrollar APIs con Postman

La estrategia «Primero la API

En Polder Knowledge, a menudo aplicamos una «estrategia API First». Existe cierto debate sobre lo que significa realmente API First, pero en Polder Knowledge lo interpretamos como un proyecto suelto que contiene la lógica empresarial de una aplicación. Esta lógica empresarial puede utilizarse hablando con API REST y RPC. La ventaja de crear una API independiente es que resulta más fácil separar las distintas preocupaciones. Gracias a la existencia de esta API, podemos crear aplicaciones para web, móviles y tabletas, y construir sitios web que hablen con la misma API y, por tanto, compartan la lógica. ¿El resultado? Los desarrolladores de móviles pueden centrarse por completo en su aplicación, los desarrolladores de front-end pueden centrarse por completo en su sitio web y los desarrolladores de back-end pueden centrarse únicamente en la propia API. Trasladamos la lógica a la API, en lugar de gestionarla en las aplicaciones.

Para desarrollar APIs, nuestra principal arma es Apigility. Apigility viene con una gran cadena de herramientas que hace posible construir API estables y profesionales. La herramienta es compatible con OAuth 2.0, JSON Hypertext Application Language (HAL) y Problem Details para API HTTP, lo que hace posible que se haga mucho trabajo por nosotros. Esto nos permite centrarnos por completo en la lógica empresarial de la aplicación.

Desarrollar API aplicando la estrategia «La API primero» no significa que la API tenga que estar terminada antes de construir la aplicación móvil o el sitio web; a menudo se desarrollan simultáneamente. Esto significa que los desarrolladores de la API necesitan una forma de ejecutar y probar sus llamadas HTTP. Por suerte, existe una herramienta impresionante que es capaz de hacer eso por nosotros: Postman

Desarrollo con Postman

Postman te permite organizar tus llamadas HTTP; te permitirá configurar todas las llamadas API disponibles, para que puedas guardarlas y reutilizarlas. También es posible compartir tu colección de llamadas API con tus colegas. Te presentaré algunos consejos que han sido muy útiles para el equipo de Polder Knowledge durante el desarrollo. Estos consejos pueden parecer obvios para algunos y pueden ayudar a otros. ¡Ojalá puedan ayudarte a ti!

Organización y categorización

Una aplicación común puede contener docenas de APIs. Las API REST suelen configurarse con un servicio sobre el que puedes aplicar acciones (los verbos HTTP). Por ejemplo: para crear una nueva entidad, lo normal es que ejecutes una solicitud POST al punto final de esa entidad. Hemos aprendido que es útil organizar estos puntos finales con las colecciones que ofrece Postman. En la captura de pantalla siguiente, puedes ver que hemos creado una colección llamada Evolve. Esta colección contiene una serie de puntos finales que hemos clasificado en su propia carpeta.

Convención de nomenclatura

Anteponiendo a la llamada a la API el prefijo REST o RPC, queda claro qué tipo de llamada se realiza. Diferenciamos REST y RPC entre sí anteponiendo a la llamada el tipo. A continuación, es útil dejar claro si estás ejecutando la solicitud en la colección o en la propia entidad.

Ver modos

Todos somos humanos, así que se cometerán errores, ¿verdad? Al probar tus llamadas a la API, a menudo ocurre que esperas JSON, pero se produce un error del servidor. Cuando una aplicación no gestiona correctamente la cabecera Accept, se mostrarán errores HTML. Postman te permite cambiar entre vistas renderizadas y vistas sin procesar. Esto es extremadamente útil en los casos en los que se producen errores del servidor, ya que te permite leer los datos de forma renderizada. Postman también analizará JSON y XML, para que tus datos sean más fáciles de leer.

Autorización

Cuando tu API haga uso de la autorización, Postman te permitirá configurar la autorización para tus llamadas a la API. Obtén fácilmente tokens de acceso OAuth, utiliza la Autorización Básica o la Autorización Digest.

Compartir

Una vez que tus llamadas a la API estén bien organizadas, podrás compartirlas. Puedes compartir la API a través de la nube Postman o puedes exportar fácilmente la API a un JSON. Estos archivos JSON se pueden enviar a un repositorio o puedes compartirlos con tus compañeros de equipo.

Variables y entornos

Imagina que tienes un servidor web local al que puedes acceder a través del dominio webserver01.host. Tu colega también tiene un servidor web local al que se puede acceder a través de miproyecto.host. Una vez configuradas tus llamadas a la API, introduces la URL de tu propio servidor web. Ahora exportas tu API a un archivo JSON y tu colega lo importa de nuevo. Tu colega verá todas tus URL locales, lo que, como puedes imaginar, no es lo ideal. Esto puede solucionarse simplemente utilizando variables. Las variables se pueden utilizar en cada campo que se pueda rellenar dentro de Postman.

Postman hace uso de entornos, que te ayudan a cambiar el conjunto de variables por proyecto en el que trabajas.

Una vez creado tu entorno y añadidas las variables, puedes utilizarlas donde quieras. ¡Postman incluso te ofrece autocompletado!

Prueba

Ya tienes tu API estructurada y organizada, e incluso puedes compartirla con tus compañeros de equipo. Pero, ¿qué fantástico sería si pudieras asegurarte de que la respuesta de la API es válida? ¡Pues Postman te ofrece esta posibilidad!

Asegúrate de echar un vistazo a Newman también, ya que ofrece la posibilidad de ejecutar tus pruebas Postman en la línea de comandos. Esto significa que puedes engancharlo en tu cadena de construcción de Integración Continua.

En resumen…

Postman ofrece un gran conjunto de herramientas para optimizar tu flujo de desarrollo. Organizar, colaborar y probar todo es posible con Postman. Espero que estos consejos te hayan ayudado a optimizar tu flujo de desarrollo. Asegúrate de ponerte en contacto con nosotros a través de Twitter (@Polder Knowledge) si tienes algún otro consejo.