Using Postman for Mock API-Driven Development

For projects that require simultaneous backend and frontend development, mocking the API layer can be a crucial strategy to decouple these work streams and facilitate rapid development and iteration.

This technique is especially useful if requirements are not fully defined when development begins and features are added or removed during the development lifecycle.

Postman is a tool for documenting APIs, but did you know it also has features for setting up mock servers?

What makes this workflow useful:

• The frontend application can be iterated on quickly
• The API can be interactively designed and adjusted during development (at a relatively low cost since there’s no implementation to change)
• The mock API serves as a contract of the interface between frontend and backend (which can later be implemented regardless of the backend stack)

However, there are some pitfalls to be aware of:

• There are mock-specific features to learn and implement (e.g. response matching heuristics, wildcard params, path segment matching)
• Wildcard matching for query parameters is unsupported
• App features that rely on server-generated data may not be fully implementable
• Postman has limited support for dynamic variables
• Some mock API features require passing Postman-specific headers (e.g. x-mock-match-request-body which is required when mocking GraphQL endpoints)
• In some cases, you may need to write application code to accommodate the mock API integration, which is unfortunate and risky (e.g. hard-coding certain query parameters)
• Fully testing application features built against a mock API can be difficult (due to some of the limitations above)

Recommendations:

• Utilize Postman’s support for importing API definitions from external sources
• Define a version-controlled process for managing the mock API definitions in code using one of the supported standardized formats like Swagger, OpenAPI, or GraphQL which allows for better collaboration, maintenance and transparency during iteration, and import your API into Postman
• Aggressively annotate places in the code that require special handling for interacting with the mock API (using structured comments that enable grepability such as @MOCK(shawk): this query must be hard-coded in order to match correctly in Postman)
• Consider building some development/integration tooling to facilitate a tester being able to control which mock response is returned (using e.g. dat or some other UI selection mechanism that will set the x-mock-response-id header)
• Don’t use mock API servers for automated testing
• Be mindful of Postman’s mock API quotas/limits