Getting started with API tests

API tests are a great way to get quick feedback that your APIs are working as expected. In mabl, you can test your APIs using API steps in browser tests and by creating API tests in the API Test Editor.

This tutorial walks through the basic actions for creating API tests in mabl, from configuring your workspace to validating responses in the API Test Editor.

Before you start

In this tutorial, you will create an API test that validates the functionality of a mabl API endpoint that gets information about users in a workspace. Before creating your test, take the following steps:

Gather the necessary information

You need the following pieces of information to complete this tutorial:

• Workspace ID: Go to Settings > workspace and copy the workspace ID.
• "Viewer" API key: Go to Settings > API and create a "Viewer" API key

📘

API privileges

If you have an editor or viewer role, ask a workspace owner for permission to access the API keys.

Set up your workspace

To test the mabl API, add it as an application to your workspace. Go to Configuration > Applications and take the following steps:

• Add a new environment called "Demo".
• Add a new application called "mabl API" and associate with the "Demo" environment

When you create the "mabl API" application, you need to provide two application URLs:

• Web application URL: "https://mabl.com"*
• API URL: "https://api.mabl.com"

*The web application URL is required to create an application, but you won't need it for this tutorial.

📘

Brand new workspace?

If your workspace has no applications or environments, go to Configuration > Applications and click on the New button. You can create the "mabl API" application and "Demo" environment together.

Create an API test

Click on the New test button and choose API test. For your first API test, give the test a name, select No plan, and associate it with the mabl API application.

👍

Naming conventions and labels

With your team, discuss what naming conventions and labels you can use to distinguish practice tests from other tests in your workspace. Consider the examples below:

• Naming conventions: "Walkthrough - API test - Your name"
• Labels: "tutorial", "walkthrough", or "practice are good labels for distinguishing your practice tests.

Click on the Create test button to launch the API Test Editor.

Set up Auth

When you send requests to mabl API endpoints, you need to provide an API key. To set up authentication, click on the pencil to edit flow-level settings.

In the AUTH tab, select "Basic Auth." Add "key" as the username and insert the API key as the password.

Get all users in a workspace

For the first request, send a GET request to the Query Users endpoint. Click on the plus sign button to get started.

Add request details

The URL for the Get Users endpoint is https://api.mabl.com/users. Instead of entering the entire URL, use mabl variable syntax to simplify your request to {{@api.url}}/users.

📘

{{@api.url}}

{{@api.url}} represents your base API URL: https://api.mabl.com.

Click on the PARAMS tab and add the workspace ID as a parameter:

After configuring your request, click on the Send button. In the Results section, you should see a list of workspace users in the response body.

Validate the response

With assertions, you can validate that an API endpoint is returning the expected response.

📘

Default assertions

By default, the API Test Editor creates an assertion that the HTTP status is 200. Depending on your use case, you can edit the assertion to validate a different HTTP status, such as 201 or 204.

Let's assert that the response returned a users property:

• In the Validation and variable assignment section, select the Assertions tab.
• Click on the Add button.
• Enter the following JSON path: users
• Select "Is present" as the type of assertion.

Send the request again, and view the results of your assertion in the Assertions tab of the Results section.

Create a variable

You can also create variables from the response. Let's create a variable that stores the email address of the first user:

• In the Validation and variables assignment section, select the Variables tab.
• Click on the Add button.
• Enter the following JSON path: users[0].email
• Assign the following variable name: email

Filter users by email

For the final step in this tutorial, send another GET request to the Query Users endpoint with the "email" parameter.

Add request details

Enter the URL {{@api.url}}/users. Click on the PARAMS tab and add the following parameters:

• workspace_id: paste your workspace ID here
• email: {{@email}}*

*This is the value of the email address variable.

Click Send and view the response in the Results section.

Validate the response

Create assertions to validate the response.

For example, the assertions in the following screenshot validate that the endpoint returns exactly one user and that the user's email address matches the value of the email variable:

Click Send again and check the Assertions tab in Results to validate that the assertion passed.

Putting it together

Click on the play button the top left corner to run the entire test in the API Test Editor. You've just created your first API test. 🎉

Next steps

Now that you've familiarized yourself with the API Test Editor, think about how you can use it to test your team's APIs. Some questions for further exploration:

• What functionality do you want to validate?
• Which endpoints do you need to send requests to in order to validate this functionality?
• How can you use your API endpoints to augment end-to-end browser tests in mabl?

Learn more

Learn more about how you can use API testing in mabl to increase test coverage:

• API steps in browser tests
• API testing overview
• Integrating API tests and browser tests into a plan