Service catalog¶
Every import records a service in the catalog: its name, version, type, the format it came from, its operations with the ids of the stubs that implement them, labels, and who imported it when. It is the FastMock counterpart of the Microcks "APIs & Services" page and is shown in the UI. The OpenAPI and AsyncAPI documents themselves are stored too, for contract testing and the UI.
- What is recorded
- The service document
- Listing and reading services
- Stored specifications
- Re-imports
- Deleting a service
- Roles
- Storage, metrics and limits
The examples use FASTMOCK_TOKEN for a token with the needed role and the admin API on localhost:9090.
What is recorded¶
| Import | Type | Name and version | Tag | Document stored |
|---|---|---|---|---|
POST /import/openapi |
REST |
info.title, info.version |
tag |
yes |
POST /import/asyncapi |
EVENT |
info.title, info.version |
the import tag | yes |
POST /import/graphql |
GRAPHQL |
# microcksId, name/version |
tag or the service id |
no |
POST /import/soapui |
SOAP |
mock service name, version property |
tag or the service id |
no |
POST /import/wsdl |
SOAP |
wsdl:service name, version |
tag or the service id |
no |
PUT /grpc/descriptors/{name} |
GRPC |
{name}, 1.0 |
none | no |
POST /import/wiremock, /import/postman, /import/har |
GENERIC |
the tag, 1.0 |
tag |
no |
Dry runs record nothing. A catalog write that fails is logged and counted but never fails the import, because the stubs are already saved.
The service id is <name>:<version> in lower case, with every run of characters other than letters, digits,
. and _ replaced by one - (ids longer than 100 characters are shortened and end with a hash). It is a valid
tag, and the imports that default their tag use it: API Pastry - 2.0 version 2.0.0 has the id
api-pastry-2.0:2.0.0.
The service document¶
{
"id": "api-pastry-2.0:2.0.0",
"name": "API Pastry - 2.0",
"version": "2.0.0",
"type": "REST",
"sourceFormat": "openapi",
"tag": "pastry",
"operations": [
{"name": "GET /pastry", "method": "GET", "path": "/pastry",
"stubIds": ["019a9b5e-0c1f-7c51-9a6e-2f4f4a2b9c01", "019a9b5e-0c1f-7c51-9a6e-2f4f4a2b9c02"]},
{"name": "GET /pastry/{name}", "method": "GET", "path": "/pastry/{name}",
"stubIds": ["019a9b5e-0c1f-7c51-9a6e-2f4f4a2b9c03"]}
],
"labels": {"domain": "pastry", "status": "GA", "team": "pastry"},
"importedAt": "2026-11-19T10:15:02.114Z",
"importedBy": "ci",
"hasSpec": true,
"importOptions": {"validateRequests": false, "pathPrefix": ""},
"overrides": {
"labels": {"team": "pastry"},
"operations": {"GET /pastry/{name}": {"delay": 25}}
},
"artifacts": [
{"kind": "APIExamples", "importedAt": "2026-11-19T10:16:40.502Z", "importedBy": "ci"},
{"kind": "APIMetadata", "importedAt": "2026-11-19T10:17:03.881Z", "importedBy": "ci"}
]
}
| Field | Meaning |
|---|---|
type |
REST, SOAP, GRAPHQL, EVENT, GRPC or GENERIC |
sourceFormat |
openapi, asyncapi, graphql, soapui, wsdl, grpc-descriptor, wiremock, postman, har |
operations[].name |
Microcks operation name: GET /path for REST, the field for GraphQL, the operation for SOAP, package.Service/Method for gRPC, SUBSCRIBE channel / SEND channel for AsyncAPI; for other formats METHOD path of the stubs |
operations[].stubIds |
stubs that implement the operation, including APIExamples stubs |
labels |
from info.x-microcks.labels and APIMetadata |
overrides |
APIMetadata labels and operation settings, applied again on every re-import |
artifacts |
companion APIExamples / APIMetadata imports |
Operations of imported stubs are grouped by metadata.operation of the stubs (set by every importer), otherwise
by method and path.
Listing and reading services¶
curl -s localhost:9090/__admin/services -H "Authorization: Bearer $FASTMOCK_TOKEN"
curl -s 'localhost:9090/__admin/services?type=SOAP' -H "Authorization: Bearer $FASTMOCK_TOKEN"
curl -s 'localhost:9090/__admin/services?label=team=pastry&q=pastry' -H "Authorization: Bearer $FASTMOCK_TOKEN"
curl -s localhost:9090/__admin/services/api-pastry-2.0:2.0.0 -H "Authorization: Bearer $FASTMOCK_TOKEN"
GET /__admin/services returns {"services": [...]} with the most recently imported first. Filters:
| Query | Meaning |
|---|---|
type |
one of the types, case-insensitive |
label |
key=value, or key for "has the label" |
q |
case-insensitive substring of the name |
GET /__admin/services/{id} returns one service or 404 {"error": "service not found", "details": []}. To see
the stubs of an operation, read them by id (GET /__admin/stubs/{id}) or by tag (GET /__admin/stubs?tag=<tag>).
Stored specifications¶
OpenAPI and AsyncAPI documents are stored, after parsing, in the data store namespace specs under the service id:
curl -s localhost:9090/__admin/services/api-pastry-2.0:2.0.0/spec -H "Authorization: Bearer $FASTMOCK_TOKEN" | jq '.name, .type, .document.info'
{"name": "API Pastry - 2.0", "version": "2.0.0", "type": "REST", "document": {"openapi": "3.0.3", "info": {"...": "..."}, "paths": {"...": "..."}}}
Contract tests refer to it with specRef (the service id). The document is not stored when it is larger than
8 MiB serialized (logged as a warning); the service then has "hasSpec": false and /spec answers 404. Services
from other formats have no stored document.
Re-imports¶
Importing a service with the same name and version replaces the previous one:
- the stubs carrying the import tag are replaced in one transaction of the stub store, so every replica sees either the old or the new set;
- when the previous import used a different tag, the stubs of the old tag (and its
:examplestag) are deleted; APIExamplesstubs (tag<tag>:examples) are kept, as are labels and operation overrides fromAPIMetadata; for OpenAPI services the overrides are applied to the new stubs right away;importedAtandimportedByare updated and the stored document is replaced.
A different version is a different service, so versions can be mocked side by side when their paths differ (for
example with pathPrefix on the OpenAPI import).
Deleting a service¶
curl -s -X DELETE localhost:9090/__admin/services/api-pastry-2.0:2.0.0 -H "Authorization: Bearer $FASTMOCK_TOKEN"
The stubs carrying the service tag and <tag>:examples are deleted, then the stored document and the catalog
entry. The engine reloads immediately, and other replicas pick the change up as for any stub change. Deleting a
gRPC service removes only the catalog entry; remove the descriptor set with
DELETE /__admin/grpc/descriptors/{name}. The deletion is audited as service.delete.
Use one tag per service: deleting a service deletes every stub with its tag, including stubs added by hand with the same tag.
Roles¶
| Endpoint | Role |
|---|---|
GET /__admin/services, GET /__admin/services/{id}, GET /__admin/services/{id}/spec |
viewer |
DELETE /__admin/services/{id} and every import |
editor |
Storage, metrics and limits¶
Services live in the data store namespace services (PostgreSQL in shared mode, memory otherwise), so every
replica sees the same catalog. At most 1000 services are listed.
| Metric | Labels | Meaning |
|---|---|---|
fastmock_services_recorded_total |
type |
catalog entries written |
fastmock_store_errors_total |
store="services" |
failed catalog writes |
fastmock_admin_changes_total |
action="service.delete", action="service.metadata" |
catalog changes |