Generated mock servers are an integral part of API design. API consumers can interact with your API before you build it, catching issues before you’ve invested a lot of time writing code.
Near the end of 2019, we made some major improvements to our open-source mock server, Prism. You can now use a proxy server to validate requests and responses, allowing for contract testing against live APIs. In addition, webhook support and live reloading features allow you to mock more APIs even faster.
Proxy Traffic to Build Prism into Testing
In the design-first workflow, mocking gives your team something to use before the API exists. Then, when enough feedback has come in and the team has decided to build the API, you hope the real API matches the mock API. Subtle differences can go unnoticed, with properties changing slightly, or being removed completely.
Prism v3.2 lets API consumers funnel their development traffic through a proxy server, such as your API-in-progress. It will report any mistakes it notices along the way, either with the requests you’re sending or the responses coming back from the server.
The proxy feature will help you identify discrepancies between your OpenAPI document (your source of truth) and any other server you designate as the proxy. This can help frontend developers integrate with your API, or other backend developers, who might want to channel their requests through Prism to see if they are making valid requests. The proxy can also be enabled in staging or any other pre-production environment, like a dress rehearsal before the opening night of a play.
This can help out folks not just working in development but can be a handy way to sniff traffic in an end-to-end test suite, with all the servers talking to each other through Prism and blowing up the calls if there is a mismatch in any of them. You can add contract testing to an existing test suite for very little work.
Validate Request and Response Data
In order to support the proxy feature, Prism also needed to provide full validation. While earlier Prism versions could validate input, Prism 3.2 can also validate the response data. There is now full callback support for OpenAPI response validation. As mentioned above, you can now use Prism’s mock server for complete contract validation. For example:
Say you have an invalid request in your API or are receiving an invalid response that does not match the rules of your OpenAPI specification document. Prism 3.2 will handle both and return an error message.
The mismatches it detects may be subtle, such as a minor schema difference (expected an integer, but a float number gets returned):
{
"type": "number",
"format": "integer"
}Returned data: 3.2
or the issue could cause a major error, like a missing field in the expected payload:
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"surname": {
"type": "string"
}
},
"required": ["name", "surname"]
}If the data coming from the server only had a name, it would cause a warning.
{
"name": "Clark"
}Here is the warning you would see in Prism: [5:55:28 PM] > [VALIDATOR]. Violation: response.body should have required property 'surname'
Support Webhooks in Your Mock Servers
In addition to validating requests and proxy servers, Prism added support for webhooks, which aren’t always easy to test. An API follows instructions when you make a request. Similarly, webhooks or web callbacks fire a request to a URL you specify. The request occurs when a defined state is met, such as a new record added to a system.
Creating and using webhooks in APIs has become a common practice, so community members flagged an issue for callback/webhook support in Prism. The Stoplight team built it into the 3.2 release. Here’s an example of how this might work when building an API to handle payment requests:
Let’s say that you want to build and test an API that is part of a SaaS system. With Prism 3.2 verifying responses and requests, you can test when a secure transaction is sent by a user’s account and when your company account responds with a confirmation of receiving payment. Prism 3.2 also validates that response to be true and, using a webhook specification on an API endpoint you have created, sends the user a key to use your service in the form of an HTTP request that will include the data they need to get started.
Automatically Reload Your Prism Servers
Finally, Prism 3.2 will save you a bit more time with its live reload feature. There is no longer any need to shut down the server manually and start it back up again when you make changes. Any changes to your OpenAPI document will now reload automatically. This saves you time and, more importantly, gives you or your team the ability to make rapid iterations such as adding new endpoints or changing out example responses.
Stoplight continues to work to make Prism smarter and more efficient for API mocking and testing. While automatically reloading is a small feature, we think it will make Prism even easier to use.
Generate Your Own Mock Servers
These brief examples show how Prism 3.2’s four new features can help you throughout the entire lifecycle of your API. We want to make Prism the best tool for mocking your APIs as part of your API design process.
Try Prism today to generate mock servers for your OpenAPI documents.
