20.5. Studio: Consuming the CodingEvents API With Postman

The UI of a browser is designed to make simple GET requests for URLs entered into its address bar. This design works great for browsing sites, but falls short when working with APIs. Anything beyond a GET request is difficult to send via a browser address bar alone. Think about what is needed to create a new CodingEvent. This type of request contains a body. Our MVC application included a view to allow us to test inputs. Our API, however, is headless. It does not contain the client-side form. In order to test how it handles requests then, we need a way to interact with the API server without the browser. In this studio, we work with Postman to explore how APIs can be consumed.

20.5.1. Setup

20.5.1.1. Install Postman

If you haven’t done so already, install Postman.

20.5.1.2. Fork and Clone the API Source Code

With Postman installed, we’re ready to fork and clone the CodingEvents API. Although it is implemented differently from CodingEvents MVC, you will find that most of the features from the MVC application have been supported through endpoints in the API.

Note

Our focus in this course is on operations and as such we will not be going into the development of the API. However, feel free to explore the source code if you are curious about the similarities and differences between the .NET MVC and API implementations.

Let’s begin by forking and cloning the repo onto our machine. In your Powershell or terminal window, move into a directory where you plan to save your local copy of the API codebase.

> git clone https://github.com/<GitUsername>/coding-events-api

For this studio, we want to have the 1-sqlite branch checked out. This branch has an API with a single (CodingEvent) resource and a built-in SQLite database.

Note

Including a SQLite database in this project means you don’t need to have your MySQL server running to test the API. We won’t get into what this looks like and instead just concentrate on testing the API endpoints.

Let’s change into the repo and switch to this branch:

# cd is an alias (like a nick-name) for the Set-Location cmdlet in PowerShell
> cd coding-events-api

# check out the 1-sqlite branch
> git checkout 1-sqlite

You can leave this PowerShell window open, we will return to it in a later step:

A PowerShell window after cloning the coding-events-api repo

20.5.1.3. Start the API Server

We’ll start the API server from the terminal using the dotnet run command. Navigate to the CodingEventsAPI project folder within your coding-events-api solution. This is the folder that contains Controllers/ and so on, and is NOT the main project folder.

# change to the CodingEventsAPI project directory
> cd CodingEventsAPI

# run the project
> dotnet run

info: Microsoft.Hosting.Lifetime[0]
   Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Users\<username>\coding-events-api\CodingEventsAPI

If you see something like this output above, then your API is running! You’ll note, we’re not using Visual Studio here to run the application but feel free to open the solution in VS and explore the source code.

20.5.1.4. Swagger Documentation

With the application running, go to the first location listed as: “Now listening on:”. Enter https://localhost:5001 into your browser. You’ll see a page that looks nothing like any view we created in our CodingEvents MVC applications. This view is indeed not an equivalent. What you see running in the browser is not at all a client-side application, but rather, some documentation resources for the API itself.

You’ll see a list of those endpoints we asked you to describe for this lesson’s exercises:

Two endpoints at the CodingEvents entry-point path, /api/events, to interact with the collection as a whole:

• list CodingEvents: GET /api/events -> CodingEvent[]
• create a CodingEvent: POST /api/events (NewCodingEvent) -> 201, CodingEvent

And two that require a sub-path variable, /events/{codingEventId}, to interact with a single entity:

• delete a CodingEvent: DELETE /api/events/{codingEventId} -> 201, CodingEvent
• find single CodingEvent: GET /api/events/{codingEventId} -> CodingEvent

And below this list are two Schemas, or shapes, of resources the API handles.

Swagger is a popular tool API developers use to include fast documentation for their API codebase. The page we’re looking at is generated by this tool and gives us a nice summary of the endpoints made available by the CodingEvents API we currently have running. But remember, we’ll test the API in Postman.

20.5.2. Making Requests to the Coding Events API

20.5.2.1. List the Coding Events

To create our first request using Postman, select the New button in the top left corner of the Postman window:

Select the New button to create a new request

20.5.2.1.1. Creating a New Request

With the new item dialog open, select the Create New tab (on the left) then select Request.

Create a new request item in Postman

This will open the new request dialog:

The new request dialog includes fields for a request name, description, and collection

Postman requests require a name and a collection. A collection is just a container to hold related requests. They make it easy to import and export collections of requests for portability across teams. For our first request, enter “list coding events” in the Request name form field. At the bottom of the new request dialog, you will see that the collections are empty. Select the orange Create Collection button, then enter the name coding events API. The new request dialog button will change to say Save to coding events API:

Once the collection is selected, save the new request

After saving, a new request tab will be created where you can customize its behavior:

A new request has been created in Postman

20.5.2.1.2. Configuring the Request

Postman exposes an exhaustive set of tools for configuring every aspect of a request. Fortunately, this request is relatively simple.

We want to request the state of the CodingEvents collection, in shorthand:

GET /api/events -> CodingEvent[]

In Postman, we can make this request by configuring the following settings:

• the URL of the endpoint: http://localhost:5000/api/events
• the HTTP method of the endpoint: GET
• the request header: (Accept: application/json)

Note

Though we view the Swagger docs from port 5001, we request the resources on port 5000.

To the left of the URL bar is a dropdown selector for HTTP methods. It will default to GET. In the following requests, you will need to select the appropriate method from this list.

The dropdown menu contains all of the HTTP request types available to send

Next to the request method type, enter the request URL where the API request should be sent: http://localhost:5000/api/events.

Underneath the URL bar are tabs for other aspects of the request. Select the Headers tab to configure our header. The Accept header lets the API know that we accept responses that are formatted as JSON.

Note

In our context, the API only responds with JSON. However, some APIs offer multiple MIME types for their responses. It is a best practice to set this header explicitly to the content type the consuming application expects.

