nimblehq.co

Postman Mock Server

Hero image for Postman Mock Server

When

This is best suited when the API and client applications are being developed concurrently. Use Postman Mock Server when the API implementation is NOT on par with the client application development. A common situation is that the squads for the client applications have more team members than the squad developing the API. Hence the development of the client applications goes faster than the API development.

Terms

  • Mock Server: A server that mimics the behavior of a real server by generating mock responses for API requests.
  • Mock Collection: A collection of requests and responses that define the behavior of a mock server.
  • Mock Environment: A set of variables that define the behavior of a mock server.
  • Mock Request: A request made to a mock server, which returns a predefined response.
  • Mock Response: A response returned by a mock server based on the request received.
  • Example: A specific set of request and response data within a mock collection.

Instructions

Creating the Postman Mock server

By default, there must be a ready collection for developers for this approach to work.

First, start creating a new environment by duplicating the existing environment (e.g., Staging) and name it with the following format - {Collection name} - Mock.

Click New > Mock Server > Select an existing collection and select the one that needs mocking.

Select the Mock environment which has just been created and then select Create Mock Server.

In practice, the Make mock server private checkbox should also be ticked so that calling the Mock server would require the API key to ensure only the allowed parties can use the Mock server.

An example of a Postman mock server configuration

Copy and replace the Mock URL with the Mock environment’s domain/base URL variable.

Setup the domain URL in the Mock environment

Finally, execute a request on the collection to verify if the mock server is set up correctly.

Example calls

Calculating Postman Mock Server usage when applicable

Using Postman Mock Server has a limitation on the number of free requests allowed per billing cycle. With the number of APIs implemented in the applications, the quota can be quickly exhausted exponentially for medium to large teams.

When this happens, while a payment method is available in the team-shared Postman account, the project’s Engineering Lead must also calculate and provide rough estimations on the potential cost usage for the mock server and inform the team members.

Setup initial support code for Postman Mock Server

The goal is to allow Mobile applications to seamlessly connect to the Postman Mock server. The developers have two options:

Hard-coding the base URL value directly in the codebase

This is an excellent option for developers to quickly switch between servers for local-machine debugging/development purposes.

Implementing a supporting feature to switch the base URL

This is the best long-term approach for cross-team testing purposes.

  • For Android, having a simple approach to support easy switching between the mock server host URL and staging/production server ones is already sufficient. At the same time, the mock server’s host will not change that frequently. Thus, a new mock build flavor would be the most simple and recommended option for local Mobile development.
  • For iOS, building a setting screen that allows switching the base URL is very fast and straightforward. Hence, it is the recommended approach.

Example

The following links to a project demo illustrating the practical applications on both iOS and Android platforms:

  • iOS: The project employs the Setting Bundle approach to showcase its functionality. This approach provides a seamless and effective solution for iOS devices to change the host URL.
  • Android: The project utilizes two different approaches on the Android platform. The first involves creating a Mock build flavor, enabling developers to generate a customized build specifically for mocking purposes (existing implementation). The second approach involves creating a custom Setting screen, granting users greater control and flexibility over the host URL switching feature.

API Mocking Demos - iOS and Android

The sample projects are private and only available internally.

Maintaining the implemented mocking code when necessary

While using x-mock-response-id in the request header can be an option to point to the desired mock example response, there will be boilerplate code that needs to be cleaned up when deploying the real server with newly available endpoints or when making production release builds. Therefore, the Mobile teams need to:

  • Avoid using x-mock-response-id in the request header in every response to reduce the mocking code. Prefer to use Postman’s Matching request body and headers instead.
  • When there is a pressing need to specify a specific mock example response (e.g., endpoints with the same request path/payload but can produce different responses), only apply x-mock-response-id header for that endpoint.
  • Remove x-mock-response-id references in the codebase when they are no longer needed (e.g., real server deployed with new endpoints, making production release builds, etc.).
  • Ensure that the app uses the actual server, not the mock server, whenever applicable.
  • Test the app thoroughly to ensure everything works as expected after each cleanup.