REST API Testing Part 1: Get Started with Postman, Swagger, and Assertible

This is post 1 of 1 in the series “REST API Testing Series”

Testing REST API architecture when engaging in software development is crucial for any development process, especially when multiple applications depend on these requests running as expected. As so, it’s a very important role of the QA team, and even developers, to ensure that these are working as expected to deliver the best quality possible for the applications in need of these requests. In a previous blog post, we explored the possibility of testing REST API architecture with different DSLs; in that particular case, using RestAssured with Java. In this blog post, we will explore a few of the most commonly used tools in REST API testing and how to use some of their most important features, in addition to determining which one suits a development process the best.

Postman

This is one of the most used tools—if not the most used—when it comes to REST API troubleshooting. Postman is a Chrome app tool used, in its simplest implementation, for executing requests and validating responses. The popularity of Postman is well deserved, as it delivers simple to complex features for everyday users to quickly test HTTP based requests. Some of Postman’s features include:

Widespread features: Some of these include executing all types of supported HTTP-supported requests, handling JSON, XML, Plain Text body requests, multiple headers or parameters, and validations of subsequent responses with JavaScript, such as expected status codes, expected body requests, parameters and headers, among many others.

Collections: Folder structured components that will hold a group of requests to be executed. These collections can be divided as per each user’s necessities whether it’s by server, functionality, business-related needs, or others.

Environments: In Postman, environments serve as global variables, which are key-value paired groups of information that will serve as static or dynamic information across all requests being executed with that specific key.

Import-Export capabilities: JSON standards are used when importing/exporting from Postman. Not only can you import/export individual requests, but also entire collections, environments, and even previously used test runner information.

Postman Runner: A built-in feature that executes requests within a collection in sequence and outputs test results of your JavaScript validations of each request executed. Adding to this feature, each run can be associated with a specific environment and can iterate or delay its execution, and test data can be associated in JSON format with the bodies of the requests to be run.

Newman + Jenkins CI: With Postman Runner comes the possibility of executing collections automatically using a Continuous Integration tool such as Jenkins or TeamCity. For this, Postman uses Newman, a command line tool specifically used for executing Postman Collections. Once these collections are executed using your command line with Newman, these bash commands are executed as steps in your Jenkins jobs to automatically deploy as part of any CI/CD process.

Swagger

The world’s most popular API framework, Swagger, uses OpenAPI to define the formats of your API RESTful requests. Swagger serves as both a documentation and a validation tool for your API requests in a web-based GUI that is easy to read and use and is based on standard JSON formats. Swagger helps align multiple request specifications into a single, readable format from which everybody involved in the development process can extract every single piece of information necessary from each request. Some of the most notable things that Swagger can help specify are:

Request types such as GET, POST, or PUT.
Request paths (URLs).
Parameters with respective names or descriptions.
Examples of bodies or associated definitions.
Expected responses.

With the information above, and each request clearly outlined, any team member can troubleshoot these requests and validate that the response codes returned are accurate in accordance with what the specification mentions. Besides requesting specific information, Swagger also outlines general information concerning all outlined APIs, such as their name, the base URL, schemes (HTTP / HTTPS), model examples, and Available Authorization info.

Swagger also has a “Try it out” button, which has the capability to run each request (one by one) so the user can verify the respective output. When attempting to execute, Swagger will read the definition of the request and ask the user for information that is necessary for it to be run, such as a parameter or a body. Once fields are input, the request runs and its response is shown. That being said, a disadvantage of Swagger is its limited verification functionalities, as it is up to the user to verify if the response is as expected. Additionally, requests have to be run one at a time, due to Swagger’s lack of built-in automation functions.

Assertible

After covering Postman and Swagger, we are left with the question, is there something out there that can both serve as documentation and make automatic API calls? Assertible can definitely help with that problem. Assertible tests and monitors the executions of your web requests and allows for powerful assertions using JavaScript. Not only that; it comes with a full integration with 3rd party tools, such as Slack, and allows for web requests to be initiated via a Swagger or Postman Collection. Some of these features include:

Creating collections with Swagger/Postman: When creating new web services to test, one of the biggest advantages of using Assertible is the possibility to import them from a Swagger definition or a Postman collection. The requests in either of these formats will be extracted and listed in Assertible automatically with no need for the user to input them manually, one by one.

Configurable assertions: As its name cleverly suggests, making multiple and configurable assertions are a part of everyday life in Assertible. The possibility of doing this greatly increases the tool’s productivity, as it can be used to add assertions to all endpoints as desired and add or remove them from more critical requests as needed.

Variety of actions: Once you have finished providing assertions and configuring your web request suite, you can perform a variety of actions on your requests, such as scheduling deployments on a daily or hourly schedule, monitoring those results via a history function, sending alerts of failures or successes via Slack, and even externally executing them ad hoc from any command line using a curl command.

As we have seen, there are quite a few good tools out there that will serve different needs when it comes to API testing. Both manual and automated tools or features are essential when troubleshooting or creating new RESTful requests, and they serve as platforms for any development team to expand upon and make their own implementations to serve their particular needs. In the next blog post, we will explore a proper application that turns the documentation features of Swagger into a tool that can automatically test multiple endpoints with different entries and their expected outcomes.