Mock server guide

A mock server imitates a real API server by returning mock API responses to API requests, and gives you some benefits:

• Try out your API as you design and develop it.
• Give feedback on API design before development begins.
• Act as an alternative for a sandbox or test environment during an integration.

To use the mock server feature, first add an API to the registry, then enable the mock server in the settings for that API.

Step 1: Set up your API

Follow the instructions in the API registry quickstart to connect your repository to the API registry and add an API definition.

Your API will be added to the registry. You will be redirected to the API Overview page, where the first build will automatically start.

By default, the mock server feature is disabled, and the Overview page doesn't display the mock server link.

The next step is to enable the feature.

Step 2: Enable mock server feature

Only users with the Admin project-level role for an API can enable the mock server feature.

The mock server feature is disabled by default.

To enable the mock server:

1. On the API registry page, select the API for which you want to enable mock server feature. The API Overview page displays.
2. From the top, navigate to Settings > Mock servers.
3. Check the Enable mock servers for all branches box and click Save button.
4. Optionally enable the mock server in your production or preview API docs by selecting your desired option.
   • off: Doesn't add the mock server URL to the servers list.
   • first: Adds the mock server URL as the first item in the servers list in the Try It console.
   • last: Adds the mock server URL as the last item in the servers list in the Try It console.
   • replace: Replaces the servers list with the mock server URL.

Select Save. Redocly generates mock servers for your primary and preview branches. If you enable the mock server in your product API docs, the primary branch rebuilds. Preview API docs aren't rebuilt automatically, and changes are applied with the next build. You can trigger a preview branch rebuild manually.

Back on the Overview page, you will see the mock server button for each published branch and all active preview branches of the current API.

Select the button to copy the mock server URL.

Step 3: Test the mock server

To test your mock server, copy the mock server link and use it as the server URL when sending a request in any API testing tool.

The mock server URL has the following format: <mock-server-id>.remockly.com. The <mock-server-id> part is automatically generated by Redocly. The URL is static and does not change when you modify the code in the branch or rebuild your API definition in the registry.

In the following example, we are sending a test request with cURL to the mock server with the URL your-example-server.remockly.com. The API definition tells us which path, operation, and parameters to use in the request.

openapi: 3.1.0
(...)
paths:
  '/users/{username}':
    get:
      tags:
        - User
      summary: Get user info by username
      description: |
        Some description of the operation.
        You can use `Markdown` here.
      operationId: getUserByName
      parameters:
        - name: username
          in: path
          description: "Name of a registered user. Must be an exact match."
          required: true
          schema:
            type: string
        - name: all
          in: query
          description: "Specifies whether to return all available information about the user. If omitted, the API returns only the basic set of information (email, registration date)."
          schema:
            type: boolean
            default: false
      security:
        - bearerAuth: []
(...)
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

If you enabled the mock server in your API docs, use the Try it feature to try it out.

Authentication for the mock server

Security for the mock server is based on the OpenAPI security definitions (such as api_key, bearer, or basic_auth) of your API in the registry. You must pass security parameters to the request in the correct format with any value. The mock server does not validate the actual credentials provided (only their format, such as the correct header name).

Custom headers for the mock server

Redocly supports the following custom headers that help you test the response content of your APIs:

• x-redocly-response-status - forces the mock server to reply with the specified HTTP status code, ignoring any validation or authentication if provided in the request. A response with the specified HTTP status code must be defined in the OpenAPI document for the particular operation you're testing. If such a response is not found, the mock server responds with its own default response.

• x-redocly-response-body-example - forces the mock server to reply with an example matching the specified example ID. If an example with the requested ID is not found in the OpenAPI document, the mock server responds with its own 500 error.

The following examples show how to force specific responses from the mock server by adding these headers to your request. We're using cURL to send requests to the mock server with the URL your-example-server.remockly.com.

curl --request GET \
  --url 'https://your-example-server.remockly.com/users/redocker?all=true' \
  -H "Authorization: Bearer anything-you-want-here" \
  -H "x-redocly-response-status: 429"

To further control the mock server behavior, use the mockServer object in your Redocly configuration file. Note that you must add this configuration file to your API project in the registry for changes to apply.