Microcks API
The Microcks platform API provides endpoints for managing services, test suites, and mock configurations programmatically. It supports integration into CI/CD pipelines for automated API testing and mocking.
OpenAPI Specification
---
openapi: 3.0.2
info:
title: Microcks API v1.14
version: 1.14.0
description: "API offered by Microcks, the Kubernetes native tool for API and microservices\
\ mocking and testing (microcks.io)"
contact:
name: Laurent Broudoux
url: https://github.com/microcks
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
x-logo:
backgroundColor: '#ffffff'
url: https://microcks.io/images/microcks-logo-blue.png
servers:
- url: http://microcks.example.com/api
description: ""
paths:
/services:
summary: This path operations deal with Services
get:
tags:
- mock
parameters:
- name: page
description: Page of Services to retrieve (starts at and defaults to 0)
schema:
type: integer
in: query
- name: size
description: Size of a page. Maximum number of Services to include in a response
(defaults to 20)
schema:
type: integer
in: query
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Service'
description: List of found Services
security:
- jwt-bearer:
- user
operationId: GetServices
summary: Get Services and APIs
/tests:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TestRequest'
required: true
tags:
- test
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/TestResult'
description: Created TestResult (empty shell cause tests are executed asynchronously)
security:
- jwt-bearer:
- user
operationId: CreateTest
summary: Create a new Test
/services/count:
get:
tags:
- mock
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Counter'
description: Number of Services in datastore
security:
- jwt-bearer:
- user
operationId: GetServicesCounter
summary: Get the Services counter
/jobs:
summary: This path operations deal with ImportJobs
get:
tags:
- job
parameters:
- name: page
description: Page of ImportJobs to retrieve (starts at and defaults to 0)
schema:
type: integer
in: query
- name: size
description: Size of a page. Maximum number of ImportJobs to include in a
response (defaults to 20)
schema:
type: integer
in: query
- name: name
description: Name like criterion for query
schema:
type: string
in: query
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ImportJob'
description: List of found ImportJobs
security:
- jwt-bearer:
- user
operationId: GetImportJobs
summary: Get ImportJobs
description: Retrieve a list of ImportJobs
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
required: true
tags:
- job
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
description: Created ImportJob
security:
- jwt-bearer:
- user
operationId: CreateImportJob
summary: Create ImportJob
description: Create a new ImportJob
/jobs/{id}:
summary: This path or subpaths operations deal with specific ImportJob having
given id
get:
tags:
- job
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
description: Found ImportJob
security:
- jwt-bearer:
- user
operationId: GetImportJob
summary: Get ImportJob
description: Retrieve an ImportJob using its identifier
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
required: true
tags:
- job
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
description: Updated ImportJob
operationId: UpdateImportJob
summary: Update ImportJob
description: Update an ImportJob
delete:
tags:
- job
responses:
"200":
content:
application/json: {}
description: ImportJob deleted
security:
- jwt-bearer:
- admin
operationId: DeleteImportJob
summary: Delete ImportJob
description: Delete an ImportJob
parameters:
- name: id
description: Unique identifier of ImportJob to manage
schema:
type: string
in: path
required: true
/services/{id}:
get:
tags:
- mock
parameters:
- name: messages
description: Whether to include details on services messages into result.
Default is false
schema:
type: boolean
in: query
responses:
"200":
$ref: '#/components/responses/ServiceResponse'
security:
- jwt-bearer:
- user
operationId: GetService
summary: Get Service
delete:
tags:
- mock
responses:
"200":
description: Service has been deleted
security:
- jwt-bearer:
- admin
- manager
operationId: DeleteService
summary: Delete Service
description: Delete a Service
parameters:
- name: id
description: Unique identifier of Service to managed
schema:
type: string
in: path
required: true
/jobs/count:
summary: Count ImportJobs
get:
tags:
- job
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Counter'
description: Number of ImportJobs in datastore
security:
- jwt-bearer:
- user
operationId: GetImportJobCounter
summary: Get the ImportJobs counter
/secrets:
summary: This path operations deal with Secrets
get:
tags:
- config
parameters:
- name: page
description: Page of Secrets to retrieve (starts at and defaults to 0)
schema:
type: integer
in: query
required: false
- name: size
description: Size of a page. Maximum number of Secrets to include in a response
(defaults to 20)
schema:
type: integer
in: query
required: false
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Secret'
description: List of found Secrets
security:
- jwt-bearer:
- user
operationId: GetSecrets
summary: Get Secrets
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
tags:
- config
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
description: Created Secret
security:
- jwt-bearer:
- admin
operationId: CreateSecret
summary: Create a new Secret
/secrets/{id}:
get:
tags:
- config
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
description: Found Secret
security:
- jwt-bearer:
- admin
operationId: GetSecret
summary: Get Secret
description: Retrieve a Secret
put:
requestBody:
description: The Secret to update
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
required: true
tags:
- config
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
description: Updated Secret
security:
- jwt-bearer:
- admin
operationId: UpdateSecret
summary: Update Secret
description: Update a Secret
delete:
tags:
- config
responses:
"200":
description: Secret has been deleted
security:
- jwt-bearer:
- admin
operationId: DeleteSecret
summary: Delete Secret
description: Delete a Secret
parameters:
- name: id
description: Unique identifier of Secret to manage
schema:
type: string
in: path
required: true
/secrets/count:
get:
tags:
- config
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Counter'
description: Number of Secrets in datastore
security:
- jwt-bearer:
- user
operationId: GetSecretsCounter
summary: Get the Secrets counter
/tests/service/{serviceId}:
get:
tags:
- test
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TestResult'
description: List of TestResults for the Service having the requested id
security:
- jwt-bearer:
- user
operationId: GetTestResultsByService
summary: Get TestResults by Service
parameters:
- name: serviceId
description: Unique identifier of Service to manage TestResults for
schema:
type: string
in: path
required: true
/tests/service/{serviceId}/count:
get:
tags:
- test
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Counter'
description: Number of TestResults for this Service in datastore
security:
- jwt-bearer:
- user
operationId: GetTestResultsByServiceCounter
summary: Get the TestResults for Service counter
parameters:
- name: serviceId
description: Unique identifier of Service to manage TestResults for
schema:
type: string
in: path
required: true
/tests/{id}:
get:
tags:
- test
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TestResult'
description: Requested TestResult
security:
- jwt-bearer:
- user
operationId: GetTestResult
summary: Get TestResult
description: ""
parameters:
- name: id
description: Unique identifier of TestResult to manage
schema:
type: string
in: path
required: true
/tests/{id}/messages/{testCaseId}:
get:
tags:
- test
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RequestResponsePair'
description: List of request and response messages for this TestCase
security:
- jwt-bearer:
- user
operationId: GetMessagesByTestCase
summary: Get messages for TestCase
parameters:
- name: id
description: Unique identifier of TestResult to manage
schema:
type: string
in: path
required: true
- name: testCaseId
description: Unique identifier of TetsCaseResult to manage
schema:
type: string
in: path
required: true
/tests/{id}/testCaseResult:
post:
requestBody:
description: TestCase return wrapper object
content:
application/json:
schema:
$ref: '#/components/schemas/TestCaseReturnDTO'
required: true
tags:
- test
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TestCaseResult'
description: TestCaseResult is reported
operationId: ReportTestCaseResult
summary: Report and create a new TestCaseResult
description: Report a TestCaseResult (typically used by a Test runner)
parameters:
- name: id
description: Unique identifier of TestResult to manage
schema:
type: string
in: path
required: true
/keycloak/config:
summary: Keycloak Authentification configuration
get:
tags:
- config
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/KeycloakConfig'
description: Get current configuration
operationId: GetKeycloakConfig
summary: Get authentification configuration
/services/{id}/operation:
put:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OperationOverrideDTO'
required: true
tags:
- mock
parameters:
- name: operationName
description: Name of operation to update
schema:
type: string
in: query
required: true
responses:
"200":
description: Operation has been updated
"500":
description: Operation cannot be updated
security:
- jwt-bearer:
- admin
- manager
operationId: OverrideServiceOperation
summary: Override Service Operation
parameters:
- name: id
description: Unique identifier of Service to managed
schema:
type: string
in: path
required: true
/services/{id}/metadata:
put:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Metadata'
required: true
tags:
- mock
responses:
"200":
description: Service metadata has been updated
"500":
description: Update of metadata failed
security:
- jwt-bearer:
- admin
- manager
operationId: UpdateServiceMetadata
summary: Update Service Metadata
parameters:
- name: id
description: Unique identifier of Service to managed
schema:
type: string
in: path
required: true
/services/search:
get:
tags:
- mock
parameters:
- name: queryMap
description: Map of criterion. Key can be simply 'name' with value as the
searched string. You can also search by label using keys like 'labels.x'
where 'x' is the label and value the label value
schema:
type: object
additionalProperties:
type: string
in: query
required: true
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Service'
description: List of found Services (filtered according search criteria)
security:
- jwt-bearer:
- user
operationId: SearchServices
summary: Search for Services and APIs
/tests/{id}/events/{testCaseId}:
get:
tags:
- test
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UnidirectionalEvent'
description: List of event messages for this TestCase
operationId: GetEventsByTestCase
summary: Get events for TestCase
parameters:
- name: id
description: Unique identifier of TestResult to manage
schema:
type: string
in: path
required: true
- name: testCaseId
description: Unique identifier of TetsCaseResult to manage
schema:
type: string
in: path
required: true
/resources/{name}:
get:
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Resource'
description: Retrieve the resource having this name
security:
- jwt-bearer:
- user
operationId: GetResource
summary: Get Resource
parameters:
- name: name
description: Unique name/business identifier of the Service or API resource
schema:
type: string
in: path
required: true
/resources/service/{serviceId}:
get:
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Resource'
description: List the resources attached to a Service or API
security:
- jwt-bearer:
- user
operationId: GetResourcesByService
summary: Get Resources by Service
parameters:
- name: serviceId
description: Unique identifier of the Service or API the resources are attached
to
schema:
type: string
in: path
required: true
/features/config:
summary: Optional features configuration
get:
tags:
- config
responses:
"200":
content:
application/json: {}
description: Get features configuration
operationId: GetFeaturesConfig
summary: Get features configuration
/import:
summary: Deals with repository snapshot to import in Microcks
post:
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/SnapshotUpload'
required: true
tags:
- mock
responses:
"201":
description: Snasphot has been correctly imported
security:
- jwt-bearer:
- admin
operationId: importSnapshot
summary: Import a snapshot
description: Import a repository snapshot previsouly exported into Microcks
/export:
summary: Deals with repository snapshot to import from Microcks
get:
tags:
- mock
parameters:
- name: serviceIds
description: List of service identifiers to export
schema:
type: array
items:
type: string
in: query
required: true
responses:
"200":
headers:
Content-Disposition:
schema:
type: string
examples:
filename:
value: attachment; filename=microcks-repository.json
content:
application/json:
schema:
format: binary
type: string
description: Snapshot file representing the export of requested services
security:
- jwt-bearer:
- admin
operationId: exportSnapshot
summary: Export a snapshot
description: Export a repostiory snapshot with requested services
/metrics/invocations/global:
summary: Invocation Statistics across Services and APIs
get:
tags:
- metrics
parameters:
- name: day
description: The day to get statistics for (formatted with yyyyMMdd pattern).
Default to today if not provided.
schema:
type: string
in: query
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/DailyInvocationStatistic'
description: Aggregated invocation statistics for specified day
operationId: GetAggregatedInvocationsStats
summary: Get aggregated invocation statistics for a day
/metrics/conformance/aggregate:
summary: Aggregation of Test conformance metrics
get:
tags:
- metrics
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WeightedMetricValue'
description: Get aggregated coverage metric value
operationId: GetConformanceMetricsAggregation
summary: Get aggregation of conformance metrics
/metrics/conformance/service/{serviceId}:
summary: Test Conformance metrics on API and Services
get:
tags:
- metrics
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TestConformanceMetric'
description: Test coverage metric for Service
operationId: GetServiceTestConformanceMetric
summary: Get conformance metrics for a Service
parameters:
- name: serviceId
description: Unique Services identifier this metrics are related to
schema:
type: string
in: path
required: true
/metrics/invocations/top:
summary: Top Invocation Statistics across Services and APIs
get:
tags:
- metrics
parameters:
- name: day
description: The day to get statistics for (formatted with yyyyMMdd pattern).
Default to today if not provided.
schema:
type: string
in: query
- name: limit
description: The number of top invoked mocks to return
schema:
type: integer
in: query
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DailyInvocationStatistic'
description: Top invocations for a defined day
operationId: GetTopIvnocationsStatsByDay
summary: Get top invocation statistics for a day
/metrics/invocations/{serviceName}/{serviceVersion}:
summary: Invocation Statistics for API and Services
get:
tags:
- metrics
parameters:
- name: day
description: The day to get statistics for (formatted with yyyyMMdd pattern).
Default to today if not provided.
schema:
type: string
in: query
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/DailyInvocationStatistic'
description: Invocation statistics for service for specified day
operationId: GetInvocationStatsByService
summary: Get invocation statistics for Service
parameters:
- name: serviceName
description: Name of service to get statistics for
schema:
type: string
in: path
required: true
- name: serviceVersion
description: Version of service to get statistics for
schema:
type: string
in: path
required: true
/metrics/invocations/global/latest:
summary: Latest Invocation Statistics across Services and APIs
get:
tags:
- metrics
parameters:
- name: limit
description: Number of days to get back in time. Default is 20.
schema:
type: integer
in: query
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CounterMap'
description: A map where keys are day (formatted using yyyyMMdd pattern)
and values are counter of invocations on this day
operationId: GetLatestAggregatedInvocationsStats
summary: Get aggregated invocations statistics for latest days
/metrics/tests/latest:
summary: Lastest Test results across Services and APIs
get:
tags:
- metrics
parameters:
- name: limit
description: Number of days to consider for test results to return. Default
is 7 (one week)
schema:
type: integer
in: query
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TestResultSummary'
description: Test results summary for specified <limit> last days.
operationId: GetLatestTestResults
summary: Get latest tests results
/jobs/{id}/start:
put:
tags:
- job
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
description: Started ImportJob
security:
- jwt-bearer:
- manager
- admin
operationId: StartImportJob
summary: Start an ImportJob
description: Starting an ImportJob forces it to immediatly import mock definitions
parameters:
- name: id
description: Unique identifier of ImportJob to manage
schema:
type: string
in: path
required: true
/jobs/{id}/stop:
put:
tags:
- job
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
description: Stopped ImportJob
security:
- jwt-bearer:
- manager
- admin
operationId: StopImportJob
summary: Stop an ImportJob
description: "Stopping an ImportJob desactivate it, so that it won't execute\
\ at next schedule"
parameters:
- name: id
description: Unique identifier of ImportJob to manage
schema:
type: string
in: path
required: true
/jobs/{id}/activate:
put:
tags:
- job
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ImportJob'
description: ImportJob is activated
security:
- jwt-bearer:
- manager
- admin
operationId: ActivateImportJob
summary: Activate an ImportJob
description: "Make an ImportJob active, so that it is executed"
parameters:
- name: id
description: Unique identifier of ImportJob to manage
schema:
type: string
in: path
required: true
/services/labels:
get:
tags:
- mock
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/LabelsMap'
description: "Already used labels: keys are label Keys, values are array\
\ of label Values"
security:
- jwt-bearer:
- user
operationId: GetServicesLabels
summary: Get the already used labels for Services
/artifact/download:
summary: Deals with artifacts to be downloaded and imported by Microcks.
post:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ArtifactDownload'
required: true
tags:
- job
responses:
"201":
content:
text/plain:
schema:
type: string
description: Artifact was imported and Service found
"204":
description: No url attribute found in download data
"400":
content:
text/plain:
schema:
type: string
description: Artifact content is invalid and not understood
security:
- jwt-bearer:
- manager
operationId: downloadArtifact
summary: Download an artifact
description: Ask Microcks to download an artifact and import it
/secrets/search:
get:
tags:
- config
parameters:
- name: name
description: Search using this name-like criterion
schema:
type: string
in: query
required: true
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Secret'
description: List of found Secrets (filtered according search criteria)
security:
- jwt-bearer:
- admin
operationId: SearchSecrets
summary: Search for Secrets
/artifact/upload:
summary: Deals with artifacts to be imported by Microcks.
post:
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ArtifactUpload'
examples:
Artifact upload:
value: |
POST /api/artifact/upload HTTP/1.1
Host: microcks
User-Agent: curl/7.54.0
Accept: */*
Authorization: Bearer <REDACTED>
Content-Length: 2743
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------8af8cbb56dd4bde0
--------------------------8af8cbb56dd4bde0
Content-Disposition: form-data; name="file"; filename="github.json"
Content-Type: application/octet-stream
THE ARTIFACT HERE
--------------------------8af8cbb56dd4bde0--
required: true
tags:
- job
parameters:
- name: mainArtifact
description: Flag telling if this should be considered as primary or secondary
artifact. Default to 'true'
schema:
type: boolean
in: query
required: true
responses:
"201":
content:
text/plain:
schema:
type: string
description: Artifact was imported and Service found
"204":
description: No file attribute found in uploaded data
"400":
content:
text/plain:
schema:
type: string
description: Artifact content is invalid and not understood
security:
- jwt-bearer:
- manager
operationId: uploadArtifact
summary: Upload an artifact
description: Uploads an artifact to be imported by Microcks.
components:
schemas:
TestCaseResult:
description: Companion objects for TestResult. Each TestCaseResult correspond
to a particuliar service operation / action reference by the operationName
field. TestCaseResults owns a collection of TestStepResults (one for every
request associated to service operation / action).
required:
- success
- elapsedTime
- operationName
properties:
success:
description: Flag telling if test case is a success
type: boolean
elapsedTime:
description: Elapsed time in milliseconds since the test case beginning
type: number
operationName:
description: Name of operation this test case is bound to
type: string
testStepResults:
description: Test steps associated to this test case
type: array
items:
$ref: '#/components/schemas/TestStepResult'
ServiceRef:
description: Lightweight reference of an existing Service
required:
- serviceId
- name
- version
properties:
serviceId:
description: Unique reference of a Service
type: string
name:
description: The Service name
type: string
version:
description: The Service version
type: string
SecretRef:
description: Lightweight reference for an exi
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microcks/refs/heads/main/openapi/microcks-openapi.yml