API testing and development are quickly becoming crucial skills for modern web developers and professionals working in the tech industry. We designed our workshop to be an approachable introduction to RESTful API development and testing using Postman, the industry-standard SaaS company for rapid API development and testing.

What are APIs?

An API, or Application Programming Interface, is a software intermediary that allows two applications to interact with each other. In other words, an API delivers your request to your desired provider and retrieves its response back to you.

Developers working with APIs no longer need to build complex features like chat applications from scratch, saving valuable time and labor. In addition, APIs allow quick and secure access to vast amounts of varied data from sources like financial markets and weather services.

RESTful APIs allow programs to communicate with each other using HTTP (Hypertext Transfer Protocol) Requests.

There are four basic HTTP methods used to communicate with a RESTful API:

  • GET is used to retrieve data.
  • POST assigns values to an empty object.
  • PUT reassigns or changes values to existing data.
  • DELETE gets rid of existing data.

Endpoints are the receiving end of all API requests. They take a request and data and return a response. Using McDonald's as an analogy, a customer’s order would be calling an API endpoint, and the food returned would be the status code and data returned.

BitBlox

Nothing gets us going like a bit of art and good competition. For our BitBlox activity, we start with a 20 x 20 grid of blank white squares. The goal of the game is to fill adjacent squares with your team color by calling API endpoints. Each square has a unique ID from 1–400 and can be filled in with orange, yellow, green, or blue.

In this game, you use the REST API to change the box color.

  • POST requests can add color to a white box, but cannot add color to a box that already has color. It doesn’t make sense to add new data to something that already has data with a POST request; this is what a PUT request is used for.
  • PUT requests can only change the color of colored boxes and cannot change the color of white boxes. It doesn’t make sense to edit something that doesn’t have data in the first place.
  • DELETE requests can only be used to remove the color from a box only if the selected box is colored. You can’t use a DELETE request on a white square since it does not contain any data.

You can see the live version of the board here: https://bitbloxs.herokuapp.com/

The Pain of cURL

In order to access the features of an API, one can use the cURL command. cURL, which stands for “client URL” and can be written as “curl,” is a command-line tool for file transferring with URL syntax. It supports a number of protocols such as HTTP, HTTPS, FTP, and many more.

In order to retrieve data on all boxes in the 20 x 20 grid with a GET request, type the following into the terminal/command prompt.

curl — location — request GET “https://bitbloxs.herokuapp.com/boxes?api_key=thisistheapikey"

We use a GET request when we want to query a collection of data or a specific piece of data.

GET requests return a data object (usually in JSON) and a 200 status code.

The problem is that the return is not formatted and visually unappealing.

POST Requests

POST requests are used to send data to the server. This data creates a new object.

  • You are “posting” data to the API.
  • POST requests generally don’t return data, just a 200 status code.
curl --location --request POST "https://bitbloxs.herokuapp.com/change/23/yellow?api_key=thisistheapikey"

PUT Requests

A PUT request is used to change existing data, in contrast to POST, which creates new data.

curl --location --request POST "https://bitbloxs.herokuapp.com/change/23/yellow?api_key=thisistheapikey"

You may be thinking that this seems really messy. I agree! This is why we have Postman!

What is Postman?

Postman is a collaboration platform for API development and makes testing APIs extremely simple. All the headings with the 👨‍🚀 before it are Postman Features we at Bit Project find very useful!

👨‍🚀 Environments

Environments are used to easily switch between development and production servers. Environments are useful because they let you customize requests using variables, allowing you to switch between different setups without changing your requests. In simple terms, it will save you a lot of time and clicking around like a madman.

At the top-right of the Postman app, there is a gear that you can click.

After clicking the gear, you will be led to a page that looks like the following:

When you are on this page, click the orange Add button.

Name your environment anything you want. Honestly, it doesn’t matter. I like to name mine after my favorite foods like env_avocado 🥑.

Afterwards, we are going to create a variable called url and fill the initial value and current value with https://bitbloxs.herokuapp.com. After creating the url variable, create another variable called api_key and fill in the initial value and current value with thisistheapikey.

After creating the environment, click the No Environment button at the top-right and select your newly created environment.

In my case, it is called UCD Postman Workshop. Yes, I know, super creative.

Now, we are going to create a GET request to retrieve the color of the selected box ID. Boxes on the grid have a unique ID from 1–400.

To create a request, click the three dots in the Postman collection. After that, click on Add Request. This should lead you to the following page:

On this screen,

  • name the request GetOneBox.
  • in the description box, write something that best describes the role of this request. In our case, it is to get the color for one box.

👨‍🚀 Authentication

Every API uses authentication, which only admits verified users. The API that we created for the workshop needs authentication in order to use it. In order to interact with the API, we need an API key, which is a unique identifier used to authenticate a user, developer, or calling program to an API.

In the GetOneBox request, click the Authentication tab.

  • In the Type dropdown, select API Key.
  • In the Key field, name it api_key.
  • In the Value field, type thisistheapikey.
  • In the Add to field, select Query Params.

👨‍🚀 Creating Your First Request

In the input field, type the following: {{url}}boxes/22. You can replace 22 with any number from 1–400. You might be wondering what {{url}} is. Remember when we made a url variable in our environment? We can use that variable anywhere as long as we put double curly brackets around the variables that we create in our environment. This is much better than typing https://bitbloxs.herokuapp.com for every route.

👨‍🚀 Documentation

After creating your own collection, environment, and request, you must worry about documentation or else everyone will get upset. Thankfully, Postman automatically generates documentation on your collection. This makes it quick and easy for developers to understand all of the features of an API. In order for our workshop attendees to play our game, we had them find our collection in the Postman templates tab.

After finding the template, click on it. You should be directed to the page shown below.

Now, click View Documentation. That should lead you to the following page:

You can now look at the documentation of the game’s API and what each endpoint does. Afterwards, click the Run in Postman button at the top-right.

Now, in the Postman app, you should see a collection called Color Changer appear on the right-hand side of the screen.

After importing the collection, we let the students experiment with it by having them test the Get All Boxes request, which returns the color of every box. We then showed them how to make the POST request work for our collection. They would first double-click the POST request.

In the link, replace <string:color> to blue, orange, green, or yellow.

Your link should look something like this. In my case, I chose blue.

Next, replace <int:box_id> with a number from 1 to 400. In my case, I chose 23.

Your link should look something like this.

After the above step, click the blue Send button.

Repeat the previous for the PUT and DELETE requests.

👨‍🚀 Collection Runners

To automate the tedious process of turning each empty square into a particular color, one can use the Collection Runner feature instead of using cURL or the Postman app.

Change the POST route to look something like this. Remember you can change blue to green, yellow or orange:

At the top-left of the Postman app, click the Runner button.

You should be led to a page like this:

On the left page, choose the Color Changer collection. You should be taken to the following page. Make sure that only the POST request is checked.

Change the environment to the Deploy environment. Afterwards, input a CSV file that lists numbers from 1 to 400. This way, the collection runner can start from 1, change the color to blue, and repeat the process until the runner hits 400. After giving the collection runner the file, click the big blue Run Color Changer button.

This is what you should see:

========================================

This was the content presented at the Intro to APIs workshop held at UC Davis and sponsored by PostmanAPI. This project was created by Bit Project’s Developer Team.

Links to Slides: 👉https://docs.google.com/presentation/d/1TBu85gPBvE8stuoCyGfgVzHIzKV_Ak5CLEBjF4eN6PU/edit?ts=5d943d61#slide=id.g70a6daab6b_38_16

Facebook: 👉 facebook.com/bitproject.org

Website: 👉https://www.bitproject.org/