Using Prism for API mocking and Contract Testing

What is API mocking? In short, it’s about creating a simplified version of an API that works at a mechanical level, even though it’s not implementing the logic of the API. Such an “API mock” then can be used by consumers of an API to start developing applications that use the API. This means that it’s possible to get feedback from consumers earlier in the development cycle, making it faster and more effective to gather early feedback and improve the API design.

Prism is an open software tool maintained and used by Stoplight for their API tooling that’s providing API mocking. It’s specifically for REST/HTTP APIs and is using the OpenAPI specification as its description language for APIs.

There are two major use cases for Prism. The first one is about mocking, i.e. about generating API mocks from API specifications. The second use case is about contract testing, where an API implementation is using Prism as a tool for validating incoming requests and outgoing responses. Let’s look at these two use cases in more detail.

API mocking with Prism

Prism is working with an OpenAPI specification and from this creates an API mock that accepts the data structures specified in the OpenAPI and responds with the data structures specified in the OpenAPI. This means that as soon as an OpenAPI specification has been created as part of the API design process, Prism can be used to generate an API mock and consumers can start testing the “live API.”

Because it’s generated, the API mock will not create meaningful results (in terms of the API logic), but consumers can already test workflows based on the API and provide feedback about the API design.

This approach allows API designers to gather feedback from consumers early on in the design process. This makes iterating on the design more cost-effective because API providers don’t have to invest in implementing the API already, but developers using the API can use the mock to start gathering first experiences with a “working version” of the API.

This iterative approach helps with creating designs that work well for consumers, but it only works as long as implementation work on the actual API has not started. However, Prism can help in that case as well because it can also act as a proxy between the API consumer and API implementation.

API Contract Testing with Prism

As a pure API mock, Prism responds to all requests by itself. Prism can also be used in proxy mode, in which case it accepts requests, inspects the payload and reports any discrepancies with the expected data format, and then forwards the request to existing API implementation. Prism then inspects the response of the API implementation, reports any discrepancies with the expected data format, and forwards the response.

In this mode, Prism effectively does contract testing because it will transparently pass through requests and responses, but it will report any discrepancies with the data formats defined in the OpenAPI specification.

This is called “contract testing” because it means that the contract that is specified in OpenAPI will be tested for every request and response. This is useful for catching problems both on the API consumer and provider side.

Proxy mode also allows for the API implementation to be incomplete. This can be useful while implementing the API when some logic already is implemented, while other parts of the implementation are not yet there and still should be mocked.

For this to work, an API implementation has to respond with the HTTP status code 501 (Not Implemented). Prism then will respond with a mock response based on the OpenAPI specification. This means that the coverage of an API implementation can be increased incrementally, with some parts of the API already working while other parts are still being mocked.

Conclusions

Prism is a useful tool for API developers. API mocks help with generating “working” APIs from OpenAPI specifications which can be used for gathering early feedback from consumers. Prism’s proxy mode supports contract testing and also is useful in terms of supporting partial API implementations where some parts are already operational while others still are being mocked.

Prism also can be useful in scenarios where APIs are needed for creating test environments that have API dependencies. If you are interested in that more advanced scenario, or in more details about the mocking and proxying scenarios discussed above, please check out the video where Phil Sturgeon of Stoplight talks about Prism.