Responses from Shell scripts

You can write shell scripts that will act as “handlers” for your API’s Requests.

{
  "endpoints": [
    {
      "route": "foo/bar",
      "response": "sh:my_shell_script.sh"
    }
  ]
}

In the example above, any request to POST /foo/bar will result in mock executing the my_shell_script.sh.

Scripts can define the HTTP Response through different methods:

• Write to response files which are referenced in environment variables like $MOCK_RESPONSE_BODY.

• Use command-line utilities provided by mock, such as mock write. and mock set-header.

A hello world script-based response handler looks like the following:

echo "Hello world!" | mock write

To further customize your script handlers, you may also pass parameters, just like you can normally pass parameters in a shell command:

 {
   "endpoints": [
     {
       "route": "foo/bar",
+      "response": "sh:my_shell_script.sh some_param another_param"
     }
   ]
 }

To define responses with shell scripts using command-line parameters, use the following:

 $ mock serve \
+  --route "foo/bar" \
+  --shell-script my_shell_script.sh

Alternatively, shell commands can be set as one-liners with exec instead of sh, not requiring you to create a shell script file. As an example, the endpoint below responds with a list of files of the current folder (ls -la):

 {
   "endpoints": [
     {
       "route": "foo/bar",
+      "response": "exec:ls -la | mock write"
     }
   ]
 }

You can use more advanced shell functionalities within exec, such as pipes. Let’s set an endpoint that returns the amount of files that exist on the home folder:

 {
   "endpoints": [
     {
       "route": "foo/bar",
+      "response": "exec:ls ~ | wc -l | mock write"
     }
   ]
 }

The same can be accomplished through command-line parameters:

 $ mock serve \
+  --route "foo/bar" \
+  --exec 'ls | sort | mock write'

Environment Variables for Request Handlers

As with any shell programs, environment variables can be read. Besides environment variables provided the operating system environment, there are also variables provided by mock which give you useful information about the current request being handled.

These variables are documented in detail in the Mock Variables page.

Route Parameters - Reading from Shell Scripts

Route Parameters can be read from shell scripts. Suppose an endpoint exists as such: user/{user_id}. We could then retrieve the User ID parameter by reading the MOCK_ROUTE_PARAM_USER_ID environment variable.

Alternatively we can retrieve the same route parameter using get-route-param:

$ mock get-route-param user_id

Response Files that can be written to by shell scripts

The following environment variables enable you to manipulate the HTTP Response:

• MOCK_RESPONSE_BODY: A file that can be written to in order to set the HTTP Response.

• MOCK_RESPONSE_STATUS_CODE: A file that can be written to in order to define the HTTP Status Code.

• MOCK_RESPONSE_HEADERS: A file that can be written to in order to define the HTTP Headers.

In the following example, we’ll see what a Handler looks like, which responds with a simple Hello world! body content, a 201 Status Code and a few custom HTTP Headers.

echo Hello world! > $MOCK_RESPONSE_BODY

cat <<EOF > $MOCK_RESPONSE_HEADERS
Some-Header-Key: Some Header Value
Another-Header-Key: Another Header Value
EOF

echo 201 > $MOCK_RESPONSE_STATUS_CODE