¿Qué aprenderá?

En este tutorial aprenderá a construir una documentación del diseño de un API usando Postman.

¿Qué construirá?

La documentación del diseño de un API.

¿Qué necesita?

En particular Ud. debe:

  1. Un equipo con la herramienta Postman instalada.

En Postman una colección es un conjunto de peticiones (u operaciones) que se realizan al API. Como decisión de diseño tendremos una colección por cada uno de los recursos del API. Para este tutorial tomaremos como referencia el recurso Author.

Diríjase a la sección Collections que se encuentra en el menú de la izquierda. Allí debe dar clic en el símbolo + o en el botón New.

Allí se redirigirá a una pestaña la cual le permitirá elegir un nombre para la colección. Para este caso dejamos como nombre Author.

Crear un autor

A continuación documentamos las operaciones del API. Iniciamos con la operación para agregar un autor a la colección de autores.

Seleccione la colección a la izquierda de la pantalla y haga clic derecho sobre el nombre de la colección y seleccione add request. La llamaremos "Crear un autor"

En los menu dropdown seleccionamos el tipo POST. En la URL dejamos el valor {{baseURL}}/authors.

Después vamos a la sección Body para documentar la representación del recurso autor en formato JSON.

Dentro de la sección Body seleccionamos la opción raw y allí seleccionamos el formato JSON. Después de eso agregamos el JSON con la representación del nuevo autor. Para este caso utilizaremos el siguiente JSON:

{
    "birthDate": "1927-03-03T00:00:00-05:00",
    "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
    "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg",
    "name": "Gabriel José de la Concordia García Márquez"
}

La operación deberá verse configurada de la siguiente manera:

Al final guardamos los cambios haciendo clic en el botón Save.

Ahora documentamos el ejemplo de respuesta de esa petición. Hacemos clic en los tres puntos de la petición y seleccionamos Add example. El nombre lo dejamos igual al nombre de la petición. Luego en Body en la sección inferior colocaremos la respuesta que debe retornar el API después de crear un autor. El siguiente es un ejemplo de la respuesta esperada. Acá tenemos los mismos datos que enviamos al API junto con el id asignado por la base de datos. 

{
    "id": 1,
    "birthDate": "1927-03-03T05:00:00.000+00:00",
    "name": "Gabriel José de la Concordia García Márquez",
    "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
    "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg"
}

Definimos el Status Code para la operación de creación el cual debe ser 201 Created. Finalmente, hacemos clic en Save.

Obtener todos los autores

Agregamos un nueva operación a la colección haciendo clic derecho > Add request. El nombre será Obtener todos los autores. Es una petición de tipo GET y la URL es {{baseUrl}}/authors.

Ahora agregamos un ejemplo de la respuesta esperada. Como decisión de diseño se ha optado por usar la representación detallada del recurso que incluye sus atributos básicos junto con las asociaciones con cardinalidad muchos que en este caso son books y prizes. 

[
    {
        "id": 1,
        "birthDate": "1927-03-03",
        "name": "Gabriel José de la Concordia García Márquez",
        "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
        "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg",
        "books": [],
        "prizes": []
    }
]

Pegaremos esta opción de respuesta y seleccionaremos el tipo de respuesta como JSON. Adicionalmente, definiremos el Status Code en 200 OK. Solo quedaría guardar y ya estaría lista la petición junto con su ejemplo.

Obtener un autor

Es una petición de tipo GET, el nombre es Obtener un autor y la URL es {{baseUrl}}/authors/{{author_id_1}}. Para no dejar un valor específico de un id en la petición usamos una variable denominada {{author_id_1}}.

Ahora agregamos un ejemplo de la respuesta esperada. Como decisión de diseño también se ha definido que la respuesta sea la representación detallada del recurso.

Este es el el ejemplo de la respuesta:

{
    "id": 1,
    "birthDate": "1927-03-03",
    "name": "Gabriel José de la Concordia García Márquez",
    "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
    "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg",
    "books": [],
    "prizes": []
}

