Skip to main content

Answer with a mock while the backend is built

The backend of the orders API is still being written, and the mobile app team wants to build against it now. The plugin mocking lets the route answer in the backend's place, with an order you write once. The request never reaches a backend. This guide puts mocking on orders-api so that every request gets the order {"id": 1042, "status": "shipped"}, then shows how to build the body from a JSON Schema instead. At the end, the app team calls the address it will keep using, and when the real backend is ready you remove the plugin and the same route sends the requests on.

Before you start​

  • This guide starts from orders-api as Route requests to a backend leaves it, with no other plugin. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
  • Whatever the route's target is, nodes of its own, an upstream or a service, mocking answers before the request would reach it. The backend nodes behind it may not run yet.
  • The requests below call /orders/42.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • The body the app team expects, agreed with the team that writes the backend. Here it is one order as JSON.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Open the route's Plugins tab​

Open orders-api under Routes, select its Plugins tab, then Add plugin at the top right of the tab.

2. Choose mocking​

Open the Transformation category, or type mocking in the search box. Select mocking, then Configure. A panel with the plugin's form opens.

3. Write the answer and add the plugin​

Keep A body written here chosen. Fill in these fields and leave the rest as they are.

FieldValueWhy
Response status200The status every mocked answer carries.
Content typeapplication/jsonThe client reads the body as this type says.
Response example{"id": 1042, "status": "shipped"}The body, sent as you write it.

Select Add plugin at the bottom of the panel. The tab now lists mocking, and the plugin is saved like this:

The Add mocking panel with a fixed JSON body, its content type and the status code filled in.
mocking · as the console saves it
{
  "response_status": 200,
  "content_type": "application/json",
  "response_example": "{\"id\": 1042, \"status\": \"shipped\"}"
}

From now on, every request that orders-api takes is answered by the gateway itself.

Check it​

Send a request to the route, the way the app will.

curl
curl -i -L 'https://<gateway host>/orders/42'
A request to the route
A request is answered 200 by the gateway itself with the body {"id": 1042, "status": "shipped"}; no backend is called.

Build the body from a schema instead​

When the teams have agreed on a JSON Schema for an order, the gateway can build the body from it. On the route's Plugins tab, select mocking in the list of plugins, then Edit. Choose A body generated from a schema and type the schema into Response schema:

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "status": { "type": "string", "example": "shipped" }
  }
}

Select Save plugin. The plugin is saved like this:

mocking · as the console saves it
{
  "content_type": "application/json",
  "response_schema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer"
      },
      "status": {
        "type": "string",
        "example": "shipped"
      }
    }
  }
}

Each property is generated from its type, and from its example where it carries one. Beside Response schema, the form shows this caution. Give every property a type: one without it makes every request answer 500. Under Content type text/html the generated body is empty.

This example sets no Response status, and the same request as above is answered 200.

A request to the route
A request is answered 200 by the gateway itself with a JSON body generated from the schema, whose status carries the example value shipped; no backend is called.

When the backend is ready​

On the route's Plugins tab, open the actions menu at the right of the mocking row and select Remove. Confirm with Remove plugin. From the next request on, the route sends requests to its target.

What to know​

  • A $name in the body, $uri for example, is replaced by the request variable of that name. A backslash before the dollar stops the replacement. The backslash is sent as well.
  • Response example and Response schema never go together. A configuration that carries both is refused when you save.
  • A Response status below 200 is refused when you save.
  • Every mocked answer carries x-mock-by, naming the gateway and its version, while With mock header is on. Turn it off on a sandbox route that partners call.
  • Delay holds the answer back for a number of seconds, to test how the app behaves with a slow backend.
  • A route can carry mocking and no backend at all. Under Target, the choice None sends nowhere, and the route serves its plugins alone.
G8 dev