5. Sending data with POST

Task: Add a book

A new bestseller book arrived! As a librarian, you wish to add it to the library. In this lesson, we will learn how to add a book via POST request with a JSON Body to submit book data to our Postman Library API database. The endpoint for adding a book is documented here.

But what is the Body?

You will need to send body data with requests whenever you need to add or update structured data. For example, if you are sending a request to add a new customer to a database, you might include the customer details in JSON data format. Typically, you will use body data with PUT, POST, and PATCH requests.

The Body tab in Postman enables you to specify the data you need to send with a request. You can send different types of body data to suit your API. You can use raw body data to send anything you enter as text. Use the raw tab, and the type dropdown list to indicate the format of your data (Text, JavaScript, JSON, HTML, or XML), and Postman will enable syntax-highlighting and appending the relevant headers to your request.

Make a POST request

1. Hover over your Postman Library API v2 Collection, click the three dots and select Add request. Name your new request “add book”.
2. Set the request method to POST and the request URL to /books.

3. This endpoint request adding a body to our request to send a payload. Our payload will be a JSON object containing the info about the book we are adding. Click the Body tab of the request and select the data type raw > JSON:

   

4. Think of a book you have read recently. Inside the Body Editor, add a JSON object wit details about the new book’s title, author, genre, and yearPublished. You can copy this object and replace the values with details about your book:

    {
     "title": "To Kill a Mockingbird",
     "author": "Harper Lee",
     "genre": "fiction",
     "yearPublished": 1960
    }
   

   

5. Save and Send your request:

   

   The response from the server came back with a status 401 Unauthorized. Remeber that 400-level erros are client erros, meaning we made a mistake in our request. The body of the response has a message explaining we need to add an api-key to the headers of the request.

Task: Add an authorization header

Some APIs require [Autorization][https://academy.postman.com/postman-api-fundamentals-student-expert-certification-1/940] for certain endpoints in order to permit a request.

Authorization

Think about why you might not want an API to have completely open endpoints that anyone can access publicly. It would allow unauthorized people to access data they shouldn’t see, or allow bots to flood an API with thousands or calls per second and shut it down. There are mutliple methods for authorizing a request. Some examples are Basic Auth (username and password), OAuth (delegated authorization), and API Keys (secret strings registerd to a developer from an API portal).

Getting an API Key

APIs that use API Key auth usually allow developer to sign up in a developer portal, where they will receive a random API Key that can be used to authorize their requests to the API. The API Key allows the API to track who is making calls and how often. The Post Library API v2 uses very light protection and does not require you to register for an API Key. You simply have to know it:

Header name	api-key
Header value	postmanrulz

As the documentation shows, the Postman Library API v2 requires adding this header to any requests for adding, updating and deleting books, since these operations change data in the database instead of simply reading them.

Headers

Headers are how we can add metadata about our requests, such as authorization info or specify the data type we want to receive in a response. This is different than the actual payload data we send in the request body, such as our new book info. You can think of headers like the outside of an envelope when you send a letter. The envelope has info about delivering the letter, like proof that you have paid for postage. The actual data “payload” is the letter inside it.

Add the API Key to the request header

1. On your add a book request, click the Headers tab:

   

2. Save and Send your request. Your book was added! Now that your request is properly authorized in the header, you should get a 201 Created response with a response body that is an object representing your newly added book. You new book has been assigned a random, unique id, and has extra info now, such as it’s checkedOut status and when it was added to the library (createdAt).

View your book

You can now return to your get books by id request, and in the path parameter id replace it with the value of the id your received in the body of the book you added:

Task: Use Postman Auth instead!

Postman has an Auth helper that makes authorizing requests even easier.

Delete the api-key header

Before we use the Postman Auth helper, let’s remove the hard-coded header we just added on the add a book request. Hover over the api-key header in the Headers tab, click the bin icon at the right to delete the header, and Save your request:

Add Auth to the Collection

The Postman Auth helper can help you add authorization at the request, folder or collection level. Let’s add the api-key to our entire collection so that all requests will send the key.

1. Click on your Postman Library API v2 Collection and select the Authorization tab.
2. Select API Keys as the auth Type.
3. Enter the API Key details in the fields below. Key: api-key, Value: postmanrulz, and Add to: Header.
4. Save the changes to your Collection by clickling the floppy disk icon in the upper right.

All requests inside this Collection that use the auth method Inherit from parent will have this header attached, and therefore be authorized.

Add a new book

1. Go back to your add a book request and add another book by changing the body in the Body tab.
2. Ensure the Auth method in the Authorization tab of your request is set to Inherit from parent to use the API Key we set at the Collection level. This is the default behavior for requests.

3. Save and Send the request.

   

4. Open up the Postman Console in the lower left, and you will see the API Key has been added as a header api-key: postmanrulz, which is why we were authorized to add a book: