API docs by Redocly

GripMock API Schema (3.18.4)

Download OpenAPI specification:Download

URL: https://github.com/bavix/gripmock-openapi License: MIT

REST control plane for GripMock, a gRPC mock server.

Use it to load stubs, ask which stub a request would match, read call history and assert call counts — all while the server keeps running.

Base URL. Every path below is relative to /api, served on the HTTP port (4771 by default). The gRPC port (4770) and the ConnectRPC/gRPC-web gateway (4769) are separate.

Sessions. Send X-Gripmock-Session: <id> to scope a request to one session. Stubs created within a session are visible only there, and call history is kept apart. Without the header the request works against the global scope. The header is the only thing that decides scope here: a session field inside a posted stub is ignored, so no caller can place stubs into someone else's session. Stub files loaded from disk keep their own session field.

Not in this document. POST /api/mcp speaks the Model Context Protocol for agent tooling, and GET /metrics — outside /api — serves Prometheus metrics.

healthcheck

Liveness and readiness probes.

Liveness check

This endpoint indicates that the service is alive and ready to handle requests

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "time": "2019-08-24T14:15:22Z"
}

Readiness check

The test indicates readiness to receive traffic

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "time": "2019-08-24T14:15:22Z"
}

dashboard

Aggregate counters and build/runtime information behind the web UI.

Dashboard aggregate payload

Returns combined dashboard counters, runtime metadata, and process state in one response.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "appName": "string",
  • "version": "string",
  • "goVersion": "string",
  • "compiler": "string",
  • "goos": "string",
  • "goarch": "string",
  • "numCPU": 1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "uptimeSeconds": 0,
  • "ready": true,
  • "historyEnabled": true,
  • "totalServices": 0,
  • "totalStubs": 0,
  • "usedStubs": 0,
  • "unusedStubs": 0,
  • "coveredMethods": 0,
  • "totalMethods": 0,
  • "grpcAddr": "string",
  • "gatewayAddr": "string",
  • "httpAddr": "string",
  • "totalSessions": 0,
  • "runtimeDescriptors": 0,
  • "totalHistory": 0,
  • "historyErrors": 0
}

Dashboard overview metrics

Returns lightweight aggregate counters for admin UI dashboard.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "totalServices": 0,
  • "totalStubs": 0,
  • "usedStubs": 0,
  • "unusedStubs": 0,
  • "coveredMethods": 0,
  • "totalMethods": 0,
  • "grpcAddr": "string",
  • "gatewayAddr": "string",
  • "httpAddr": "string",
  • "totalSessions": 0,
  • "runtimeDescriptors": 0,
  • "totalHistory": 0,
  • "historyErrors": 0
}

Dashboard runtime and build info

Returns GripMock build metadata and current runtime process information.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "appName": "string",
  • "version": "string",
  • "goVersion": "string",
  • "compiler": "string",
  • "goos": "string",
  • "goarch": "string",
  • "numCPU": 1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "uptimeSeconds": 0,
  • "ready": true,
  • "historyEnabled": true,
  • "totalServices": 0,
  • "totalStubs": 0,
  • "totalSessions": 0,
  • "runtimeDescriptors": 0
}

sessions

Session IDs currently known to the server.

Session options

Returns distinct non-empty session IDs available in current stubs.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

services

Services and methods GripMock can serve, across every descriptor source.

Services

List of registered services

Authorizations:
None

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Service methods

List of registered service methods

Authorizations:
None
path Parameters
serviceID
required
string

ID of service

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Service method details

Returns exact metadata for one method (by short name or full method id).

Authorizations:
None
path Parameters
serviceID
required
string

Full service name (e.g. helloworld.Greeter)

methodID
required
string

Method short name (e.g. SayHello) or full id (e.g. helloworld.Greeter/SayHello)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "methodType": "unary",
  • "requestType": "string",
  • "responseType": "string",
  • "requestSchema": {
    },
  • "responseSchema": {
    },
  • "clientStreaming": true,
  • "serverStreaming": true
}

Service details

Returns exact metadata for one service including all methods and streaming capabilities.

Authorizations:
None
path Parameters
serviceID
required
string

Full service name (e.g. helloworld.Greeter)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "package": "string",
  • "name": "string",
  • "methods": [
    ]
}

Remove service

Removes a service added via POST /descriptors. Services from startup (proto path) cannot be removed.

Authorizations:
None
path Parameters
serviceID
required
string

Full service name (e.g. helloworld.Greeter)

Responses

stubs

Create, list, search and delete stubs, and inspect why one matched. Send X-Gripmock-Session: <id> to scope the call to one session; without it the request works against the global scope.

Getting a list of used stubs

The list is needed to quickly find used stubs