El código de estado será 200.

Obtener un autor que no existe

Esta operación se documentará para que el usuario entienda cómo el API notifica un error que se produce al generar una petición sobre un recurso que no existe.

Es una petición de tipo GET, el nombre es Obtener un autor que no existe y la URL es {{baseUrl}}/authors/0. Por convención ese id no existe en la base de datos.

Ahora agregamos un ejemplo de la respuesta esperada. 

{
    "apierror": {
        "status": "NOT_FOUND",
        "timestamp": "21-02-2023 10:01:09",
        "message": "The author with the given id was not found"
    }
}

Adicionalmente se debe colocar un Status Code 404 Not Found.

Actualizar un autor

Es una petición de tipo PUT, el nombre es Editar un autor y la URL es {{baseUrl}}/authors/{{author_id_1}}. Dentro de Body en formato JSON incluiremos la información del autor con los valores que se van a modificar:

{
    "birthDate": "1927-03-03T00:00:00-05:00",
    "description": "Fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura. Vivio gran parte de su vida en Mexico",
    "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg",
    "name": "Gabriel José de la Concordia García Márquez"
}

Como se observa el atributo que se modificó fue description.

Crearemos ahora un ejemplo de respuesta por parte del servidor. En el cuerpo de la respuesta incluimos la representación básica del autor en formato JSON con los cambios aplicados. Definimos el Status Code 200 OK.

{
    "id": 1,
    "birthDate": "1927-03-03T05:00:00.000+00:00",
    "name": "Gabriel José de la Concordia García Márquez",
    "description": "Fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura. Vivio gran parte de su vida en Mexico",
    "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg"
}

Actualizar un autor que no existe

Es una petición de tipo PUT, el nombre es Editar un autor que no existe y la URL es {{baseUrl}}/authors/0. Dentro de Body en formato JSON incluiremos la información del autor con los valores que se van a modificar:

Como respuesta de ejemplo tendremos el siguiente JSON. 

{
    "apierror": {
        "status": "NOT_FOUND",
        "timestamp": "21-02-2023 10:04:10",
        "message": "The author with the given id was not found"
    }
}

Se definirá el Status Code en el valor 404 Not Found.

Borrar un autor

Es una petición de tipo DELETE, el nombre es Borrar un autor y la URL es {{baseUrl}}/authors/{{author_id_1}}.

En la respuesta de ejemplo solo esperamos que el API retorne el código 204 No Content.

Borrar un autor que no existe

Es una petición de tipo DELETE, el nombre es Borrar un autor que no existe y la URL es {{baseUrl}}/authors/0.

Como respuesta del servidor esperamos el siguiente mensaje en formato JSON:

{
    "apierror": {
        "status": "NOT_FOUND",
        "timestamp": "21-02-2023 10:05:19",
        "message": "The author with the given id was not found"
    }
}

Adicionalmente se configura un Status Code 404 Not Found.

En la documentación del API no se deben tener en cuenta únicamente los recursos individuales sino también sus asociaciones. Para nuestro caso de estudio el recurso autor tiene una asociación con el recurso libro. Esto implica que crearemos una colección adicional para esa documentación, que la llamaremos AuthorBooks.

Las peticiones que incluiremos en esta colección son las siguientes:

Agregar un libro a un autor

Es una petición de tipo POST y la URL es:

{{baseUrl}}/authors/{{author_id}}/books/{{book_id_1}}.

Las variables author_id y book_id_1 representan los ids del autor y del libro respectivamente.

Aunque esta es una petición de tipo POST no incluye un body.

Se espera que en la respuesta el API retorne el libro al que se le agregado el autor. Esta será la documentación de la respuesta junto con el código 201 Created.

