Postman API Testing¶
Postman is a free API testing tool which you can use to quickly set up API requests and modify them accordingly, after reviewing the server's response. It is currently one of the most popular tools used in API testing. With Postman you can test your API by visually creating your own requests and viewing the results. Some would say that Postman is the GUI version of cURL.
This guide will get you started with using Postman to test API endpoints and importing your own results to Calliope.
To make your very first request, you will first have to select what type of request you want to make, the most common types being GET, POST, PUT, and DELETE. Then fill out the URL of your endpoint and hit send. Postman will show you the server's HTTP response status code. and the body of the response. You can customise data such as the request headers., parameters, and the request body. For more detailed information on how to send requests with Postman, you can read more about Postman here..
APIs use authorisation to ensure that clients who request data have the correct permissions to request said data. You can pass authorisation details along with any request you send in Postman. It is recommended you use the Authorization tab in Postman to include your API key.
For example, to interact with the Calliope API you would select the type as API key, with as key '
x-api-key', along with your API key as its value. This will automatically generate a header called
x-api-key with your API key as its value for this request.
It is recommended you either use environment variables or that you set up authorisation in the parent collection. The benefit of setting up authorisation in the collection rather than each individual request is that all requests in the collection automatically know how to authorise.
A GET request is one of the most common and straightforward types of requests. It often only contains information about who's making the request. For example, GET requests often contain information about the browser that the client uses, and in our example above, the request included an API key for authorisation of the client.
Anytime you visit a website, no matter how basic, your browser is making a GET request to a server, and the server is responding with the HTML, CSS, and JS files that the webpage stores. When you make a GET request in Postman, the server does not specifically know that you are using Postman to make this request, and will respond the same as if you were to visit it with for example Mozilla Firefox.
POST requests are slightly more complicated than GET requests as they often have a request body used, for example, to tell the server to add an entry to the database. Often this is raw JSON data with a content-type of
In the context of importing test results to Calliope using POST requests it is useful to know that Calliope does accept JSON but prefers to receive
file as the key for the request body and then select your test result files as the value.
The difference between these two methods is that contrary to a raw JSON body, the uploaded file(s) will include their metadata which Calliope uses to improve your test results.
To be able to start using your Postman scripts in an automated process, Newman is a recommended tool. To learn more about setting up reporters with Newman, click here. You can read more about how Calliope supports Newman JSON output here.
The Calliope Collection is a full set of requests that you can use with the Calliope API. To get started with trying out the Calliope API using our Postman Collection, follow the steps below.
- Download our Postman Calliope Collection here.
- Import the Calliope Collection, called "
- Right-click the Calliope Collection and click edit then click the Variables tab.
- Fill in your API key as the current value for
- If you have no profiles yet, create a company, give it a project and create a profile.
- Now select your newly created profile. The URL will look something like
- Return to Postman and for the
projectIdcurrent variable enter the number that's behind
/projects/in your URL, in our example it's 1.
- Now for the
profileIdcurrent variable enter the number that's behind
/profiles/in your URL, in our example it's 2.
- The Calliope Collection is now set up and ready to go. Click any request and you should be able to fire a request by clicking Send. Import requests require you to select a file first in the Body tab of the request. The ZIP file you downloaded earlier includes an example file for each supported format, at the time of writing.