Authorizations:
None

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Getting a list of unused stubs

The list is needed to quickly find unused stubs

Authorizations:
None

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Getting a list of stubs

The list of stubs is required to view all added stubs. Use source query param to filter by source.

Authorizations:
None
query Parameters
source
string

Filter by source (file, rest, mcp, proxy)

service
string

Filter by service name (exact match)

method
string

Filter by method name (exact match)

session
string

Filter by session ID (empty means global stubs)

q
string

Case-insensitive substring search over service, method and stub ID

matcher
string

Filter by matcher kind(s) present on the stub input. Comma-separated for OR semantics (e.g. "glob,anyOf"). Valid kinds: equals, contains, matches, glob, anyOf.

limit
integer >= 1

Maximum number of returned stubs

offset
integer >= 0

Number of stubs to skip before returning results

sort
string

Sort order for result list

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new stub to the store

Creates a new stub or multiple stubs and adds them to the storage

Authorizations:
None
Request Body schema: application/json
required

Create a new stub in the store

One of
Array
id
string <uuid> (ID)

Stub identifier (UUID).

service
required
string

Fully qualified gRPC service name.

method
required
string

gRPC method name, without the service prefix.

priority
integer
Default: 0

Tie-breaker among equally specific stubs; higher wins. Specificity is compared first, so an equals stub still beats a contains stub with a higher priority.

used
boolean

Response-only — whether the stub has matched at least once. Ignored on input.

object (StubHeaders)

Matchers applied to gRPC request metadata. Header names are case-insensitive. All blocks present are AND-ed; an omitted or empty block always passes.

required
object (StubInput)

Matchers applied to the request body. All blocks present are AND-ed; an omitted or empty block always passes, so a stub with every block empty matches any request.

Array of objects (StubInput)

Per-message matchers for client and bidirectional streaming. With one element it is a broadcast pattern that every message must match; with several, element N is matched against the Nth message and the counts must be equal. Mutually exclusive with input — a stub with both is rejected. For OR semantics use input.anyOf.

required
object (StubOutput)

What the stub returns. Over this API exactly one side must be set: either the unary side (data, error, code, details) or stream. A stub carrying both is rejected with 400.

object (StubOptions)

Optional behavior settings for a stub

Array of objects (StubEffect)

Side effects applied after successful stub match

Responses

Request samples

Content type
application/json
Example
[ ]

Response samples

Content type
application/json
[ ]

Remove stubs

Deletes stubs. With X-Gripmock-Session only the stubs of that session are removed, so one client cannot wipe another session's fixtures; without the header the whole stub storage is cleared.

Authorizations:
None

Responses

Deletes a batch of stubs by IDs

Takes IDs as input and deletes them

Authorizations:
None
Request Body schema: application/json
required

Delete stubs by their IDs

Array
string <uuid> (ID)

Stub identifier (UUID).

Responses

Request samples

Content type
application/json
[
  • "51c50050-ec27-4dae-a583-a32ca71a1dd5"
]

Validate a stub payload without persisting

Validates one or more stubs and returns them normalized without adding to storage

Authorizations:
None
Request Body schema: application/json
required

Stub payload to validate

One of
Array
id
string <uuid> (ID)

Stub identifier (UUID).

service
required
string

Fully qualified gRPC service name.

method
required
string

gRPC method name, without the service prefix.

priority
integer
Default: 0

Tie-breaker among equally specific stubs; higher wins. Specificity is compared first, so an equals stub still beats a contains stub with a higher priority.

used
boolean

Response-only — whether the stub has matched at least once. Ignored on input.

object (StubHeaders)

Matchers applied to gRPC request metadata. Header names are case-insensitive. All blocks present are AND-ed; an omitted or empty block always passes.

required
object (StubInput)

Matchers applied to the request body. All blocks present are AND-ed; an omitted or empty block always passes, so a stub with every block empty matches any request.

Array of objects (StubInput)

Per-message matchers for client and bidirectional streaming. With one element it is a broadcast pattern that every message must match; with several, element N is matched against the Nth message and the counts must be equal. Mutually exclusive with input — a stub with both is rejected. For OR semantics use input.anyOf.

required
object (StubOutput)

What the stub returns. Over this API exactly one side must be set: either the unary side (data, error, code, details) or stream. A stub carrying both is rejected with 400.

object (StubOptions)

Optional behavior settings for a stub

Array of objects (StubEffect)

Side effects applied after successful stub match

Responses

Request samples

Content type
application/json
Example
[ ]

Response samples

Content type
application/json
[ ]

Get Stub by ID

Searches for Stub by ID

Authorizations:
None
path Parameters
uuid
required
string <uuid> (ID)
Example: 51c50050-ec27-4dae-a583-a32ca71a1dd5