{
    "id": 1,
    "name": "Historia de los hombres lobo 2",
    "isbn": "930330149-8",
    "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
    "publishingDate": "2000-08-20",
    "description": "Jorge Fondebrider traza un mundo fantástico con mapas de la geografía real y de sus mitologías, observando a los hombres lobo que han vivido en la imaginación de Europa y América.",
    "editorial": {
        "id": 1,
        "name": "Norma"
    },
    "reviews": [],
    "authors": [
        {
            "id": 2,
            "birthDate": "1927-03-03",
            "name": "Gabriel José de la Concordia García Márquez",
            "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
            "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg"
        }
    ]
}

Agregar un libro que no existe a un autor

Es una petición de tipo POST y la URL es:

{{baseUrl}}/authors/{{author_id}}/books/0

Se espera que en la respuesta el API retorne el código 404 junto con el mensaje descriptivo del error.

{
    "apierror": {
        "status": "NOT_FOUND",
        "timestamp": "21-02-2023 10:15:29",
        "message": "The book with the given id was not found"
    }
}

Obtener un libro de un autor

Es una petición de tipo GET y la URL es:

{{baseUrl}}/authors/{{author_id}}/books/{{book_id_1}}

Se espera que en la respuesta el API retorne el libro del autor junto con el código 200 Ok.

{
    "id": 1,
    "name": "Historia de los hombres lobo 2",
    "isbn": "930330149-8",
    "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
    "publishingDate": "2000-08-20",
    "description": "Jorge Fondebrider traza un mundo fantástico con mapas de la geografía real y de sus mitologías, observando a los hombres lobo que han vivido en la imaginación de Europa y América.",
    "editorial": {
        "id": 1,
        "name": "Norma"
    },
    "reviews": [],
    "authors": [
        {
            "id": 2,
            "birthDate": "1927-03-03",
            "name": "Gabriel José de la Concordia García Márquez",
            "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
            "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg"
        }
    ]
}

Obtener un libro que no existe de un autor

Es una petición de tipo GET y la URL es:

{{baseUrl}}/authors/{{author_id}}/books/0

Se espera que en la respuesta el API retorne el código 404 con un mensaje descriptivo del error.

{
    "apierror": {
        "status": "NOT_FOUND",
        "timestamp": "21-02-2023 10:17:39",
        "message": "The book with the given id was not found"
    }
}

Obtener un libro que no está asociado a un autor

Es una petición de tipo GET y la URL es:

{{baseUrl}}/authors/{{author_id}}/books/{{book_id_2}}

Note que en este caso se asume que el libro con el id {{book_id_2}} existe en la base de datos pero no se le ha asociado a ningún autor. Por tanto se espera que en la respuesta el API retorne el código 412 con un mensaje descriptivo del error.

{
    "apierror": {
        "status": "PRECONDITION_FAILED",
        "timestamp": "21-02-2023 10:19:03",
        "message": "The book is not associated to the author"
    }
}

Obtener los libros de un autor

Es una petición de tipo GET y la URL es:

{{baseUrl}}/authors/{{author_id}}/authors

Se espera que en la respuesta el API retorne el listado de los libros del autor junto con el código 200.

[
    {
        "id": 1,
        "name": "Historia de los hombres lobo 2",
        "isbn": "930330149-8",
        "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
        "publishingDate": "2000-08-20",
        "description": "Jorge Fondebrider traza un mundo fantástico con mapas de la geografía real y de sus mitologías, observando a los hombres lobo que han vivido en la imaginación de Europa y América.",
        "editorial": {
            "id": 1,
            "name": "Norma"
        },
        "reviews": [],
        "authors": [
            {
                "id": 2,
                "birthDate": "1927-03-03",
                "name": "Gabriel José de la Concordia García Márquez",
                "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.",
                "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg"
            }
        ]
    }
]

Asociar libros a un autor

Es una petición de tipo PUT y la URL es:

{{baseUrl}}/authors/{{author_id}}/books

En el cuerpo de la petición se incluirá una lista con los nuevos libros que se agregarán al autor.

Este es el ejemplo del body. 

