Documentación de API Rest con Postman
Tags: database, deno
Published: 2020-06-04 00:39:46

En este post, vamos a ver como documentar con Postman nuestra API Rest desarrollada en el post anterior con Deno, de esta forma obtendremos nuestra documentación, para luego integrar nuesta API con un front que vamos a crear con React. Les dejo el enlace en donde creamos nuestra API Rest: [Iniciando con Deno - API Rest](https://dev.to/juangaj07538514/deno-api-rest-4m82)

Es necesario descargar [Postman](https://www.postman.com/downloads/) y ingresar a la aplicación, podemos crear un usuario o ingresar con cuenta de google o redes sociales.

## Iniciar API Rest

Lo primero que vamos hacer es iniciar nuestra API Rest creada en el post anterior, para ello, es necesario dirigirse a la ruta de nuestro proyecto y darle al comando `drun` para iniciar nuestra aplicación:

![start drun](https://i.ibb.co/kQPWQ7F/drun.png "Iniciar API")

Esto nos debería entregar por consola el siguiente mensaje:

![start drun ok](https://i.ibb.co/mbVBv4V/drun-ok.png "API Ok")

Y listo, ya podemos empezar a trabajar con Postman en nuestra documentación.

## Nuevo workspace

Comenzaremos creando nuestro workspace, es necesario hacer click en "All workspaces" como aparece en la imagen:

![nuevo workspace](https://i.ibb.co/7pX258B/add-workspace.png "Nuevo workspace")

Luego nos vamos al enlace que nos abre postman, y le damos click en "create new workspace":


![create new workspace](https://i.ibb.co/v1NySHZ/create-new-workspace.png "Crear nuevo workspace")

## Nuevo environment (entorno)

Ahora crearemos un environment, para ello es necesario ir al botón con un engranaje en el extremo superior izquierdo de nuestra pantalla:

![nuevo environment](https://i.ibb.co/1Mmtsh3/enviroment-options.png "Nuevo environment")

Luego procedemos a hacer click en "Manage Environments", le damos un nombre a nuestro nuevo "Environment", en mi caso y como aparece en la imagen, le di el nombre "Development" le damos add o agregar:

![add environment](https://i.ibb.co/3hNXgPn/manage-environments.png "Nuevo environment")

Listo, ya hemos creado nuestro environment. Ahora configuraremos nuestras variables, para ello vamos a "Manage Environments" que fuimos anteriormente, y seleccionamos nuestro entorno:


![select environment](https://i.ibb.co/nj6DjTN/select-environment.png "Seleccionar entorno")

Agregamos nuestra url de desarrollo y le damos update:


![save variables](https://i.ibb.co/TY0FXyX/save-variables.png "Guardar variables")

Y listo, nuestro entorno ha sido configurado.

## Nueva colección

En esta sección vamos a crear una nueva colección, para esto tenemos que presionar el botón "New collection" como lo indica la imagen adjunta, debemos colocar un nombre y una descripción, luego le damos a "create".

![nueva colección](https://i.ibb.co/DzVGnVW/Screenshot-3.png "Nueva colección")

## Nuestro primer servicio

Para crear nuestro primer servicio, es necesario crear una carpeta dentro de nuestra colección que generamos en la sección anterior: 

![nueva carpeta](https://i.ibb.co/12TsTn6/add-folder.png "Nueva carpeta")

Ahora le damos el nombre de "Cars" y una descripción:

![crear nueva carpeta](https://i.ibb.co/dGCYVQw/create-new-folder.png "Crear nueva carpeta")

En este momento crearemos nuestra petición para traer todos los automóviles (getCars):

![nuevo request](https://i.ibb.co/Zmj9WhS/add-request.png "Nuevo request")

![crear request](https://i.ibb.co/V2PLVQk/create-request.png "Crear request")

De esta forma ya tenemos listo nuestro primer request, ahora lo que debemos hacer es seleccionar el entorno que creamos en nuestra sección "Nuevo entorno", esto en la parte superior derecha donde dice "No enviroment" y seleccionamos "Development":

![select enviroment 2](https://i.ibb.co/zsypwRP/select-environment-2.png "Seleccionar development")

De esta forma tenemos a disposición nuestra variable de entorno (url dev), ahora elaboramos nuestro "endpoint":

![url cars](https://i.ibb.co/fSLGsFj/url-cars.png "Endpoint /cars")

Procedemos a guardar nuestra petición con el botón "Save":

![save request](https://i.ibb.co/LdwvSpZ/save.png "Guardar petición")

Esta petición, nos entrega una respuesta 401, ya que no estamos mandando la cabecera "Authorization" ya que este método solicita token de autenticación, ahora guardaremos nuestra respuesta como ejemplo:

![save response](https://i.ibb.co/52w3LxT/save-response.png "Guardar respuesta")

![save response with example](https://i.ibb.co/8zRgjMV/save-response-2.png "Guardar respuesta como ejemplo")

En la ultima imagen, guardamos este ejemplo como error 401, ahora lo que debemos hacer, es configurar nuestra petición para que pueda entregar una respuesta `200` exitosa.

Para esto vamos a consultar a nuestro método `/users/login` para obtener el token y agregarla a nuestra cabecera:

![get token](https://i.ibb.co/gP0MXmp/get-token.png "Traer token")

Luego procedemos a agregarlo a nuestra cabecera:

![ok request](https://i.ibb.co/pJVcB7V/200-get-Cars.png "Traer todos los automóviles")

De esta forma obtenemos una respuesta 200 con todos los vehículos. Guardamos nuestra respuesta exitosa:

![save response 200](https://i.ibb.co/Ln9944t/save-response-200.png "Guardar respuesta 200")

![save response 200 example](https://i.ibb.co/ww51tqd/save-response-example-2.png "Guardar respuesta 200 como ejemplo")

De esta forma, logramos guardar nuestra respuesta como error y también nuestra respuesta exitosa.

## Primer vistazo a nuestra documentación con Postman

Vamos a revisar como esta quedando nuestra documentación, para esto, tenemos que ir a "view in web" y dar click:

![view in web](https://i.ibb.co/0Zm9DBd/view-web.png "Ver en la web")

Esto nos enviara a una pagina de Postman para poder ver la documentación que estamos creando, acá debemos seleccionar primero el entorno, en nuestro caso "Development" y esto nos mostrara las variables que creamos, en nuestro caso la url, en el costado inferior derecho, podemos ver la respuesta 401 que guardamos:

![view in web development](https://i.ibb.co/7Y4QLw3/web-development.png "Ver en la web development")

Si seleccionamos la otra respuesta que guardamos veremos como cambia el ejemplo:

![view in web development success ](https://i.ibb.co/kqNScNm/success-example.png"Ver en la web - Success")

Acá vemos nuestra respuesta exitosa y el ejemplo de como debe mandarse para consultar los datos a la API Rest.

## Conclusión

De esta forma podemos realizar una documentación de nuestra API Rest con Postman, como ejercicio les dejo los siguientes métodos para que los puedan realizar ustedes mismos y ver la tremenda herramienta que es Postman.

Mencionar que lo trabajado en este post, lo utilizaremos en un tercer post, donde vamos a construir un cliente front con React (Hooks) para poder logearnos y poder realizar las operaciones CRUD con una interface de usuario.

Saludos y hasta luego.