Control API

Optionally, download the OpenAPI Spec ↗ or import it:

import spec from 'mockaton/openapi.json' with { type: 'json' }
console.log(spec)

How to use the API?

import { Commander } from 'mockaton'
const mockaton = new Commander('http://localhost:2020')

get /mockaton/openapi Get OpenAPI spec

await mockaton.getOpenAPI()

curl http://localhost:2020/mockaton/openapi

get /mockaton/state Get complete Mockaton state

await mockaton.getState()

curl http://localhost:2020/mockaton/state

patch /mockaton/write-mock Write a mock file

Writes a mock file to the mocks directory. Requires config.readOnly = false and config.watcherEnabled = true.

await mockaton.writeMock('api/user/friends.GET.200.json', '{ "friends": [] }')

curl http://localhost:2020/mockaton/write-mock \
  --request PATCH \
  --data '["api/user/friends.GET.200.json",""]'

patch /mockaton/delete-mock Delete a mock file

Deletes a mock file from the mocks directory. Requires config.readOnly=false

await mockaton.deleteMock('api/user/friends.GET.200.json')

curl http://localhost:2020/mockaton/delete-mock \
  --request PATCH \
  --data '"api/user/friends.GET.200.json"'

patch /mockaton/reset Re-initialize Mockaton

The selected mocks, cookies, and delays go back to their defaults, but proxyFallback, collectProxied, and corsAllowed are not affected.

await mockaton.reset()

curl http://localhost:2020/mockaton/reset \
  --request PATCH

patch /mockaton/select Select a mock file for a route

await mockaton.select('api/user/avatar.GET.json')

curl http://localhost:2020/mockaton/select \
  --request PATCH \
  --data '"api/user/friends.GET.200.json"'

patch /mockaton/bulk-select-by-comment Select all mocks that have a particular comment

await mockaton.bulkSelectByComment('(demo-a)')

curl http://localhost:2020/mockaton/bulk-select-by-comment \
  --request PATCH \
  --data '"(demo-a)"'

patch /mockaton/toggle-status Toggle a specific status for a route

Selects the first found mock with the given status, which could be the autogenerated one. Or, selects the default file.

await mockaton.toggleStatus('GET', '/api/user/friends', 500)

curl http://localhost:2020/mockaton/toggle-status \
  --request PATCH \
  --data '["GET","/api/user/friends",500]'

patch /mockaton/delay Set whether a route is delayed

await mockaton.setRouteIsDelayed('GET', '/api/user/friends', true)

curl http://localhost:2020/mockaton/delay \
  --request PATCH \
  --data '["GET","/api/user/friends",true]'

patch /mockaton/global-delay Set global delay for all responses

await mockaton.setGlobalDelay(1500)

curl http://localhost:2020/mockaton/global-delay \
  --request PATCH \
  --data '1500'

patch /mockaton/global-delay-jitter Set global delay jitter for all responses

await mockaton.setGlobalDelayJitter(0.5)

curl http://localhost:2020/mockaton/global-delay-jitter \
  --request PATCH \
  --data '0.5'

patch /mockaton/cookies Select a cookie label

await mockaton.selectCookie('Normal User')

curl http://localhost:2020/mockaton/cookies \
  --request PATCH \
  --data '"Normal User"'

patch /mockaton/cors Enable or disable CORS

await mockaton.setCorsAllowed(false)

curl http://localhost:2020/mockaton/cors \
  --request PATCH \
  --data 'false'

patch /mockaton/fallback Set proxy fallback address

await mockaton.setProxyFallback('http://example.test')

curl http://localhost:2020/mockaton/fallback \
  --request PATCH \
  --data '"https://example.test"'

patch /mockaton/collect-proxied Enable or disable collection of proxied responses

Applicable only when there’s a proxy fallback server URL already set. See PATCH /mockaton/fallback

await mockaton.setCollectProxied(true)

curl http://localhost:2020/mockaton/collect-proxied \
  --request PATCH \
  --data 'true'

patch /mockaton/proxied Set whether a route is proxied

Applicable only when there’s a proxy fallback server URL already set. See PATCH /mockaton/fallback

await mockaton.setRouteIsProxied('GET', '/api/user/friends', true)

curl http://localhost:2020/mockaton/proxied \
  --request PATCH \
  --data '["GET","/api/user/friends",true]'

patch /mockaton/watch-mocks Enable or disable mock file watching

Controls file watchers for mocksDir.

await mockaton.setWatchMocks(true)

curl http://localhost:2020/mockaton/watch-mocks \
  --request PATCH \
  --data 'false'

get /mockaton/sync-version Get sync version as SSE

A counter that’s incremented when a new mock is added, removed, or renamed. Also, when the internal state changes, e.g., when changing the mock file for a route.

await mockaton.getSyncVersion()

curl http://localhost:2020/mockaton/sync-version