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.

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:

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.

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:

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.

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.