Management API

Mockintosh allows to control it in-flight with several “management API” endpoints. Through requests to those endpoints, you can fetch some information about mock service state, as well as change parameters and configuration. This comes useful if you want to use Mockintosh as part of test automation, where each test case uses different mock fixture.

Management API is disabled by default. There are two ways to enable management API: global at separate port, or per-service with service’s port reused. The latter is convenient when you can’t afford exposing another port, for example from inside Kubernetes or cloud environment.

To enable global management API, consider this config example with top-level management section:

management:
  port: 8000
  # ssl: true
  # sslCertFile: "subdir/cert.pem",
  # sslKeyFile: "subdir/key.pem",

Uncommenting SSL settings will enable SSL on that port, just like with service’s SSL settings.

You can access global API of above settings via url like http://localhost:8000.

To enable management API on service level, you need to specify managementRoot property, which will designate URL path at which management API endpoints will be accessed:

services:
  - name: Mgmt demo
    managementRoot: __admin

You can access service’s management API of above settings via url like http://localhost:8001/__admin.

Minimalistic UI

When you open root URL of management API in browser, it displays you a minimalistic HTML page, allowing to access some API actions through UI.

Getting and Setting Mock Config

With management API, you can retrieve current configuration by requesting config path.

Also, you can issue a POST call into same endpoint, to dynamically set the config. The format for POST payload is same as you retrieve via GET. There are some restrictions on what can be changed live. Generally, you can only change endpoints contents.

The /config endpoint can return YAML format, when queried with format parameter GET /config?format=yaml. POST /config endpoint also supports YAML as the payload.

POST /config endpoint not only supports changing how the services respond to the requests but also supports changing the global settings of the configuration file.

Getting Service Statistics

By requesting stats path of management API, you can get information on how many requests were served by Mockintosh, each service and each endpoint inside service. Also, the statistics of response statuses will be available, as well as average processing time.

You can reset these stats by issuing DELETE call on same path.

Resetting Iterators

You can reset positions of dataset and multi-response endpoints, by issuing POST /reset-iterators request.

Unhandled Requests

By defualt, unhandled requests data capture is disabled.

If the unhandled requests data is enabled via curl -X POST http://localhost:8000/unhandled -d 'true' then Mockintosh will record all the requests that are not matched into the configured endpoints. You can get config prototype for these endpoints by querying GET /unhandled in management API.

The /unhandled endpoint can return YAML format, when queried with format parameter GET /unhandled?format=yaml.

You can disable the unhandled requests data with curl -X POST http://localhost:8000/unhandled -d 'false' whenever you want.

OAS Serving

Specifically for HTML UI, there is GET /oas that returns autogenerated OpenAPI specification for service (or services) . In UI, the most useful is ability to “try now” the mocked endpoint.

Also, you can specify existing OAS document for service like this:

services:
  - name: Mgmt demo with OAS
    managementRoot: __admin
    oas: '@path/to/service.oas.json'

Resources

It’s possible to CRUD the resource files used in the configuration file (the paths starts with @) using /resources endpoint. This endpoint accepts GET, POST and DELETE requests and operates on paths relative to the configuration file’s parent directory otherwise it return a 4xx. Also the files referenced in the such requests are required to be defined with @ prefix in the configuration file before hand. The directories are automatically created or deleted for the given paths.

Overriding The Relative Directory Path

It’s possible to override the default directory path (which is the parent directory of the configuration file) using the MOCKINTOSH_DATA_DIR environment variable. Such that you can place your resource files and reference them from the configuration file according to the directory path that you’ve specfied with this environment variable.

Reading

GET /resources returns the list of paths to the externals files used in the configuration file.

GET /resources?path=somedir/myfile.txt reads the files and returns its text.

GET /resources?path=somedir/myfile.txt&format=stream returns the file as an octet stream (downloads the file).

Creating/Updating

POST /resources -F 'path=somedir/myfile.txt' -F 'file=hello world' creates the directory somedir/ if it does not exist, updates the file myfile.txt if it exists otherwise creates it and puts hello world text into that file. path and file parameters are required in form data requests.

POST /resources -F 'somedir/myfile.txt=@myfile.txt' also works in the same way but this time it’s a multipart request and path parameter is not required. If path parameter is supplied then it works as a parent directory path for the path specified in the files’ key: POST /resources -F 'path=somedir/' -F 'myfile.txt=@myfile.txt'.

Note: Leading forward slashes (/) are ignored and name-inode maps like ., .. are supported in the path. But it always operates in paths relative to the configuration file’s parent directory.

Deleting

DELETE /resources?path=somedir/myfile.txt removes the file myfile.txt. Also removes the directory somedir/ if it’s empty after the removal of the file. If keep=true query argument is supplied then it does not remove the parent directories. Otherwise it removes the empty directories by unfolding from the referenced file’s parent directory to the directory that contains the configuration file.

Traffic Logs

Traffic logging records the details of every incoming requests and their corresponding responses. Traffic logging is disabled by default. To enable it; send the request POST /traffic-log -F 'enable=true' to the related service-level or global-level management endpoint.

To access the logs one can send a GET request to /traffic-log management endpoint. This endpoint returns the logs in HAR format. The logs can be retrieved separately based on service-level or as a whole on global-level based on the management endpoint that you’re requesting to.

To clean up the logs; simply send a DELETE request to /traffic-log management endpoint. Similar to GET request, DELETE also operates on both service-level and global-level. DELETE endpoint returns the logs just before the clean up operation is performed.

Setting Current Tag

For the tagged responses, you can get currently active tag, or set one. Issuing GET /tag will report currently active tag, doing POST /tag will set one. For POST, just place desired name of the tag into raw request body. Empty tag set means “no active tag”. Alternatively you can use the current query parameter instead of the raw request body like: POST /tag?current=tagname to set the active tag.

The payload for POST /tag management endpoint can be a list of tags that’s comma-separated like: POST /tag?current=tagname1,tagname2