ID of stub

Responses

Response samples

Content type
application/json
{
  • "id": "51c50050-ec27-4dae-a583-a32ca71a1dd5",
  • "service": "Gripmock",
  • "method": "SayHello",
  • "priority": 0,
  • "used": true,
  • "session": "string",
  • "headers": {
    },
  • "input": {
    },
  • "inputs": [
    ],
  • "output": {
    },
  • "options": {
    },
  • "effects": [
    ],
  • "source": "string"
}

Deletes stub by ID

The method removes the stub by ID

Authorizations:
None
path Parameters
uuid
required
string <uuid> (ID)
Example: 51c50050-ec27-4dae-a583-a32ca71a1dd5

ID of stub

Responses

Stub storage search

Performs a search for a stub by the given conditions

Authorizations:
None
Request Body schema: application/json
required

Search criteria including service, method, headers and data to match against stubs

id
string <uuid> (ID)

Stub identifier (UUID).

service
required
string

Fully qualified gRPC service name.

method
required
string

gRPC method name.

object

Request metadata to match against stub headers.

required
object

Request body to match against stub input.

Responses

Request samples

Content type
application/json
{
  • "id": "51c50050-ec27-4dae-a583-a32ca71a1dd5",
  • "service": "Gripmock",
  • "method": "SayHello",
  • "headers": {
    },
  • "data": { }
}

Response samples

Content type
application/json
{
  • "headers": {
    },
  • "data": { },
  • "error": "Message not found",
  • "code": 3
}

Inspect stub matching decision path

Returns detailed matching stages/candidates for a query without consuming stub times.

Authorizations:
None
Request Body schema: application/json
required

Inspect criteria including service, method, optional headers/session and input messages

id
string <uuid> (ID)

Stub identifier (UUID).

service
required
string

Fully qualified gRPC service name.

method
required
string

gRPC method name.

session
string

Session to resolve against; empty means the global scope.

object

Request metadata, matched against stub headers.

Array of objects

Request body, matched against stub input.

Responses

Request samples

Content type
application/json
{
  • "id": "51c50050-ec27-4dae-a583-a32ca71a1dd5",
  • "service": "string",
  • "method": "string",
  • "session": "string",
  • "headers": { },
  • "input": [
    ]
}

Response samples

Content type
application/json
{
  • "service": "string",
  • "method": "string",
  • "session": "string",
  • "matchedStubId": "string",
  • "similarStubId": "string",
  • "fallbackToMethod": true,
  • "error": "string",
  • "stages": [
    ],
  • "candidates": [
    ]
}

history

Calls the server has answered, newest first. Send X-Gripmock-Session: <id> to scope the call to one session; without it the request works against the global scope.

Get call history

Returns recorded gRPC calls (when history is enabled)

Authorizations:
None
query Parameters
limit
integer >= 0

Return at most N most-recent records

offset
integer >= 0

Skip the N newest records (page backward through older calls)

service
string

Keep only calls to this fully qualified service name.

method
string

Keep only calls to this method name.

error
boolean

When true, return only calls that ended with a gRPC error

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Purge call history

Deletes recorded calls. With X-Gripmock-Session only the records of that session are removed, so a test can reset its own history without disturbing the calls of a parallel session; without the header the whole history is cleared.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "deletedCount": 0,
  • "session": "string"
}

verify

Assert how many times a method was called. Send X-Gripmock-Session: <id> to scope the call to one session; without it the request works against the global scope.

Verify call counts

Asserts that a method was called a specified number of times. With X-Gripmock-Session the count covers that session's calls plus global ones — the same scope its stubs match in. Without the header every call is counted, including calls made under a session.

Authorizations:
None
Request Body schema: application/json
required
service
required
string

Fully qualified gRPC service name.

method
required
string

gRPC method name.

expectedCount
required
integer >= 0

Number of calls the method must have received.

Responses

Request samples

Content type
application/json
{
  • "service": "string",
  • "method": "string",
  • "expectedCount": 0
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "time": "2019-08-24T14:15:22Z"
}

descriptors

Load a compiled FileDescriptorSet into a running server.

List service IDs from REST-added descriptors

Returns service IDs (e.g. helloworld.Greeter) added via POST /descriptors. Use DELETE /services/{serviceID} to remove.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "serviceIDs": [
    ]
}

Upload FileDescriptorSet

Accepts binary Protocol Buffers FileDescriptorSet. Registers descriptors for dynamic service discovery. Returns service IDs for later removal via DELETE /services/{serviceID}.

Authorizations:
None
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "time": "2019-08-24T14:15:22Z",
  • "serviceIDs": [
    ]
}