You can set multiple headers in this section. As you begin to type the name and value of headers, Postman will autocomplete them for you. After configuration, your request should look like this:

The request Accept header is given a value of “application/json”

To issue the request, you can select the blue Send button on the right of the window, or use the ctrl + enter keyboard shortcut.

20.5.2.1.3. Viewing the Response

Below the request configuration, you will see the response section has been populated. From here, you see the response body along with the status code (on the right) and a tab for headers:

The initial CodingEvents collection state is empty

Since this is our first time running the application, the database is empty. We expectedly received an empty JSON list [] which corresponds to the empty representation of the Coding Events collection.

If you select the Headers tab in the response pane, you see the API satisfied our Accept request header and provided the response in application/json format.

The response is returned as application/json

Note

If you get a connection refused error, it means you likely forgot to start the API server or mistyped the URL. Check both of these before attempting the request again.

If sending the request results in a connection error, check your setup and request settings

20.5.2.2. Create a CodingEvent

For our next request, we will create a CodingEvent. Repeat the steps you performed in the previous request:

1. Click on the orange New button in the top left corner of the Postman window to create a new request named: create coding event
2. Add it to the existing coding events API collection

This request will change the state of the Coding Events collection by adding a new entity to it. Recall that the shorthand for this request is:

POST /api/events (NewCodingEvent) -> 201, CodingEvent

We will need to set the following request settings:

1. The URL of the endpoint: http://localhost:5000/api/events
2. The HTTP method of the endpoint: POST
3. The request header: (Content-Type application/json)
4. The request body: a JSON NewCodingEvent object

As a best practice, we explicitly define the Content-Type header. This header indicates that our request contains application/json data so that the API knows how to parse the incoming request body.

20.5.2.2.1. Configure the Request Body

In addition to the configurations you are now familiar with setting, we will need to define the request body. For this task, select the Body tab that is next to Headers.

The body of the request must be in a raw JSON format. In the Body tab, open the the dropdown to select your data format. Select raw from the menu. Once this format is selected, enter the following JSON body:

{
   "Title": "Halloween Hackathon!",
   "Description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions",
   "Date": "2020-10-31"
}

Before sending the request, check that your configuration matches the following image:

You can write JSON directly into the request Body tab

Hit send and we’ll take a look at the result.

20.5.2.2.2. Analyzing the Response

You can see in the response that the API reflected back the representation of the new CodingEvent entity. Notice that a unique id has been assigned to it by the API. Looking at the status code (201) and headers of the response, we can see the API conformed to the REST convention. Open the Headers tab in the response panel. The URL value of the Location header is: http://localhost:5000/api/events/1. This location can be can now be used to view the individual CodingEvent entity that was created by our request.

20.5.2.2.3. Sending a Bad Request

To test the rejection of bad requests, let’s send one that violates the NewCodingEvent validation constraints. Send another request with the following JSON body:

{
   "Title": "too short",
   "Description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions",
   "Date": "2020-10-31"
}

You can see from the response that the API rejected the request. The response returns a bad request status of 400 which indicates a client-side error. The response body includes information about what needs to be corrected to issue a successful request:

The response body error message tells us we need to modify our CodingEvent title

20.5.2.3. Get a Single Coding Event

For this step, we will make a request for the state of a single entity. You can use the URL from the Location header of the previous request to complete this task. Remember to follow the steps you performed before, keeping in mind the shorthand for this request:

GET /api/events/{codingEventId} -> CodingEvent

1. Create a new request named: get a single coding event
2. Add it to the existing coding events API collection
3. Configure the URL of the endpoint: http://localhost:5000/api/events/1
4. Configure the HTTP method of the endpoint: GET
5. Configure the request header: (Accept: application/json)

You should get back the following JSON response body:

{
   "id": 1,
   "title": "Halloween Hackathon!",
   "description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions",
   "date": "2020-10-31T00:00:00"
}

20.5.2.3.1. Requesting a Non-Existent Entity

Our REST API allows us to interact with the state of its resources. If we make a request for a resource that doesn’t exist in this state, we expect a 404 (not found) response.

Try issuing the request again with a non-existent codingEventId of 100. You should get back the following response:

We got a 404 response when requesting a resource that cannot be found on the server

20.5.2.4. Delete a Coding Event

In this final step, we will issue a DELETE request. Before we make the request, let’s re-issue the request to list the collection of CodingEvents. Now that we have added an entity, we expect the state of the CodingEvents resource collection to have changed. Switch back to the list coding events request tab and re-issue the request. You should get a response of the collection’s list representation containing the single entity we have created.

[
  {
     "id": 1,
     "title": "Halloween Hackathon!",
     "description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions",
     "date": "2020-10-31T00:00:00"
  }
]

To delete this entity, and therefore change the state of our resources, we will need to issue the following shorthand request:

DELETE /api/events/{codingEventId} -> 204

Once again, go through the methodical process of setting up the request:

1. Create a new request named: delete a coding event
2. Add it to the existing coding events API collection
3. Configure the URL of the endpoint: http://localhost:5000/api/events/1
4. Configure the HTTP method of the endpoint: DELETE

Notice that for this request, we do not need to set any request headers. A DELETE request should send back an empty (no-content) response body with its 204 status code.

Deleting a CodingEvent returns no body in the response

As a final confirmation, check the state of the CodingEvents collection and notice that it has returned to its initial state. The representation of this state is shown in the empty list [] response body.

20.5.3. Bonus Missions

If you complete this studio early and want some additional practice, consider the following bonus missions:

• Explore the API source code using your IDE debugger to step through the request and response process
• Try consuming the API from the command-line using the Bash curl program or the PowerShell Invoke-RestMethod cmdlet.