Create and test RESTful APIs

Using Humlix for test generation

Welcome to the first article in a series on how to develop and test RESTful APIs. In this series, we will utilize Humlix when trying out different REST endpoints.

If you haven’t heard about Humlix before, it is a tool to help out when building and testing RESTful APIs. It can automatically generate tests to discover errors in API endpoints.

The series contains the following articles:

• RESTful API quick tutorial (in this article)
• Testing of a RESTful API (coming soon)

For many companies, it is crucial to build and maintain APIs for the Web. Building robust APIs that will be maintained and improved over time comes with a lot of challenges. In this guide, we will go from the basics of creating a RESTful API and continue by showing how to test it using Humlix to generate tests for us.

RESTful API quick tutorial

REST APIs are implemented daily by developers all over the world to enable communication between systems. They make it possible for systems implemented with different technologies to collaborate and understand each other.

We will go through some of the principles when building an API for the Web:

• Using the request methods (GET, POST, etc.) correctly
• Naming API endpoints
• Using parameters for filtering
• Using correct HTTP response codes

Use HTTP request methods correctly

HTTP defines request methods used to show the action to perform on a resource. HTTP verbs are another common way to refer to these request methods. Some of the most commonly used verbs are:

GET — Get one or more resources
POST — Create one or more resources
PUT — Update one or more resources
DELETE — Delete one or more resources

Naming API endpoints

When developing software, methods are often named using verbs to describe their intent, e.g., GetPerson or SetLimit. Because we have HTTP verbs used to indicate the action, we can name our endpoints using nouns instead, i.e., /persons instead of /getPersons.

Let’s look at a real-life example from GitLab and their Groups API. That API provides a GET /groups endpoint to get a list of groups for the logged-on user. They didn’t call it /getGroups because they used the GET HTTP verb to state the intention.

GET /api/v4/groups

Use parameters for filtering

RESTful APIs can provide means to sort or filter responses on the server-side so that clients don’t have to massage the response data. The technique for this is to use query parameters.

Let’s go back to the GitLab example above where the GET /groups endpoint can handle sorting if clients add a query string ?sort=asc.

GET /api/v4/groups?sort=asc

The image below shows how to use Humlix to make test requests to the GET /groups endpoint.

Use correct HTTP response status codes

HTTP response status codes are a way for an endpoint to inform the client of the request’s status. Was the call a success, or did it fail?

There are five categories of status codes, where the first digit defines the class of the response.

1XX — used for information, e.g., backend received a request
2XX — successfully handled request
3XX — redirection occurred
4xx — client request cannot be fulfilled, e.g., due to the wrong syntax
5xx — server failed to fulfill a valid request

Be sure to utilize more than just 200 OK responses for your API. Check this list of HTTP response status codes.

Thank you for reading

We will soon publish the follow-up article, Testing of a RESTful API, to show you how to generate RESTful APIs tests.