Testing REST APIs example: Build your own application to give it a try
If you decide a REST API is well-suited to you and your customers’ needs, then it’s time to design and test it based on those needs.
In order to fully understand how your target audience would use your API, you have to dogfood it yourself and then, once it’s out in the wild, you need to monitor how it’s being used. For both API testing requirements, let’s use the common REST API example of a simple contact system or address book.
You can start by assumin
g that there is some sort of contact information as endpoints—a name, an email address, a phone number. Then, you build an application around that. If you design your endpoint so you make an API call for contacts first, then you have to make subsequent calls to the email and address endpoints. For an address book of ten addresses, it is a minimum of 30 REST calls just to have a visual representation—like an address book—of your application.
Building an app just to test out your API may seem expensive, but you don’t need to produce a commercial-ready app, but rather one that just has the parts that the consumer wants to use to interact with your API. “Doing things like this helps you understand the architectural design of your API,” says Ahmad Nassri, Principal Architect at Telus Digital.
And like all products, Nassri says,
“When it comes to testing, you need to figure out your use cases of what people are building around your APIs,” not just the standards or what data goes in or out. "A lot of people look at APIs as data in and data out, but they should be a lot more than that.””
REST API testing for developer experience
Hitch developer community portal co-founder Bruno Pedro told us that one value of the REST API is in creating and automating functional testing. “Testing REST APIs lets you confirm that a controlled input always generates predictable responses.” He went on to say that in order to have successful functional testing, there are certain requirements:
-
Know which API calls to test and how your application uses them.
-
Identify the input you need to provide to make tests meaningful.
-
Using a tool like ReadyAPI, generate input using fake data that resembles what a real user would do.
But to be able to do this right you need to understand how your API consumers are going to use your API.
“When you’re using any product or tool to test your APIs, the tests you’re building are not just to validate the input or output with the API, but what applications can be built on it,” something that Nassri says is often missing.
When asked how do you do that when you are first building your API and maybe don’t know who your users are, he recommended to just create a hypothesis of the end user experience and adjust from there. He says that when you’re building API tests, it’s not enough to know the endpoint, “You actually have to build an application around it to test it from a usability point of view.”
Nassri offers the example of Flickr. This image hosting site was built as a photo service with a target photographer audience, but the Flickr API has nothing to do with that audience.
“Look at your API design as a product, how does that work and how does that affect your audience? The user experience and how users use it.”
Another important thing for REST API testing — beyond response time and accuracy of data — is making sure you also have API analytics and reporting. Testing is not just data in, data out, it’s testing how your API can be used and then after you’ve launched it and begin to use it, you can further change and update your API in response to users’ needs.
You also need to understand how your end-user developers are using your API. Nassri says he wants to understand:
- When developers are using the API
- Which endpoints they are using
- Which endpoints they are using more than the other(s)
- When they use one particular endpoint
- Why they use this particular endpoint
- What combination of endpoints they are calling
Continuing with the same REST API example as offered before, by knowing that when people are making REST calls for /contacts, they always also call the /email and /address endpoints, you can optimize your REST API so that these three endpoints are consolidated into one API call. So whether you are going the way of building your own application to test out your RESTful API use cases or you are carefully monitoring the API usage with an API testing tool, you uncover a need to make changes to your REST API which reduces the amount of API calls that need to be made.
Nassri points out that this is win-win — you make your API consumers happy because they have to make fewer calls, and your DevOps rejoice because it’s less strain on your servers.
The Three Levels of API Testing
“APIs, by their nature as being over-the-wire [or network protocol], allow for testing at a variety of levels: behavioral, contractual, and solution-oriented,"
API architect James Higginbotham, Executive API Consultant at LaunchAny, explains. He breaks down API testing into three essential aspects:
- Behavioral API testing ensures that it delivers expected behavior and handles unexpected behavior properly. This is the lowest, most internal value. Behavioral testing ensures that the REST API delivers on the expected behavior and handles unexpected behavior properly. Does the code work?
- Contractual API testing ensures that what is specified by the definition is what has actually been shipped via code. This falls at the middle level of needs. Contractual testing ensures that what is specified by the definition is what has actually been shipped via code. Does the API contract continue to function as we have defined it? With the right inputs? Outputs? Data formats?
- Solution-oriented API testing ensures that the API as a whole supports the intended use cases that it was designed to solve. This falls as the highest, mostly external value. Solution-oriented testing ensures that the API as a whole supports the intended use cases that it was designed to solve. Does the API solve real problems that our customers have? Does it do something that people actually care about?
Higginbotham calls this Maslow’s Pyramid of API needs, made up of growing concerns from the lowest—the internal—to the highest—external—levels. “Teams need to look beyond just testing for functional and behavioral completeness. They need to move upward to ensure what they are externalizing to internal and/or external developers is complete.”
Higginbotham says to flip that pyramid upside-down, balanced with the behavioral API testing tip as the base for all API testing. “I’m suggesting that if you flip the pyramid with API testing, you can focus more on testing the solution as it can be automated, unlike browser and mobile apps. Thus, you cause your QA team to become more focused on verifying value to the customer, with the other testing at the other two levels focused on internal workings to catch bugs in isolation.”
He points out that the solution-oriented API testing is often the hardest to carry out, particularly when it is a mobile or browser-based app. He says that when the data is run through a REST API, this testing becomes much easier and can add tremendous value.
“The constraints of REST encourage the use of HTTP specification, making it easier to build out tests by composing the right requests and responses, without the more complicated SOAP-based protocol details involved,” Higginbotham went on to say.
“The testing world has always pushed for the lower-level tests that verify internal functionality to the detriment of focusing on the product deliverables, because much of the UI-focused testing requires manual effort.” But, he says, this manual user interface testing is essential for putting developer experience first.
What You Need to Know for Testing REST APIs
The basics of good API testing — and good software testing really — are the same — you have to do it early, often and continually, and much of it can be automated.
What makes testing REST APIs particularly easy is because of the clear relationship between the data, made even clearer when used in conjunction with Hypermedia APIs.
“Again in Hypermedia there are a lot of standards that you can follow, but that also helps the hypermedia descriptions between the entities of the API or the data,” Nassri explained. “If you are following a RESTful architecture, you are sending descriptions from areas. With hypermedia, you’re describing the relationships between developers. Hypermedia can become a very important part in terms of testing APIs.”
He says Hypermedia is used a lot in terms of testing the functionality of APIs, but he says it is not used enough in terms of vesting and validating the behavior of the API, like they do at Mashape, with everything based on the HTTP spec and URLs, taking part in their APIs being very RESTful by design.
SendGrid email delivery software’s Matt Bernier echoes Nassri by saying that since REST is very standards compliant, it means you have description languages that can confirm to that as well, like Swagger, which SendGrid uses. He says REST is a small subset of specifications for how to send and accept API calls. When combined with other standards, this is where he finds an ease for API testing.
"You take a description language, like Swagger, that is based on the REST specification, is designed to describe REST endpoints, and is written in JSON. [Together they] allow you to then code against the specification and automate against that specification,” he said.
Also because the specification has all of the data about the fields, the structure, and the endpoints and the methods, URLs, that makes it really easy to then write both basic and more advanced tests that can be automated.
Bernier went onto explain: “You have this description language that gives you all the information, and all the variables have been taken out so there are no edge cases. In software if you can take all the edge cases you, it’s pretty easy to automate. And then you can write code against each edge case and then if that code happens to create tests then you have all of your unit tests and integrations tests for your API.”
From this you can also then automate things like documentation and library generation. “It makes it all really easy,” Bernier said.
The World's Most Trusted API Testing Tool
For REST, SOAP and other popular API and IoT protocols, ReadyAPI provides the industry's most comprehensive and easy-to-learn functional testing capabilities. Based on open core technology proven by millions of community members, ReadyAPI helps you ensure that your APIs perform as intended, meet your business requirements, timeframes, and team skill sets right from day one. Start REST testing your APIs off on the right foot by downloading your free trial of ReadyAPI today.
Learn more:
The Gap Between Your API Testing Goals and Reality
Data Driven Testing Obstacles
5 Best Practices for Data Driven API Testing
API Testing Strategy Best Practices
Why Load Testing Is Important