How to Effectively use Groovy GPath in REST Assured – Part 2: GPath JSON

In part 1 of this series on how to effectively use Groovy GPath in REST Assured, we gave an overview of Groovy. We also covered installation options, the Groovy playground, and some of the basic concepts that will be useful to us for GPath in REST Assured. For part 2, we are going to focus purely on working with GPathJSON in REST Assured.

Although XML continues to be widely used amongst APIs (particularly legacy systems), there seems to undoubtedly be a shift towards JSON for newly developed APIs. My personal preference is for JSON, and it does seem to be the most popular. But if often doesn’t matter to us testers which we prefer to test, we will get whatever system we are given!

We need to understand how to use GPath in REST Assured to test both JSON and XML. Although there is a lot of crossover and similarities in the syntax for both uses of GPath in REST Assured, there are some key differences as well. We will see these differences as we go through the examples in the next two blog posts, starting with GPath JSON.

Since REST Assured is obviously just code, we can be very flexible in how we choose to write our tests. We will see that in the examples below.

In this blog post, we are going to cover the following:

Register for an API token from football-data.org

Add boilerplate REST Assured code to include the token and Base URL in all our requests

Look at 5 different ways of writing the same GPath JSON REST Assured test

Demonstrate a wide range of more complex examples for writing GPath JSON expressions

The Football-Data.org API

For all the GPath JSON examples in the next two posts we will use the football-data.org API . This is an easy to use RESTful API that provides data on football fixtures, results, teams and players.

You can use the football-data API anonymously without a key, which is a nice feature. However, you will be limited to 100 requests per day from your IP. With the API key, you can make 100 calls a minute. So it’s worth registering for one. It’s free, and it only takes a minute. To register for a key, go to the registration page on the football-data.org API website.

You should get an email straight away with the key, or “X-Auth-Token“. It should look something like this: fze4b032141e23f453c22dbb2f78946b . This key is fake, so make sure you actually register and don’t just copy this!

Add Boilerplate Code

With the key in hand we can begin setting up our boilerplate code in our project so that we can start using GPath JSON in REST Assured. We will be creating a @BeforeClass annotation. It will hold the REST Assured base URI and path, as well as a request specification builder with headers for the API key and another to reduce noise from the API by minimising the meta data returned.

This code will be executed before each of our GPath in REST Assured @Tests. It will set the base URI and path for us, and a couple of headers with the API Key and another to reduce the meta data in the response.

The First Test for GPath JSON – Written in 5 Different Ways

JSON Snippet – Details of a Team

Let’s write our first GPath JSON REST Assured test! We will call the API to get the details of a certain team (Manchester United), and printout the team name that is returned. This is the JSON that is returned from calling http://api.football-data.org/v1/teams/66

Let’s talk through what we are doing here line by line. On the first line we call the API endpoint, we only need to put “teams/66” because the base URL is specified in the @BeforeClass. We save the response in an instance of the REST Assured Response class. We can use the REST Assured get() method because of the static import we specified at the top. If you didn’t include the static import, you could write this instead:

Response response = RestAssured.get("teams/66");

On the 2nd line, we create a string called teamName. We call the .path() method on the response, and specify the JSONPath to this attribute (in this case simply “name”).

Example 2 – Specify JSONPath

A quick note on the .path() method. How did REST Assured know to use JSONPath, instead of XMLPath? We didn’t specify it! That’s some of the magic of GPath in REST Assured. If we wanted to specifically tell REST Assured to use JSONPath, we could write the same example like this:

This is doing the same thing as the other examples, but all the work happens on a single line. It’s down to personal preference which way you want to do it, and which way you think is more readable. I just wanted to show how many different ways you could write the same test using GPath JSON.

Example 5 – Given, When, Then

Let’s finish by writing the same test using the traditional Given, When, Then syntax supported by REST Assured. Instead of just printing out the team name, this test will check that it is actually correct:

We don’t need to specify a given() since that is handled in the @BeforeClass at the start. If we didn’t have the @BeforeClass, we would include the headers for the call here.

For the when() we ask to get the endpoint at http://api.football-data.org/v1/teams/66 .

Finally for the then(), we assert that the response body contains a name key with the value “Manchester United“.

Now that we have done the initial setup, and looked at different ways of writing the same test, lets look at some more complex examples. Remember, you can write these in whatever format is most suitable for you, as I demonstrated above.

Simple GPath JSON Examples

JSON Snippet – Data for many Teams

