April is API Excellence month at Stoplight, and a great way to ensure the quality of your APIs is by performing automated validation that ensures your data conforms to your chosen design specification.
What is Data Validation?
When it comes to APIs, data validation means determining if data sent to and from the API falls within acceptable preset values. These values are usually spelled out in a document using a description language like OpenAPI. In practice, data validation involves checking if API requests and responses align with that API description. You will often see client-side and server-side validation, but it depends on the use case.
OpenAPI Data Validators
One of the great things about OpenAPI is you can find a TON of open-source and free tools created for it, including tools for data validation. Most of these free tools are simple plugin packages written for specific languages, like Python, JavaScript, and Go. You can use a plugin to integrate a validation tool with a server or client.
Here are a few free OpenAPI data validators currently available for popular languages:
APIFuzzer
- GitHub Repository: https://github.com/KissPeter/APIFuzzer
- Language: Python
- Supports OpenAPI Versions: 3.0 and 2.0
- Description: APIFuzzer is an HTTP API testing framework that reads an API description and then fuzzes the fields step by step to verify that the application can handle the fuzzed parameters. The tool comes with a number of features, including support for all HTTP methods and the file formats, JSON and YAML. The tool also supports the fuzzing of the request body, query string, path parameter, and request header.
Committee
- GitHub Repository: https://github.com/interagent/committee
- Language: Ruby
- Supports OpenAPI Versions: 3.0 and 2.0
- Description: Committee is a collection of middleware that you can use to build services using JSON Schema or OpenAPI (version 3.0 or 2.0). Among the middleware components are RequestValidation and ResponseValidation. RequestValidation validates the parameters of incoming requests against a particular schema. ResponseValidation validates the contents of a response for any route matching the JSON Schema.
express-openapi-validator
- GitHub Repository: https://github.com/cdimascio/express-openapi-validator
- Language: JavaScript
- Supports OpenAPI Version: 3.0
- Description: This tool is designed for ExpressJS, and it automatically validates API requests and responses using OpenAPI version 3.0. Among its features are request validation, JSON-only response validation, and security validation.
kin-openapi
- GitHub Repository: https://github.com/getkin/kin-openapi
- Language: Go
- Supports OpenAPI Versions: 3.0 and 2.0
- Description: This tool for Go lets you validate HTTP requests and responses using OpenAPI.
oas-tools
- GitHub Repository: https://github.com/oas-tools/oas-tools
- Language: Node.js
- Supports OpenAPI Version: 3.0
- Description: This tool lets you manage RESTful APIs (defined by OpenAPI 3.0) over Express servers. You can validate API requests and responses with this tool, and the tool validates API responses inside the router middleware. The tool can validate some functions of JSON Web Tokens (JWTs) once you specify a few parameters or create a function.
openapi-core
- GitHub Repository: https://github.com/p1c2u/openapi-core
- Language: Python
- Supports OpenAPI Version: 3.0
- Description: OpenAPI-Core is a Python library that adds client-side and server-side support for OpenAPI 3.0. Among the library’s features are API request and response validation, media type and parameters deserialization, and security providers (e.g., API keys, cookies, and HTTP authentications).
All of these tools can help you with API data validation and they’re all free to use! However, most of these tools have limitations or may not provide all the validation capabilities you need. That’s why we created Prism — so that you can do much more than basic validation.
Prism: Go Beyond Basic API Data Validation
Stoplight Prism is a free, open-source HTTP mock and proxy server. It lets you accelerate API development with mock servers generated from your OpenAPI (version 3.0 or 2.0) documents. You can work on validating and improving your APIs before writing any code — the mock server mimics your API’s behavior as if you’ve already built it.
Prism validates both API request and response data. It will tell you if a request doesn’t follow the rules of your API specification by returning an error message. The OpenAPI description document helps Prism figure out validation rules for different components of your API, such as:
- Request Body
- Headers
- Query Parameters
- Path Parameters
Prism can also validate all or parts of your API or its operations against specific servers.
What sets Prism apart from most free validation tools, besides comprehensive support and ease of use, is that it lets you set up a validation proxy for different API validation use cases.
What Is Prism’s Validation Proxy?
Prism’s proxy feature helps to identify discrepancies between the OpenAPI document and the targeted server. This feature differs from mocking as the validation proxy expects to find a real API running somewhere — e.g., an API deployed to a production server, localhost environment, docker container, or hosted sandbox environment. You can also load the proxy into a pre-production environment.
What Are the Use Cases for the Validation Proxy?
We recommend using Prism’s validation proxy as part of an API design-first workflow. Use cases for the validation proxy include:
Assist Consumers with API Integration
Ideally, API consumers will participate in the design process, providing feedback before developers begin coding the underlying functionality of the API. With Prism, you can create a mock API and validate it against the real API to detect discrepancies, like missing or changed properties.
In this scenario, the API team would create and distribute OpenAPI documents to API consumers. The team would then point the proxy server to the development environment, enabling error validation so that Prism denies requests that contain a mismatch.
API consumers can funnel their development traffic through Prism v3.2+, which runs as a proxy. Consumers can then relay that traffic to the API currently in progress. Prism detects and reports any errors with sent requests and responses from the server.
If everything goes well with validation, the real API will match the mock API. When they match, consumers will have a much easier time integrating the real API with their applications.
Simplify Contract Testing in API Testing Suites
When we say, “contract testing,” we mean running tests to ensure that the API continues to follow the structure of an API description language, like OpenAPI. If you design your APIs based on OpenAPI, the resulting document is essentially a written API contract. You can use that document to contract-test your APIs.
Many teams use traditional end-to-end testing suites where they must spend a lot of their time entering API information into the software if they want to do any contract testing. Some testing suites don’t even include contract testing capabilities.
You can integrate Prism with your test suite so that contract testing only requires that you change a few environment variables (or a service catalog) to point to the Prism proxy. Prism will then confirm the validity of each API request and respond automatically.
Warn Consumers About Deprecated Endpoints
Some API endpoints last for many years, and some have a short life span. Eventually, you’ll need to deprecate an API endpoint, sometimes many at once. And when you decide to deprecate an endpoint, you need to give your consumers advanced notice of that change. You have several options to get the word out about changes to an endpoint, such as email, API documentation, and messages on Slack.
A deprecation/sunset header is another way to warn consumers that an endpoint has been deprecated or changed. You can set Prism to emit a deprecation header when API client developers interact with an API mock or validation proxy. So, when client applications communicate with Prism, they would see a Deprecation HTTP header for any mock endpoint that has been set to “deprecated: true”.
Start Validating Your APIs Today
We encourage you to check out the free OpenAPI data validators we’ve highlighted today, including Prism. After all, you can’t have API excellence without proper tools. Validation will help you ensure that what you designed is what you are delivering.
