Base APIs

A mock server can be configured to have a Base API. All requests sent to the server will be forwarded to the Base API:

$ mock serve \
  --base "example.com" \
  --route 'hello/world' \
  --response 'Hello world!'

Alternatively you may use the base configuration option for achieving the same:

{
  "base": "example.com",
  "middlewares": [],
  "endpoints": [
     {
       "route": "hello/world",
       "response": "Hello world!"
     }
  ]
}

Above we’ve set up an API that uses example.com as its Base API, furthermore an endpoint was set routed as hello/world. If a request is made to GET hello/world, the server will act normally responding with the response which was set - Hello world!. However if a request is made to an endpoint that has not been set, then the request will be forwaded to the Base API. In other words, a request to foo/bar will result in a proxy request to example.com/foo/bar.

Note

Base APIs defined through the command-line flag takes precedence over one set through configuration file. There can only be one Base API for a running mock instance.

Note

You can use mock solely as a Base API. Don’t define any endpoints and start up mock with only the Base API option. It will act as a proxy to some other service.

Intercepting responses

Endpoints defined for a mock API overwrite the ones from a Base API. In other words, when both your API and Base API offer the same endpoint, then your API’s endpoint takes precedence, therefore the Base API’s endpoint does not even get requested in that scenario. But that is the default behavior only, we can set things to behave differently if desired.

Through response shell scripts we can forward the current request to the Base API, and then the HTTP Response from Base API will be available in the $MOCK_RESPONSE_BODY environment variable, enabling us to tweak the response if desired, before sending to the client. This is accomplished using the forward command, executed from your endpoint’s shell script:

$ mock forward

Note

If the HTTP Response obtained from forward is encoded with gzip, mock decodes it for you, therefore the $MOCK_RESPONSE_BODY file will contain the decoded data for you to manipulate as you wish. Note also that mock removes the Content-Encoding HTTP Header upon decoding the data, therefore if you wish to respond to the client with encoded data, you must manually add again the Content-Encoding header.

Intercepting responses through middlewares

Middlewares can be used to manipulate responses given by a Base API. In fact Middlewares make no distinction between requests to Base API or otherwise.

On your middleware handler you can find out whether the context is that of a Base API request or not by reading the $MOCK_BASE_API_RESPONSE environment variable.

The middleware below adds a header Foo: bar to all responses proxied to a Base API:

if [ "$MOCK_BASE_API_RESPONSE" = true ];
then
  printf "Foo: bar" >> $MOCK_RESPONSE_HEADERS
fi

Alternatively you can just use the route_match middleware option in order to filter the requests which you want to manipulate, targetting the route patterns that are meant for your Base API.

Base APIs and TLS

The Base API option can take a simple domain (example.com) as its value, or a protocol+domain combo (https://example.com). Read further to understand how the different methods differ:

Domain only: The protocol set by the requesting client will be respected. If a client requests mock using HTTPS, then mock will request the Base API using HTTPS as well.

Protocol + domain combination: If a protocol is set in the Base API’s value, then mock will always use that protocol when forwarding the request, independent of the protocol chosen by requesting client.

Manipulating headers

There may be cases when you don’t want certain HTTP Headers from the Base API. For that, mock provides a command for easily removing headers:

$ mock forward
$ mock wipe-headers some-header-key another-header-key

Note

wipe-headers is meant to be used inside shell scripts.

A response handler shell script using wipe-headers as exemplified above will remove HTTP Headers some-header-key and another-header-key.

Note

wipe-headers is just a faster way of manipulating the $MOCK_RESPONSE_HEADERS file. The exact same could’ve been accomplished with:

$ mock forward
$ grep -v \
    -e some-header-key \
    -e another-header-key \
    $MOCK_RESPONSE_HEADERS | sponge $MOCK_RESPONSE_HEADERS

Regular expressions are also supported:

$ mock wipe-headers --regex some-regex-pattern another-regex-pattern