This is a snippet of the JSON that is returned when calling http://api.football-data.org/v1/competitions/426/teams . Actually more data is returned than is shown here, but I have trimmed it for example purposes. You should be able to call the URL above (even without an API key) and see the full response:

Extract Multiple Maps of Objects

Rather than just extracting each of the team names, suppose that you wanted to extract all of the data for each team (i.e. name, shortname, id etc.). You could do this by extracting a list, with each element in the list being a map of the team data:

REST Assured has given us a lot of power here, without having to write any complex code we are taking advantage of GPath JSON. This is what the ArrayList that we extracted above looks like visually in the IDE debugger:

Technique to Practice GPath JSON Expressions

Before we dive into the more advanced GPath JSON examples, I want to show you a good way of practicing your GPath JSON expressions using the Groovy Playground. This will make it much easier when writing your expressions into your REST Assured code. You will need to have the following two sites open:

The above will fail at the moment if we execute it, as we haven’t copied in the JSON yet. The next thing to do, is copy your JSON string into your clipboard, and remove all the white space. To do that, paste the JSON blob into Online JSON viewer and click “remove white space”, then copy the result back to your clipboard (as in the video below):

Now that you have your JSON without the white space, paste that back into the Groovy Playground (as in the video below):

You are now able to practice your GPath JSON directly in the Groovy Playground. Let’s take one of the previous examples where we extracted a list of all the team names. To do that now in the Groovy Playground, you would add the following line:

def allTeamNames = object.teams.name

So now your Groovy Playground would look like this, and you can see the ArrayList of team names when you execute the script:

I find this technique to be really useful when starting to write more complex GPath JSON that I need to figure out and test beforehand.

Let’s get into some of those examples now!

Advanced GPath JSON examples – Using Groovy

The examples we have seen so far have been useful and powerful. But we still haven’t seen any of the more advanced features of using GPath JSON in REST Assured. Such as using closures to loop over it, using find() and findAll() etc.

In the next few examples, we will build on the basic Groovy that we learnt about in the first post of this series to demonstrate the remarkable flexibility and power of GPath JSON in REST Assured.

Extract Map of JSON Object with Find

Let’s remind ourselves of the JSON that gets returned when we call the endpoint at http://api.football-data.org/v1/competitions/426/teams . Here is the snippet below again:

Suppose that from the above JSON, you wanted to extract a map with the key / value pairs of everything for Leicester City? So the id, name, shortName, squadMarketValue and crestUrl into a map.

Firstly copy all of the JSON returned from the response and remove the whitespace using Online JSON Viewer (as we saw above).

Then copy that trimmed JSON into the template in Groovy Playground (again as we saw above). Now we are ready to starting experimenting in Groovy Playground to find the right GPath JSON expression for us.

This is what the GPath JSON expression looks like in the Groovy Playground (mind the trimmed JSON below, replace that will the full JSON in yours):

Just to reiterate what is happening here in REST Assured. We examine the “teams” node and using GPath JSON we iterate over every element until we find the one that has the name ‘Leicester City FC’. Once we find it, all the data for that team (name, id etc) is returned in a map.

This is really powerful and useful stuff! In the remaining examples, I am not going to talk through the process of going through Groovy Playground again, but I recommend that you use the process outlined above when experimenting with your own GPath JSON expressions. It can save you a lot of time compared to experimenting with the expressions in your REST Assured code and having to keep executing the @Test to check the expressions.

Extract Single Value with Find

In the previous example, we extracted a map with all the data for a team. What about if we just wanted to extract a single value from the object, rather than the whole map?

For this example and the next few ones, we are going to use a new API endpoint. This is a subset of the JSON data that is returned from calling http://api.football-data.org/v1/teams/66/players :

Combine Find and FindAll in your GPath JSON Expressions

You can combine find() and findAll() in your expressions. Here, we are searching for all players with a position of “Centre-Back” and then from all the players that are returned, we find the single player (because find() only returns one result) with a nationality of “Argentina”:

Use Parameters in your GPath JSON Expressions

You can also use parameters in your expressions, to make them a bit easier to read. This is a similar example to the previous one, but using parameters instead and searching for a different position / nationality:

Not sure off the top of my head, but could you attempt to extract the postalCode from all possible locations (i.e. postalCode, phoneNumbers.postalCode, phoneNumbers.key.postalCode ) and then use whichever one is not null? Even if there are a few places postalCode can appear, I presume its still a finite number.