Importing¶
FastMock generates stubs from the API descriptions and traffic captures teams already have, so a mock does not have to be written by hand. Every importer turns the document into ordinary stubs (plus async mocks for AsyncAPI), tags them, and can preview the result without saving anything.
- Formats and endpoints
- Common options and response
- Auto-detection: POST /import
- OpenAPI 3
- Postman collections
- HAR captures
- Secrets
- Limits
- Metrics and audit
The examples use FASTMOCK_TOKEN for an editor token, the admin API on localhost:9090 and the data plane on
localhost:8080.
Formats and endpoints¶
| Format | Endpoint | Details |
|---|---|---|
| OpenAPI 3.0 / 3.1 (JSON or YAML) | POST /__admin/import/openapi |
below, Microcks artifacts for examples and dispatchers |
| WireMock mappings | POST /__admin/import/wiremock |
WireMock and MockServer |
| MockServer expectations | POST /__admin/import (auto-detected) |
WireMock and MockServer |
| Postman Collection v2.1 / v2.0 | POST /__admin/import/postman |
below |
| HAR 1.2 | POST /__admin/import/har |
below |
| AsyncAPI 2.x / 3.x | POST /__admin/import/asyncapi |
AsyncAPI |
| GraphQL SDL, WSDL, SoapUI projects, Microcks APIExamples | POST /__admin/import/graphql, /import/wsdl, /import/soapui, /import/microcks |
Microcks artifacts |
| any of the above | POST /__admin/import |
auto-detection |
Exporting goes the other way: GET /__admin/export?tag= returns stubs in the format POST /__admin/stubs/import
accepts.
Common options and response¶
| Option | Default | Meaning |
|---|---|---|
tag |
format name (postman, har, wiremock, …) |
added to every generated stub; it identifies the import |
replace |
true |
delete the stubs carrying tag first, in the same transaction, so re-importing a changed document leaves no stale stubs |
dryRun |
false |
validate and return the generated stubs without saving anything |
{"imported": 12, "removed": 11, "warnings": ["Get user / not found: same request as an earlier example; ..."]}
A dry run answers {"imported": 0, "removed": 0, "dryRun": true, "stubs": [...], "warnings": [...]}. Warnings
report what could not be converted or was skipped; the import still succeeds. A generated stub that fails
validation is skipped with a warning naming it (its name, or its id). A document that is not of the expected
format, or that yields no valid stub at all, is a 400 and nothing is saved, deleted or replaced: the stubs of the
tag stay as they were. The error lists the first warnings:
{"error": "the document produced no stubs; nothing was changed; mapping #0: no request; the mapping was skipped", "details": []}
Tags are 1..128 characters of [A-Za-z0-9-_.:/]. A request body that is not valid JSON, or has a field of the wrong
type, is a 400 too.
Auto-detection: POST /import¶
Send the document itself, as it is on disk, and let FastMock pick the importer. Options go into the query string.
curl -s -X POST "http://localhost:9090/__admin/import?tag=petstore&dryRun=true" \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/yaml' \
--data-binary @petstore.yaml
| Detected as | When the document |
|---|---|
| OpenAPI 3 | has openapi: 3.x |
| AsyncAPI | has asyncapi |
| Microcks APIExamples | has apiVersion: mocks.microcks.io/... or kind: APIExamples |
| Postman | has an item array and info.schema on schema.getpostman.com (or info._postman_id) |
| HAR | has log.entries |
| WireMock | is {"mappings": [...]}, a single mapping or an array of mappings (request + response objects) |
| MockServer | is an expectation or an array of expectations (httpRequest with httpResponse, httpForward, httpError, …) |
| SoapUI | is XML with a soapui-project root |
| WSDL | is XML with WSDL 1.1 definitions or WSDL 2.0 description |
| GraphQL SDL | is text with type Query, type Mutation, type Subscription, schema { or extend type |
| Query parameter | Meaning |
|---|---|
tag |
as above; default is the format name, for GraphQL, WSDL, SoapUI and Microcks the service id |
replace, dryRun |
as above |
format |
skip detection: openapi, wiremock, mockserver, postman, har, asyncapi, graphql, wsdl, soapui, microcks |
The response is the importer's response (AsyncAPI answers like POST /import/asyncapi). An unrecognised
document, or Swagger 2.0, answers 415:
{"error": "could not detect the document format; supported: OpenAPI 3, WireMock, MockServer, Postman v2, HAR 1.2, AsyncAPI, GraphQL SDL, WSDL, SoapUI, Microcks APIExamples", "details": []}
OpenAPI 3¶
curl -s -X POST http://localhost:9090/__admin/import/openapi \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d "$(jq -n --rawfile spec petstore.yaml '{spec: $spec, tag: "petstore", pathPrefix: "/v1", validateRequests: true}')"
| Field | Default | Meaning |
|---|---|---|
spec |
required | the document as a JSON object, or JSON/YAML text |
tag |
required | tag of the generated stubs |
pathPrefix |
"" |
prefix added to every path |
validateRequests |
true |
requests that violate the operation's parameters or body schema get a 400 with the violations |
replace, dryRun |
true, false |
see above |
Each operation becomes stubs answering its documented examples (or examples generated from the schemas);
$refs are resolved within the document. How examples are selected and dispatched is described in
Microcks artifacts.
Postman collections¶
Export the collection from Postman as Collection v2.1 and send it as collection (a JSON object or the file's
text):
curl -s -X POST http://localhost:9090/__admin/import/postman \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d "$(jq -n --slurpfile c shop.postman_collection.json '{collection: $c[0], tag: "shop"}')"
How the collection maps to stubs:
| Postman | Stub |
|---|---|
| saved example response | one stub; requests without saved examples are skipped with a warning |
example's originalRequest (else the item's request) |
method, path, query |
:id path segment, unresolved {{var}} segment |
path parameter: urlPathTemplate: /users/{id} |
{{baseUrl}}, host, scheme |
resolved from collection and folder variables, then dropped: stubs match on the path |
| enabled query parameters | equalTo matchers (values with unresolved {{var}} are not matched) |
| raw request body, when the request has several examples | equalToJson (ignoreExtraElements) or equalTo, so the examples can be told apart |
example code, headers, body |
response status, headers (except Content-Length, Set-Cookie, Date and hop-by-hop headers), jsonBody for JSON, else body |
| folders | one tag per folder level (name sanitised to the tag alphabet) |
Example:
{"item": [{"name": "Users", "item": [{
"name": "Get user",
"request": {"method": "GET", "url": "{{baseUrl}}/users/:id"},
"response": [
{"name": "found", "code": 200, "header": [{"key": "Content-Type", "value": "application/json"}], "body": "{\"id\": 7}"},
{"name": "missing", "code": 404, "body": ""}
]}]}],
"variable": [{"key": "baseUrl", "value": "https://api.example.com"}]}
generates GET /users/{id} answering 200 {"id": 7} and a second, identical request pattern for 404. Two
examples with the same request cannot both answer: the later one gets a lower priority (higher number) and a
warning; give the examples different query parameters or bodies to make both reachable, or use scenarios.
Variables are resolved once (a variable's value is not resolved again), dynamic variables like {{$guid}} are left
as text, and generated stubs have templated: false, so {{...}} left in a response body is returned literally
and never executed. Postman v1 collections are rejected with a hint to export as v2.1.
HAR captures¶
Save a HAR from the browser's developer tools (Network > Export HAR) or a proxy, and send it as har:
curl -s -X POST http://localhost:9090/__admin/import/har \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d "$(jq -n --slurpfile h session.har '{har: $h[0], tag: "checkout-session",
mimeTypes: ["application/json"], hosts: ["api.example.com"], captureHeaders: ["x-request-id"]}')"
| Field | Default | Meaning |
|---|---|---|
har |
required | the HAR document as a JSON object or JSON text |
mimeTypes |
all | keep only entries whose response MIME type starts with one of these (at most 32) |
hosts |
all | keep only entries for these hosts (exact host name, port ignored; at most 256) |
captureHeaders |
[] |
response headers to keep besides content-type (at most 32) |
tag, replace, dryRun |
har, true, false |
see above |
Each distinct request (method, path, query, body) becomes one stub replaying the first recorded response;
repeats are counted in a warning. The request's path and query become exact matchers, a JSON body
equalToJson, another body equalTo; request headers are not matched. Responses keep their status, the
content-type header, and the body (jsonBody for JSON, base64Body for base64-encoded content such as images,
else body). Entries without a response (blocked or failed requests) are skipped with a warning, as are
responses over 10 MiB.
Secrets¶
Postman collections and HAR files often contain real credentials. Before the stubs are stored or returned:
- query parameter matchers whose name is a sensitive key (
FASTMOCK_REDACT_JSON_KEYS, e.g.api_key,token) becomematches: ".*"; - sensitive JSON fields are removed from
equalToJsonmatchers, which then useignoreExtraElements: true; - text body matchers containing a secret (JSON, XML, multipart or form fields with sensitive names) are dropped;
- response headers matching
FASTMOCK_REDACT_HEADERSor sensitive name patterns (*token*,*secret*,*key*, …) are dropped; HAR imports keep onlycontent-typeandcaptureHeadersto begin with.
The warnings say how many stubs were changed. Request headers (Authorization, Cookie) are never turned into
matchers by these importers.
Limits¶
| Limit | Value |
|---|---|
| request body | 32 MiB |
| stubs per import | 10000 (every saved Postman example is one stub) |
| Postman items (requests and folders) | 10000, folders nested at most 32 deep |
| HAR entries | 10000; bodies over 10 MiB are skipped |
| generated stubs (Postman, HAR) | 64 MiB in total, after variables are substituted |
| parsing | no code is executed while importing; generated stubs are not templated (Postman, HAR) |
Metrics and audit¶
| Metric | Labels | Meaning |
|---|---|---|
fastmock_imports_total |
format, dry_run |
imports per format |
fastmock_import_detections_total |
format |
formats detected by POST /import |
Every saved import is audited as import.<format> with the tag and the number of imported and removed stubs, and
the imported API is recorded in the service catalog (GET /__admin/services).
See also: Admin API, Recording, WireMock and MockServer, Microcks artifacts, AsyncAPI.