APIs have become the adhesive that holds the modern web together, reflecting the changing nature of web apps.
The modern web application is no longer a self-contained hub for the distribution of its own data. Once repositories of their own unique resources, web apps have become a mesh of internal and external data and other information, all carefully intertwined and relying on one another to fulfill their purposes.
Applications, both software and hardware, increasingly rely on external APIs to pipe data into their own APIs before being referenced, mutated, or checked against, ultimately providing the application's users with what they seek.
As a result, uniformity in how APIs operate and what they return has become an increasingly important goal for engineers who build and maintain the APIs. And with the number of APIs available increasing daily, a set of industry-wide standards has become necessary.
This has led to the creation and widespread acceptance of an API description format for RESTful APIs, known as the OpenAPI Specification. Here's why the spec is especially helpful for applications that rely on third-party APIs—and how it's useful in testing.
What is the OpenAPI Spec?
The OpenAPI Specification, formerly known as Swagger, defines a standard, language-agnostic interface to RESTful APIs. The interface allows humans and computers to discover and understand the capabilities of an API without access to source code or documentation.
At its core, the OpenAPI Specification is a JSON or YAML file for an API that provides these functions:
- Defines the API's endpoints and their available operations (GET, POST, PUT, PATCH, DELETE)
- Outlines the parameters necessary for the input and output of each operation
- Describes authentication methods
- Communicates other information associated with the API itself (contact, licensing, terms of use, etc.)
The OpenAPI Specification relays to an API's consumer what each endpoint provides, as well as the necessary steps needed to receive or send data.
It provides a handful of other companion tools to better help test and provide users with a deeper look into an API and its details. The Swagger UI automatically generates documentation that will accept parameters and then return responses from the API based on the rules outlined in the OpenAPI Specification itself. For its part, the Swagger Editor provides a browser-based editor where a developer can write OpenAPI specs and generate documentation in real time.
Figure 1: Screenshot of the Swagger Editor, a browser-based editor for creating OpenAPI specifications and documentation. Credit: https://editor.swagger.io/
Both the editor and the UI tools help users ingest an API more easily, and provide interactive docs in a clickable, simple-to-use interface. These docs allow you to see and test examples of each endpoint's response without writing a single line of code.
But the OpenAPI Specification is also used by engineers as a powerful tool for the internal testing of APIs in applications—especially APIs that rely on third-party integrations prone to encounter problems that are out of a developer’s control.
Contract testing
Contract testing integrates OpenAPI specs directly into your internal testing processes. At a basic level, contract testing verifies that an API's responses match the "contract" specified in an OpenAPI specification. This means making sure that responses contain all of the required properties, or that requests return the correct status codes upon completion.
In contract testing, an endpoint's response is tested to make sure it abides by the rules and guidelines defined inside of an OpenAPI specification. The testing results in either a passing or failing grade, similar to traditional continuous integration tests before deployment of an application's build.
Contract testing can even be included by an engineering manager in pull-request reviews, and automated to run with the continuous integration (CI) tool of your choice. If an API changes how it operates, not only in its structure but also in what is returned, it will not pass contract testing. This ensures that your application won't run into problems down the line that might be missed by simply testing for response error codes.
Contract testing also offers valuable time-saving features to make testing an API on deployment straightforward and painless. There's no need to come up with any test assertions that cover cases already described in your specifications, since API responses that don't match what the specs define will not pass validation.
Mock APIs
There are also other tools to make contract testing with the OpenAPI Specification as simple and efficient as possible. Stoplight lets you use a UI toolkit to create OpenAPI specifications that you can host as a mock server using Prism.
By using a mock server to host your OpenAPI specs, you can route incoming requests to example responses. To further cut down on the time necessary to get the testing environment set up and ready to go, Prism also creates dynamically generated responses on the fly based on your OpenAPI specs.
Essentially, a mock API simulates how a real API would operate. This not only benefits the testing process by emulating the functionality of your API when it would be fully operational, but also allows teams to begin work on an API before it actually exists. So, if one team is building features that rely on an API's response, it doesn't have to wait for the API to be created and tested before beginning its work.
If you set up a mock API based on the OpenAPI Specification with responses for each endpoint in place, then there is no need to wait for the API to return real data before implementing code to hit those routes and building functionality. The mock API will return responses that simulate its intended functionality before you even implement that functionality.
When you finish building the real API, as long as it conforms to the OpenAPI Specification, then all the features that rely on those endpoints will work as you intend them to.
The future of testing with OpenAPI
Heading into the future, there are many possibilities for API testing through the OpenAPI Specification. One possibility is to create a standardized template of OpenAPI Specs geared toward specific industries, such as healthcare, banking, or education.
This standardization would not only provide engineers with a faster means of building out their APIs, but would also give developers accessing those APIs a rigid guideline of what to expect when connecting to any API across that industry. The time-saving benefits on both engineering and development sides would speed up innovation in some of the most important and heavily utilized industries providing data today.
Unified APIs
Unified APIs present other interesting possibilities. A unified API is essentially an abstraction layer that consolidates multiple third-party APIs into a single set of data models accessed through common API endpoints.
The goal of a unified API is to reduce the time it takes to complete integrations with multiple similar applications to meet a common use case. (Disclosure: Kloudless, the vendor for which I work, sells a unified API.)
There are countless applications that benefit greatly from this level of abstraction. Let’s say you’re building a chat app and want to allow your users to attach a file from their preferred cloud storage service, or you’re building an interview tool and would like to check your users' calendars for availability.
There are hundreds of cloud storage apps and several calendaring tools that your users may be using. Integrating with every single one of these, or even just the majority, is time-consuming and error-prone, not to mention very hard to maintain. A single integration may take a developer hundreds to thousands of hours to create.
With a unified API, you’d code just once against the unified API’s endpoints, and the platform handles transforming data and filling in any missing functionality to provide the same integration experience regardless of the third-party app the user connects to.
Building APIs, unified or not, is an intensive process. Thankfully, the OpenAPI Spec has provided a means of simplifying the rigorous testing that the process entails.
It's clear the OpenAPI Specification is here to stay. The standardization of a way to describe RESTful APIs has proved to be of immense value to both those designing interfaces and those consuming them. In fact, the OpenAPI Initiative, an open-source project that took over control of the future of the OpenAPI Specification, just celebrated its third anniversary.
Keep learning
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
