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: 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
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
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.
With management API, you can retrieve current configuration by requesting
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
/config endpoint can return YAML format, when queried with
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.
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.
If management API is enabled, Mockintosh will record all requests that are not found in configured endpoints. You can
get config prototype for these endpoints by querying
GET /unhandled in management API.
/unhandled endpoint can return YAML format, when queried with
POST /unhandled endpoint also supports YAML as the payload.
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'
It’s possible to CRUD the resource files used in the configuration file (the paths starts with
endpoint. This endpoint accepts
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.
It’s possible to override the default directory path (which is the parent directory of the configuration file)
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.
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).
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.
file parameters are required in form data requests.
POST /resources -F 'email@example.com' also works in the same way but this time it’s a multipart request
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 'firstname.lastname@example.org'.
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.
DELETE /resources?path=somedir/myfile.txt removes the file
myfile.txt. Also removes the directory
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 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
DELETE also operates on both service-level and global-level.
DELETE endpoint returns the logs just before the
clean up operation is performed.
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