Web Reactiva

WR 81: Diseñando una API con Swagger

Crearemos en el episodio de hoy la definición de los primeros endpoints de una API utilizando el editor online Swagger.

Escúchalo también en Spotify | Apple Podcasts | Google Podcasts | iVoox

Crearemos en el episodio de hoy la definición de los primeros endpoints de una API utilizando el editor online Swagger.

Esta semana también estrenamos un nuevo podcast en la Zona Premium. Será “Marketing online para programadores”. Todo un atrevimiento, pero, ya es hora de aprender a sacar partido de todo lo que sabemos, ¿verdad?

Atención porque Juanan Ruiz nos hace una propuesta muy generosa. Está buscando un alumno/a para enseñarle a programar plugins y themes de WordPress de forma gratuita. Está montando unos cursos muy interesantes y aprovecha mi humilde podcast para encontrar un aprendiz para su mentoría.

Apúntate a través de este formulario de Kung Fu Press.

La definición de una API

Como sabéis comienzo ya con el reto #100DaysOfCode y estoy preparando las herramientas necesarias. Algo que no es exactamente programación per es muy necesario es tener orden.

Otra cosa relevante es tener una fuente de datos lo más realista posible. Existen muchas APIs en internet donde puedes encontrar información valiosa, pero con el “Lorem ipsum” o los “Chistes de CHuck Norris” no termino de apañarme.

Así que voy a aprovechar el trabajo de Miguel Santa Olalla en la web de filosofía boulesis.com para tener datos de filósofos reales. Creo de esta manera una funcionalidad que quizás traiga nueva vida a este portal de referencia.

Tenemos unos datos sobre filósofos en un formato como este:

Creando una APi con datos de filósofos

Y los vamos a exponer al mundo con una API.

Creando el contrato en Swagger

Swagger tiene un editor en abierto, pero yo recomiendo utilizar su Hub, ya que permite tener un mejor control de todas las características.

Basaremos la definición en las reglas que marca la iniciativa OpenAPI, impulsada por SmartBear entre otros. Así podremos especificar los endpoints, los métodos HTTP asociados y hasta incluso los parámetros de seguridad.

Creamos la API con algunas descripciones básicas.

Cuadro de creación de la API swagger

No usamos la versión 3.0 de la especificación únicamente porque tiene más limitada la generación de código de ejemplo. Pero es muy fácil migrar desde la versión 2 a la 3 con el propio editor.

Además podremos importar en Postman la definición para trabajar con ella.

Incluso nos va a generar un Mock para poder testear la API llamando a unas rutas de URL autogeneradas por Swagger.

Los endpoints

La definición de cada endpoint se comenta en detalle en el podcast. Hay que tener en consideración que lo basamos todo en el modelo de “Author”, que es la clave de los datos.

De esta forma vamos a crear endpoints para recuperar los datos que tenemos sobre cada autor, pero también dotaremos de vida al sistema permitiendo, con los permisos pertinentes, escribir datos en nuestra base de datos utilizando la API como puerta de acceso.

Así emplearemos los métodos PUT, POST y DELETE para interactuar y crear un CRUD. Aquí vemos lo que tenemos ejecutado en el ejemplo:

Métodos de mi API

Resultado final

Puedes consultar la definición completa de la “Philosophers API” en este enlace autodocumentado.

También se permite exportar el boilerplate en el lenguaje de programación que más te interese. En mi caso lo exportaré a Lumen para tener los controladores necesarios ya generados y, a partir de ahí, arrancar con la programación de todo lo que se me ocurra.

Exportar el código de la API

Puedes seguir a Web Reactiva en el canal de telegram t.me/webreactiva o en la cuenta de twitter @webreactiva con referencias, recursos y enlaces de interés.

12 recursos para developers cada domingo en tu bandeja de entrada

Además de una skill práctica bien explicada, trucos para mejorar tu futuro profesional y una pizquita de humor útil para el resto de la semana. Gratis.