Studio: Consuming the Coding Events 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.

Setup

Install Postman

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

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.

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.

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.

# navigate and change into the coding-events-api solution 
cd coding-events-api
# change to the CodingEventsAPI project directory
cd CodingEventsAPI

```bash
# 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.

Swagger Documentation

With the application running, go to the first location listed as: Now listening on: https://localhost:5001. Open https://localhost:5001 in your browser. You’ll see a page that looks nothing like any view we created in our other MVC applications. 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:

• find single CodingEvent: GET /api/events/{codingEventId} -> CodingEvent
• delete a CodingEvent: DELETE /api/events/{codingEventId} -> 201, 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.

Making Requests to the Coding Events API

List the Coding Events

To create our first request using Postman, select the Create New button located within the “Start with something new” section.

Select the Create New button to create a new request

Creating a New Request

With the Create New view open, select the HTTP Request option.

This will open the view to create a HTTP Request.

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)

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.

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.

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

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 New button in the top left corner of the Postman window to create a new request.
2. Select the HTTP Request option.

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

Your request should look like the following image:

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.

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, you will need to select the data format. Select raw from the available options. Once this format is selected, enter the following JSON body:

1
2
3
4
5

{
   "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.

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. (in my case the id was 2) This location can be can now be used to view the individual CodingEvent entity that was created by our request.

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:

1
2
3
4
5

{
   "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:

.. figure:: figures/create-coding-event-bad-request.png :alt: Postman response returned from CodingEvent creation request containing an invalid request body

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

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:

1
2
3
4
5
6

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

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

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 GET request tab and re-issue the request for the endpoint http://localhost:5000/api/events. You should get a response of the collection’s list representation containing the single entity we have created.

1
2
3
4
5
6
7
8

[
    {
        "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 HTTP request
2. Configure the URL of the endpoint: http://localhost:5000/api/events/1
3. 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 by submitting a GET request to http://localhost:5000/api/events and notice that it has returned to its initial state. The representation of this state is shown in the empty list [] response body.

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.