[
    {
        "description": "Jorge Fondebrider traza un mundo fantástico con mapas de la geografía real y de sus mitología, observando a los hombres lobo que han vivido en la imaginación de Europa y América.",
        "editorial": {
            "id": {{new_id_e}},
            "name": "Norma"
        },
        "id": {{new_id_b}},
        "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
        "isbn": "930330149-8",
        "name": "Historia de los hombres lobo 2",
        "publishingDate": "2000-08-20T00:00:00-05:00"
    },
    {
        "description": "Descripción para el libro 2",
        "editorial": {
            "id": {{new_id_e}},
            "name": "Norma"
        },
        "id": {{new_id_b2}},
        "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
        "isbn": "930330149-2",
        "name": "Historia de los programadores",
        "publishingDate": "2003-08-20T00:00:00-05:00"
    }
]

Se espera que en la respuesta el API retorne el listado de libros junto con el código 200 Ok.

[
    {
        "id": 1,
        "name": "Historia de los hombres lobo 2",
        "isbn": "930330149-8",
        "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
        "publishingDate": "2000-08-20T05:00:00.000+00:00",
        "description": "Jorge Fondebrider traza un mundo fantástico con mapas de la geografía real y de sus mitologías, observando a los hombres lobo que han vivido en la imaginación de Europa y América.",
        "editorial": {
            "id": 1,
            "name": "Norma"
        },
        "reviews": [],
        "authors": []
    },
    {
        "id": 2,
        "name": "Historia de los programadores",
        "isbn": "930330149-2",
        "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
        "publishingDate": "2003-08-20T05:00:00.000+00:00",
        "description": "Descripción para el libro 2",
        "editorial": {
            "id": 1,
            "name": "Norma"
        },
        "reviews": [],
        "authors": []
    }
]

Asociar libros que no existen a un autor

Es una petición de tipo PUT y la URL es:

{{baseUrl}}/authors/{{author_id}}/books

En el cuerpo de la petición se incluirá una lista con los nuevos libros que se agregarán al autor los cuales no deben existir.

Este es el ejemplo del body. 

[
    {
        "description": "Jorge Fondebrider traza un mundo fantastico con mapas de la geografia real y de sus mitologias, observando a los hombres lobo que han vivido en la imaginacion de Europa y America.",
        "id": 0,
        "image": "https://static.iris.net.co/arcadia/upload/images/2017/7/31/64899_1.jpg",
        "isbn": "930330149-8",
        "name": "Historia de los hombres lobo 2",
        "publishingdate": "2000-08-20T00:00:00-05:00"
    }
]

Se espera que en la respuesta el API retorne el código 404 junto con el mensaje de error.

{
    "apierror": {
        "status": "NOT_FOUND",
        "timestamp": "21-02-2023 10:25:21",
        "message": "The book with the given id was not found"
    }
}

Borrar un libro de un autor

Es una petición de tipo DELETE y la URL es:

{{baseUrl}}/authors/{{author_id}}/books{{book_id_2}}

Se espera que en la respuesta el API retorne el código 204.

Borrar un libro a un autor que no existe

Es una petición de tipo DELETE y la URL es:

{{baseUrl}}/authors/0/artworks/{{artwork_id_2}}.

Se espera que en la respuesta el API retorne el código 404 junto con el mensaje de error.

Borrar una libro que no existe de un autor

Es una petición de tipo DELETE y la URL es:

{{baseUrl}}/authors/{{author_id}}/books/0

Se espera que en la respuesta el API retorne el código 404 junto con el mensaje de error.

Por defecto todas las colecciones quedan guardadas en el workspace del usuario, no obstante podemos guardarlas en el repositorio del proyecto.

Para esto debemos exportarlas a una carpeta del proyecto. Entonces, seleccionamos la colección, le damos clic derecho > Export.

En la ventana que aparece seleccionamos la versión v2.1 y hacemos clic en el botón Export.

Allí buscamos la carpeta collections en nuestro proyecto y guardamos el archivo. Asegúrese de que el nombre del archivo no contiene ni espacios ni caracteres especiales.