nimblehq.co

Mockoon

Hero image for Mockoon

When

This is best suited when the API is NOT developed concurrently with the client applications. Use Mockoon since a comprehensive mock server solution is required.

To allow backend development and testing to proceed smoothly on the mobile side without the later Web team, the Mockoon JSON environment file and an initial Postman collection must be set up in advance. Depending on availability, the Web team or PM can perform the setup.

Terms

  • Environment: A JSON file that defines an entire mock API.
  • Routes: Paths that define the URL structure of a mock API.
  • Rules: Complex scenarios that can be fulfilled to serve the expected responses.
  • Headers: Data sent along with a request or response that provides information about the request/response.
  • Proxy: A feature that allows requests to be forwarded to a real API server, with responses then returned to the client as if they came from the mock API.

Instructions

Creating a Mockoon environment JSON file

There are two main scenarios for generating a Mockoon JSON file:

  • Create a brand new Mockoon environment - Mainly for creating one from scratch, and no corresponding Postman collection is available. For detailed instructions, please feel free to refer to its official guide.
  • Clone from an existing Postman collection - This is for when an extensive existing Postman collection is too troublesome to manually create again. Here is an example flow of exporting a Postman collection to a corresponding Mockoon JSON file:
    1. Select the Postman collection and export it as a collection v2.1 JSON file: Export a Postman collection to v2.1
    2. Take the newly generated JSON file and convert it to an OpenAPI v3.1 YML file by using this postman-to-openapi CLI:
      • Command: p2o ./path/to/PostmantoCollection.json -f ./path/to/result.yml
      • Example usage: Convert the Postman collection v2.1 to OpenAPI v3.1 YML
    3. Since Mockoon can support OpenAPI v3.1 JSON file only, it is necessary to transform the YML file to a JSON file with the swagger-cli:
      • Command: swagger-cli bundle -o api-spec.json api-spec.yml
      • Example usage: Convert OpenAPI v3.1 YML to OpenAPI v3.1 JSON
    4. Import the OpenAPI v3.1 JSON file to Mockoon and start creating mock responses 🚀

Exporting Postman collection to create the Mockoon environment JSON file is a good starting point only. For response creations, new API additions and modifications, they still need to be done manually due to the OpenAPI specification limited compatibility.

Sometimes, an endpoint can generate different responses based on various sub-paths or request body parameters. In that case, the Backend squad needs to add request rules corresponding to the actual parameters provided in the request. To learn more about serving different responses using rules, please refer to the official guide from Mockoon.

Working with the Mockoon collection

  • Once the Mockoon environment JSON file is created, all mobile team members use this file mainly as the mock API’s source of truth, and there is no longer a need to work with other tools like Postman.

  • Then, the Mobile Engineering Lead or Team Lead takes the JSON file from the Web team and shares it with the entire mobile squads via 1Password. (This file can also be shared with PM for local testing).

  • Where there are new changes or updates on the APIs raised by the mobile team, the mobile Engineering Lead or Team Lead needs to confirm and perform updates on the Mockoon JSON file apart from the Postman collection.

  • After the updates are complete, the Mobile Engineering Lead or Team Lead(s) will provide the new Mockoon’s environment JSON file for sharing across mobile team members on 1Password and notify relevant parties (PMs, Mobile developers, and supporting Web developer(s) if any).

Setting up initial support code for Mockoon

The objective is to facilitate easy connectivity switching between mock and regular servers (e.g., Mockoon’s mock server, Staging server, etc.) on Mobile applications. To achieve this, there are two available options:

Hard-coding the base URL value directly in the codebase

This option is convenient for developers who need to quickly switch between servers for local-machine debugging/development purposes.

Implementing a supporting feature to switch the base URL

This is a conventional long-term approach for cross-team testing and local-machine development. Additionally, since Mockoon will create a local mock server on the developers’ machine, it is highly critical to have a solution that allows changing the host URLs frequently. This is because it is unknown to the host URL per each machine’s available port or assigned IP addresses when testing with physical devices in a WiFi network.

As a result, while setting up a screen on the Mobile applications for changing the active host URL is more complex, it is highly recommended.