3. Your First API Request

Task: Create a workspace

The Postman Library API v2 is a REST API that allows you to CRUD (Create, Read, Update, Delete) books in a public library database. You will use Postman to interact with this API and manage books.

To start making Postman requests, you need to be inside a workspace:

1. Workspaces dropdown > Create Workspace:

   

2. Select Blank Workspace as Template:

   

3. Name your workspace “Postman API Fundamentals Student Expert” and set the visibility to Public. Then click Create:

   

4. Welcome to your empty new workspace!

   

Task: Create a collection

Collections are places to organize your API requests in Postman. Let’s make a new Collection in our workspace where our requests to the Postman Library API v2 will live.

1. From the left pane, either click the plus (+) icon or Create a collection:

   

2. Name your collection “Postman Library API v2”:

   

Next up, we will make our first API request.

Task: Get books from the Library API

First things first: a librarian must know how to view all the books in the library catalog. According to the API documentation, you can get all the books in the library by making a request to GET https://library-api.postmanlabs.com/books. Here, GET is the request method, and the URL is the request URL.

Make your first request

1. Create a new request by either clicking Add a request inside your new Collection or hovering on your Collection, then click the three dots icon and Add request:

   

2. Name your request “get books”. Set the request method to GET, and the request URL to GET https://library-api.postmanlabs.com/books. Be sure to hit **Save your work using CTRL + S:

   

3. Send your request by clicking the Send button:

   

View the response

If everything goes well, you will see a response from the server in the lower half of Postman. It should look like this: a JSON (JavaScript Object Notation) response body with an array of book objects. You can scroll down to see more books:

Request methods

When we make an HTTP call to a server, we specify a request method that indicates the type of operation we are about to perform, aka HTTP verbs. Some common HTTP request methods correspond to the CRUD operations mentioned earlier. You can see a list of more methods here.

Method name	Operation
GET	Retrieve data (Read)
POST	Send data (Create)
PUT/PATCH	Update data (Update)
DELETE	Delete data (Delete)

PUT usually replaces an entire resource, whereas PATCH usually is for partial updates.

Since we are “getting” books and not modifying any data, it makes sense that we are making a GET request. There are just conventions - it all depends on how the API is coded. To know which method to use, always read the API documentation you are working with, such as Postman Library API v2 docs!

Request URL

In addition to a request method, a request must include a request URL that indicates where to make the API call. A request URL has three parts:

1. A protocol (such as http:// or https://)
2. A host (server location)
3. A path (route on the server)

In REST APIs, the path often points to a reference entity, like “books”.

Protocol	Host	Path
https://	library-api.postmanlabs.com	/books

Paths and complete URLs are also sometimes called API endpoints.

Reponse status codes

The Postman Library API v2 has returned a response status code of 200 OK. Status codes are indicators of whether a request failed or succeeded. Status codes have conventions. For instance, any status code starting with 2xx (“a 200-level response”) represents a successful call. Some other categories are:

In Postman, you can hover over any response to see what it means:

Request-Reponse pattern

Now you can understand the request-response pattern, which represents how computers communicate over a network. An API is the interface that lets us know what kind of response to expect when we make certain calls to a server. You made an HTTP GET request to https://library-api.postmanlabs.com/books and received a response from the server:

The client is the agent making a request. A client could be a browser or an app you have coded. In our case Postman is the client because that is how we sent the request. The request is sent over a network to some server. In our case, we made a request over the public internet to a server located at the address https://library-api.postmanlabs.com. The server interpreted the request (GET /books) and sent the appropriate response over the network back to the Postman client: a list of books.