REST API Testing For Beginners

API testing is an inherently technical task. Instead of spinning up a new browser tab, typing into a slick user interface and clicking buttons, I reach for a tool and think carefully about data and endpoint paths. When we test an API, we deal with the stuff under the covers -- JSON, XML, REST, and web services. Let's take some fundamentals of software testing, flip them on their side, and see how we can get better at API testing.

Where to Start with RESTful Testing

You have to learn a little new language to work with an API. When I travel to new places that speak different languages, I start with the basics -- "One more coffee, please.", "Where is the bathroom?". Just enough to get what I need, and make it clear that I'm trying. That is where we will start with REST. You can worry about fluency later if you decide you want to come back and spend more time in API-land.

The basic language you need for REST are the words POST, GET, PUT, and DELETE.

GET and DELETE are pretty self-explanatory, so we won't spend time with those. POST is a fancy way of telling the software "Save this!" and PUT is how we say "I made a change, save that again."

Let's look at an example using the virtual Kanban software, Trello. If you want to follow along with the example, you can generate an application key and a user token following the instructions on this page.

I'm going to start by using the Trello API to get a list of all the boards I am currently subscribed to. By looking at the API documentation, I can see that this requires performing a GET on the following URL:

https://trello.com/1/members/my/boards?key=<substitutewithyourapplicationkey>&token=</substitutewithyourapplicationkey>

After running the GET command against that URL with the right authentication secrets thrown in, we get back a list of all the boards you are currently a member of. The data I get back from Trello comes in a special format called JSON. The name might sounds like scary geekery at first, but it is just a simple set of descriptions and strings or numbers paired together.

With that one example, we know two very important things -- first is that we can correctly authenticate to my Trello account, the second thing is that I can see some data in my account.

Some API Testing Basics with REST

High powered consultants sometimes parachute into new projects and have to test entire products. The normal life of a tester sees us working in iterations, probably testing a new end point over the course of a sprint. We are going to start with just one field and see what comes to mind.

One of the Trello boards listed when I ran GET before was called Coolest Trello Board EVAR. I don't really like that name anymore, so let’s change that and think of some test ideas at the same time. Since we are updating something that already exists, we are going to need to PUT this time.

The command to do that will look something like this:

https://trello.com/1/boards/[board_id]/name?key=<substitutewithyourapplicationkey>&amp;token=<substitutethispartwiththeauthorizationtokenthatyougotfromtheuser></substitutethispartwiththeauthorizationtokenthatyougotfromtheuser></substitutewithyourapplicationkey>

And along with that, we will need to send an addition to the query string that holds the new name.

&name=Better Board Name

I'm starting with a simple example just to see if we can even set a name. Every tester has had a build that was dead on arrival at least once in their life, simple beginnings like this save time in discovering that.

We can see that the PUT worked because a JSON response comes back that contains the new name. We also have a HTTP200 (success). A failed PUT would have an error along with some sort of HTTP code to describe what went wrong.

Let’s go deeper and get some test ideas to direct the next steps.

One thing we know from the specification is that this field should take from 1 to 16384 characters. When we think of this as a Domain Testing problem, there are boundaries at 0 and 1 characters, and also at 16384 and 16385 characters. We could quickly run those four tests to discover if the boundaries in the software are the same ones described in the specification. If they aren't, I immediately think of the question "Does this matter, is this a problem?" and start talking with developers and product folks to get some perspective.

Those four tests help discover information about the data length we can send in this field, but doesn't teach much about the kinds of data that are OK and the kinds that are not. That can cover lots of ground. I could test till the lights go out with that sort of question so I need to focus on what is important by asking questions.

Context Matters

Getting a hold on the technical aspects of API testing is part of the adventure. But at the same time, we don't want to forget about our context -- who is using the product, why are they using this part of it, what do they value. Thinking about the software from the point of view of a real live person, even when what we are dealing with is URLs and file formats, can take things from sanitized experiments, to a more nuanced place.

Context helps answer the questions like -- what users matter, what do those people value, what character sets matter, is punctuation a valid board name, how should we reject data, and should we accept multi-byte characters? There are usually interesting questions to ask about a product when we look a little deeper.

It is easy to get swept away in the technical details of testing an API, especially when they are a completely foreign concept.

Lucky for testers though, most of us are born learners. Technical understanding will come quickly and then we can get back to what is important. Testing software, and helping to build a better product.