Checking an API Response contains the correct number of items with API Fortress

When does the length of responses matter?

We have a discussion open about when you should and shouldn’t check the length of API responses, which attempts to answer this question as a community.  Regardless, if you’ve decided you need to check API response length, here’s how to do it in API Fortress

Our Example

We’re going to be retrieving jobs from the Sauce Labs REST API.  You can find the full API documentation here.

The API Method under test is getJobs, which returns the latest jobs for a specific user account:

GET https://saucelabs.com/rest/v1/<USERNAME>/jobs

==> JSON array of 100 jobs

By default, this response returns 100 jobs, but it’s possible to configure that for the Sauce Labs API by adding the limit parameter.  We’re going to check that works, by limiting the response to 6 entries.

We’ve implemented this API call in the API Fortress Composer.  All this is doing is making a request for a list of jobs, run by the user set as the USERNAME variable.  I’m using another variable, BASIC_AUTH, to encode my credentials.  At the moment, it doesn’t have the limit parameter included, so it’s returning the default number of responses:

Step One - Capture the Response

First up, we need to store the value of the response in a variable.  Let’s click the Edit button on our request, and enter the name jobPayload in the Variable section.

Step Two - Adding the limit Parameter

Next up, we’re going to limit the API’s response size to 6.  Click Add Parameter under the Query Params section, give it the name limit, and the String value 6:

Click the Tick to save the request, and we’re ready to move on.

Step Three - Add an Assertion

Click the + Add Request / Assertions box, and choose the Assert Equals assertion:

Step Four - Configure the Assertion to check size

Now we’re ready to get Groovy.  The Groovy Programming Language, that is.  We can use this dynamic version of Java to write expressions.  For this step, we’re just going to check the size of the payload, but there’s a huge range of things Groovy can do.

The GET Jobs method returns an array of jobs in JSON format, which API Fortress into a java.util.ArrayList and stores under the parameter name we gave it (eg, jobPayload).  That means we can use any of the methods available for ArrayList… Such as size()!

If we set the Expression value of our assertion to jobPayload.size(), and the Value to 6:

Then once we’ve saved the assertion (By hitting the tick mark), running the test should check the size of our response!

Step Five - Running our test

Let’s click the Run button in the menu bar and see what happens:

Aww Yiss!  The assertion ran and checked the payload size.  Now we can be confident the limit parameter works!

Summary

To check the size of a response, you should:

1. Capture the response as a variable
2. Add an Assert Equals
3. Set the Expression to “variableName.size()”
4. Set the Value to the size you’re expecting

You can do the same thing with Assert Greater Than or Assert Less Than to check comparisons, too.

Happy Testing!