---

openapi: 3.0.2

info:

title: Microcks API v1.12

version: 1.12.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: laurent@microcks.io

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