openapi: 3.0.3
info:
title: Gravitee.io APIM - Management API - APIs
description: |-
This is the OpenAPI specification for our new version of APIM Management API.
contact:
email: team-apim@graviteesource.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 2.0.0
security:
- BasicAuth: []
- CookieAuth: []
servers:
- url: "{protocol}://{managementAPIHost}/management/v2"
description: APIM Management API v2 - Default base URL
variables:
protocol:
description: The protocol you want to use to communicate with the mAPI
default: https
enum:
- https
- http
managementAPIHost:
description: The domain of the server hosting your Management API
default: localhost:8083
- url: "{protocol}://{managementAPIHost}/management/v2/organizations/{orgId}"
description: APIM Management API v2 - Base URL to target specific organizations
variables:
protocol:
description: The protocol you want to use to communicate with the mAPI
default: https
enum:
- https
- http
managementAPIHost:
description: The domain of the server hosting your Management API
default: localhost:8083
ordId:
description: The unique ID of your organization
default: DEFAULT
tags:
- name: APIs
description: Everything about APIs
- name: API Documentation
description: Everything about API documentation pages
- name: API Members
description: Everything about API members
- name: API Plans
description: Everything about API plans
- name: API Subscriptions
description: Everything about API subscriptions
- name: Groups
description: Everything about groups
- name: Installation
description: Base resources about the installation
paths:
# APIs
/environments/{envId}/apis:
parameters:
- $ref: "#/components/parameters/envIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
- $ref: "#/components/parameters/apisSearchExpandsParam"
tags:
- APIs
summary: List APIs
description: |-
Get the list of APIs for a specific environment.
The results are paginated.
User must have the ENVIRONMENT_API[READ] permission.
operationId: listApis
responses:
"200":
$ref: "#/components/responses/ApisResponse"
default:
$ref: "#/components/responses/Error"
post:
tags:
- APIs
summary: Create an API
description: |-
⚠️ Support only v4 API for the moment. ⚠️
Create a new API.
User must have the ENVIRONMENT_API[CREATE] permission.
operationId: createApi
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateApiV4"
required: true
responses:
"201":
description: API successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/ApiV4"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/_import/definition:
parameters:
- $ref: "#/components/parameters/envIdParam"
post:
tags:
- APIs
summary: Import API definition
description: |-
⚠️ Support only v4 API for the moment. ⚠️
Create an API by importing an API definition.
This definition can be retrieved from `GET /environments/{envId}/apis/{apiId}/_export/definition`
User must have the ENVIRONMENT_API[CREATE] permission.
operationId: createApiWithImportDefinition
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ExportApiV4"
required: true
responses:
"201":
description: API successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/ApiV4"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/_search:
parameters:
- $ref: "#/components/parameters/envIdParam"
post:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
- $ref: "#/components/parameters/apiSortByParam"
- $ref: "#/components/parameters/apisGetExpandsParam"
tags:
- APIs
summary: Search APIs
description: |-
Search APIs for a specific environment.
The results are paginated and can be sorted.
User must have the ENVIRONMENT_API[READ] permission.
operationId: searchApis
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiSearchQuery"
required: true
responses:
"200":
$ref: "#/components/responses/ApisResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/_verify/paths:
parameters:
- $ref: "#/components/parameters/envIdParam"
post:
parameters:
- $ref: "#/components/parameters/envIdParam"
tags:
- APIs
summary: Verify API paths
description: |-
Verify paths before creating or updating an API.
This will check paths and hosts (depending on environment domain restrictions), and will check that path is not already used by other APIs in the environment.
The result will indicate if the paths are OK, and give the reason of the failure if they are not (path contains invalid chars, path is already covered by another API,...)
operationId: verifyPaths
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/VerifyApiPaths"
required: true
responses:
"200":
$ref: "#/components/responses/VerifyApiPathsResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
tags:
- APIs
summary: Get a specific API
description: |-
Get a specific API.
User must have at least one management (create, update, or delete) permission on the API to access it.
operationId: getApi
responses:
"200":
description: API found
content:
application/json:
schema:
$ref: "#/components/schemas/Api"
default:
$ref: "#/components/responses/Error"
put:
tags:
- APIs
summary: Update an API
description: |-
Update a V2 or a V4 API.
User must have API_DEFINITION[UPDATE] or API_GATEWAY_DEFINITION[UPDATE] permissions.
operationId: updateApi
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateApi"
required: true
responses:
"200":
description: API successfully updated
content:
application/json:
schema:
$ref: "#/components/schemas/Api"
default:
$ref: "#/components/responses/Error"
delete:
parameters:
- name: closePlans
in: query
required: false
description: |-
Set to true to force deletion by closing API plans.
⚠️ Closed plans can't be reopened and every active subscriptions will also be closed. ⚠️
schema:
type: boolean
tags:
- APIs
summary: Delete an API
description: |-
Delete a V2 or a V4 API.
User must have API_DEFINITION[DELETE] permission.
operationId: deleteApi
responses:
"204":
description: API successfully deleted
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/background:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
tags:
- APIs
summary: Get an API's background picture
description: |-
Get the API's background picture.
User must have the API_DEFINITION[READ] permission.
operationId: getApiBackground
responses:
"200":
$ref: "#/components/responses/ImageResponse"
default:
$ref: "#/components/responses/Error"
put:
tags:
- APIs
summary: Update an API's background
description: |-
Update the API's background.
User must have the API_DEFINITION[UPDATE] permission.
operationId: updateApiBackground
requestBody:
content:
image/*:
schema:
type: string
format: binary
responses:
"204":
description: API background successfully updated
default:
$ref: "#/components/responses/Error"
delete:
tags:
- APIs
summary: Delete an API's background
description: |-
Delete the API's background.
User must have the API_DEFINITION[UPDATE] permission.
operationId: deleteApiBackground
responses:
"204":
description: API background successfully deleted.
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/deployments:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Request a deployment to gateway instances
description: |-
Request a deployment for a given API.
An optional deployment label can be given to the requested deployment.
User must have the API_DEFINITION[UPDATE] permission.
operationId: createApiDeployment
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiDeployment"
responses:
"202":
description: API deployment request received
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/picture:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
tags:
- APIs
summary: Get an API's picture
description: |-
Get the API's picture.
User must have the API_DEFINITION[READ] permission.
operationId: getApiPicture
responses:
"200":
$ref: "#/components/responses/ImageResponse"
default:
$ref: "#/components/responses/Error"
put:
tags:
- APIs
summary: Update an API's picture
description: |-
Update the API's picture.
User must have the API_DEFINITION[UPDATE] permission.
operationId: updateApiPicture
requestBody:
content:
image/*:
schema:
type: string
format: binary
responses:
"204":
description: API picture successfully updated
default:
$ref: "#/components/responses/Error"
delete:
tags:
- APIs
summary: Delete an API's picture
description: |-
Delete the API's picture.
User must have the API_DEFINITION[UPDATE] permission.
operationId: deleteApiPicture
responses:
"204":
description: API picture successfully deleted.
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/_export/definition:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
tags:
- APIs
summary: Export an API
description: |-
⚠️ Support only v4 API for the moment. ⚠️
Export an API to a JSON file.
User must have at least the API_DEFINITION[READ] permission.
User should also have these permissions for specific data:
- API_DEFINITION[READ] for the API
- API_MEMBER[READ] for the API's members
- API_PLAN[READ] for the API's plans
- API_METADATA[READ] for the API's metadata
- API_DOCUMENTATION[READ] for the API's documentation pages
operationId: exportApiDefinition
responses:
"200":
description: API deployment successfully deployed
headers:
Content-Disposition:
schema:
type: string
example: attachment; filename="api-definition.json"
content:
application/json:
schema:
$ref: "#/components/schemas/ExportApiV4"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/_start:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Start an API
description: |-
Change the API's status to STARTED.
Return a 400 HTTP Error:
- when user tries to start an ARCHIVED API
- when the API is already STARTED
- when the API needs to be reviewed (only if Review feature is activated).
User must have the API_DEFINITION[UPDATE] permission.
operationId: startApi
responses:
"204":
description: API successfully started
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/_stop:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Stop an API
description: |-
Change the API's status to STOPPED.
Return a 400 HTTP Error:
- when user tries to stop an ARCHIVED API
- when the API is already STOPPED.
User must have the API_DEFINITION[UPDATE] permission.
operationId: stopApi
responses:
"204":
description: API successfully stopped
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/_transfer-ownership:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Transfer the ownership of the API
description: |-
Transfer the ownership of the API to a user, a group or an api member.
Return a 404 HTTP Error if API cannot be found.
Return a 400 HTTP Error:
- when user tries to stop an ARCHIVED API
- when the API is already STOPPED.
User must have the API_MEMBER[UPDATE] permission.
operationId: transferOwnership
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiTransferOwnership"
required: true
responses:
"204":
description: Ownership has been transfered successfully
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/_duplicate:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Duplicate an API
description: |-
Create a new API from an existing one.
User must have at least the API_DEFINITION[READ] and ENVIRONMENT_API[CREATE] permissions.
operationId: duplicateApi
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/DuplicateApiOptions"
required: true
responses:
"200":
description: API successfully duplicated
content:
application/json:
schema:
$ref: "#/components/schemas/Api"
default:
$ref: "#/components/responses/Error"
# API Reviews
/environments/{envId}/apis/{apiId}/reviews/_ask:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Ask for a review
description: |-
Ask for a review
Return a 400 HTTP Error:
- when user tries to change reviews state of an ARCHIVED API
- when user tries to change reviews state of an API already in review
User must have the API_DEFINITION[UPDATE] permission.
operationId: reviewsAsk
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiReview"
required: true
responses:
"204":
description: API successfully change review state
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/reviews/_accept:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Accept a review
description: |-
Accept a review
Return a 400 HTTP Error:
- when user tries to change reviews state of an ARCHIVED API
- when user tries to change reviews state of an API that is not in review
User must have the API_REVIEWS[UPDATE] permission.
operationId: reviewsAccept
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiReview"
required: true
responses:
"204":
description: API successfully change review state
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/reviews/_reject:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- APIs
summary: Reject a review
description: |-
Reject a review
Return a 400 HTTP Error:
- when user tries to change reviews state of an ARCHIVED API
- when user tries to change reviews state of an API that is not in review
User must have the API_REVIEWS[UPDATE] permission.
operationId: reviewsReject
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiReview"
required: true
responses:
"204":
description: API successfully change review state
default:
$ref: "#/components/responses/Error"
# API Members
/environments/{envId}/apis/{apiId}/members:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- API Members
summary: Get the API's members
description: |
List the members for a given API.
User must have the API_MEMBER[READ] permission.
operationId: listApiMembers
responses:
"200":
$ref: "#/components/responses/MembersResponse"
default:
$ref: "#/components/responses/Error"
post:
tags:
- API Members
summary: Add a member to an API.
description: |
Add a new member to an API.
Returns a 400 HTTP Error:
- when the user tries to set a member as PrimaryOwner.
User must have the API_MEMBER[CREATE] permission.
operationId: addApiMember
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/AddApiMember"
required: true
responses:
"201":
description: Member successfully added
content:
application/json:
schema:
$ref: "#/components/schemas/Member"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/members/{memberId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/memberIdParam"
put:
tags:
- API Members
summary: Updates a member for an API.
description: |
Edit a member for an API.
Returns a 400 HTTP Error:
- when the user tries to set a member as PrimaryOwner.
User must have the API_MEMBER[UPDATE] permission.
operationId: updateApiMember
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateApiMember"
required: true
responses:
"200":
description: Membership successfully edited.
content:
application/json:
schema:
$ref: "#/components/schemas/Member"
default:
$ref: "#/components/responses/Error"
delete:
tags:
- API Members
summary: Remove one API member
description: |
Remove an API member.
Returns a 400 HTTP Error:
- when the user tries to remove a PrimaryOwner.
User must have the API_MEMBER[DELETE] permission.
operationId: removeApiMember
responses:
"204":
description: API member successfully removed
default:
$ref: "#/components/responses/Error"
# API Plans
/environments/{envId}/apis/{apiId}/plans:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- name: statuses
in: query
required: false
description: List of status filters
schema:
type: array
items:
$ref: "#/components/schemas/PlanStatus"
default: ["published"]
explode: false
- name: securities
in: query
required: false
description: List of security plan type filters
schema:
type: array
items:
$ref: "#/components/schemas/PlanSecurityType"
explode: false
- name: mode
in: query
required: false
description: Mode of plan
schema:
$ref: "#/components/schemas/PlanMode"
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- API Plans
summary: List the API's plans
description: |
List plans for a given API, always filtered by a `status` and the possibility to filter by `security`.
The results are paginated.
User must have API_PLAN[READ] permissions to access endpoint.
operationId: listApiPlans
responses:
"200":
$ref: "#/components/responses/PlansResponse"
default:
$ref: "#/components/responses/Error"
post:
tags:
- API Plans
summary: Create an API's plan
description: |-
Create a new plan on a given API.
User must have the API_PLAN[CREATE] permission.
operationId: createApiPlan
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePlan"
required: true
responses:
"201":
description: Plan successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/Plan"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/plans/{planId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/planIdParam"
get:
tags:
- API Plans
summary: Get one API's plan
description: |-
Get the API's plan by its identifier.
User must have the API_PLAN[READ] permission.
operationId: getApiPlan
responses:
"200":
description: An API's plan
content:
application/json:
schema:
$ref: "#/components/schemas/Plan"
default:
$ref: "#/components/responses/Error"
put:
tags:
- API Plans
summary: Update one API's plan
description: |-
Update the API's plan.
User must have the API_PLAN[UPDATE] permission.
operationId: updateApiPlan
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdatePlan"
required: true
responses:
"200":
description: API's plan successfully updated
content:
application/json:
schema:
$ref: "#/components/schemas/Plan"
default:
$ref: "#/components/responses/Error"
delete:
tags:
- API Plans
summary: Delete one API's plan
description: |-
Delete the API's plan.
User must have the API_PLAN[DELETE] permission.
operationId: deleteApiPlan
responses:
"204":
description: API's plan successfully deleted
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/plans/{planId}/_close:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/planIdParam"
post:
tags:
- API Plans
summary: Close an API's plan
description: |-
Close the API's plan.
User must have the API_PLAN[UPDATE] permission.
operationId: closeApiPlan
responses:
"200":
description: API's plan successfully closed
content:
application/json:
schema:
$ref: "#/components/schemas/Plan"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/plans/{planId}/_deprecate:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/planIdParam"
post:
tags:
- API Plans
summary: Deprecate an API's plan
description: |-
Deprecate the API's plan.
User must have the API_PLAN[UPDATE] permission.
operationId: deprecateApiPlan
responses:
"200":
description: API's plan successfully deprecated
content:
application/json:
schema:
$ref: "#/components/schemas/Plan"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/plans/{planId}/_publish:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/planIdParam"
post:
tags:
- API Plans
summary: Publish an API's plan
description: |-
Publish the API's plan.
User must have the API_PLAN[UPDATE] permission.
operationId: publishApiPlan
responses:
"200":
description: API's plan successfully published
content:
application/json:
schema:
$ref: "#/components/schemas/Plan"
default:
$ref: "#/components/responses/Error"
# Group
/environments/{envId}/groups:
parameters:
- $ref: "#/components/parameters/envIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- Groups
summary: List of environment groups
description: |
List the groups of a given environment.
User must have the ENVIRONMENT_GROUP[READ] permission.
operationId: listGroups
responses:
"200":
$ref: "#/components/responses/GroupsResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/groups/{groupId}/members:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/groupIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- Groups
summary: List a group's members
description: |
List the members of a given group.
User must have the GROUP_MEMBER[READ] permission.
operationId: listGroupMembers
responses:
"200":
$ref: "#/components/responses/MembersResponse"
default:
$ref: "#/components/responses/Error"
# Installation
/environments:
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- Installation
summary: List all environments.
description: |-
List all environments accessible by the current user.
User must be authenticated.
operationId: getEnvironments
responses:
"200":
$ref: "#/components/responses/EnvironmentsResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
get:
tags:
- Installation
summary: Get a specific environment
description: |-
Get a specific environment.
User must be authenticated.
operationId: getEnvironmentById
responses:
"200":
description: An environment
content:
application/json:
schema:
$ref: "#/components/schemas/Environment"
default:
$ref: "#/components/responses/Error"
/license:
servers:
- url: /management/v2
description: Gravitee.io APIM - Management API -v2
get:
tags:
- Installation
summary: Get the license gravitee is running on.
description: |-
Returns the license information of the gravitee instance.
User must be authenticated.
operationId: getGraviteeLicense
responses:
"200":
description: |-
The license and its features. If there is no license, then the features will be empty.
content:
application/json:
schema:
$ref: "#/components/schemas/GraviteeLicense"
default:
$ref: "#/components/responses/Error"
/organizations/{orgId}:
servers:
- url: /management/v2
description: Gravitee.io APIM - Management API - v2
parameters:
- $ref: "#/components/parameters/orgIdParam"
get:
tags:
- Installation
summary: Get a specific organization
description: |-
Get a specific organization
User must be authenticated.
operationId: getOrganizationById
responses:
"200":
description: An organization
content:
application/json:
schema:
$ref: "#/components/schemas/Organization"
default:
$ref: "#/components/responses/Error"
# API Subscriptions
/environments/{envId}/apis/{apiId}/subscribers:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- name: name
description: |-
Name to use to filter subscribers.
Can be a part of a name.
For example, `foo` will match `foo`, `foobar` and `barfoo`.
in: query
schema:
type: string
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- API Subscriptions
summary: Get the API's subscribers
description: |
List applications that have subscribed to a given API.
The results are paginated.
User must have API_SUBSCRIPTION[READ] permissions to access endpoint.
operationId: getApiSubscribers
responses:
"200":
$ref: "#/components/responses/SubscribersResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- name: applicationIds
description: List of application ids to filter on.
in: query
explode: false
schema:
type: array
items:
type: string
- name: planIds
description: List of plan ids to filter on.
in: query
explode: false
schema:
type: array
items:
type: string
- name: statuses
in: query
required: false
description: List of status filters.
explode: false
schema:
type: array
items:
$ref: "#/components/schemas/SubscriptionStatus"
- name: apiKey
in: query
description: API Key associated to the subscription to filter on.
schema:
type: string
- name: expands
in: query
description: Expansion of data to return in subscriptions.
schema:
type: array
items:
type: string
enum:
- api
- application
- plan
- subscribedBy
explode: false
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- API Subscriptions
summary: Get the API's subscriptions
description: |
List subscriptions for a given API, always filtered by a `status` and the possibility to filter by `security`.
User must have API_SUBSCRIPTION[READ] permissions to access endpoint.
operationId: getApiSubscriptions
responses:
"200":
$ref: "#/components/responses/SubscriptionsResponse"
default:
$ref: "#/components/responses/Error"
post:
tags:
- API Subscriptions
summary: Subscribe to an API's plan
description: |-
Create a new subscription on a given API.
User must have the API_SUBSCRIPTION[CREATE] permission.
operationId: createApiSubscription
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSubscription"
required: true
responses:
"201":
description: Subscription successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/_export:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- name: applicationIds
description: List of application ids to filter on.
in: query
explode: false
schema:
type: array
items:
type: string
- name: planIds
description: List of plan ids to filter on.
in: query
explode: false
schema:
type: array
items:
type: string
- name: statuses
in: query
required: false
description: List of status filters.
explode: false
schema:
type: array
items:
$ref: "#/components/schemas/SubscriptionStatus"
- name: apiKey
in: query
description: API Key associated to the subscription to filter on.
schema:
type: string
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- API Subscriptions
summary: Export API subscriptions as CSV
description: |-
Export API subscriptions to a CSV file.
User must have the API_SUBSCRIPTION[READ] permission.
operationId: exportApiSubscriptions
responses:
"200":
description: API subscriptions successfully exported.
headers:
Content-Disposition:
schema:
type: string
example: attachment;filename="filename=subscriptions-51fdbabf-ab0c-3dc6-b3c1-77c99d96b535-1686772361126.csv"
content:
text/csv: {}
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/_verify:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
post:
tags:
- API Subscriptions
summary: Check a subscription can be created
description: |-
Check a subscription can be created with given API Key, and application.
User must have the API_SUBSCRIPTION[CREATE] permission.
operationId: verifyCreateApiSubscription
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/VerifySubscription"
required: true
responses:
"200":
description: Verification successfully performed.
content:
application/json:
schema:
$ref: "#/components/schemas/VerifySubscriptionResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
get:
tags:
- API Subscriptions
parameters:
- name: expands
in: query
description: Expansion of data to return in subscriptions.
schema:
type: array
items:
type: string
enum:
- api
- application
- plan
- subscribedBy
summary: Get one API's subscription
description: |-
Get the API's subscription by its identifier.
User must have the API_SUBSCRIPTION[READ] permission.
operationId: getApiSubscription
responses:
"200":
description: An API's subscription
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
put:
tags:
- API Subscriptions
summary: Update one API's subscription
description: |-
Update the API's subscription.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: updateApiSubscription
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateSubscription"
required: true
responses:
"200":
description: API's subscription successfully updated
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/_close:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Close one API's subscription
description: |-
Close the API's subscription.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: closeApiSubscription
responses:
"200":
description: API's subscription successfully closed
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/_pause:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Pause one API's subscription
description: |-
Pause the API's subscription.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: pauseApiSubscription
responses:
"200":
description: API's subscription successfully paused
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/_resume:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Resume a paused API's subscription
description: |-
Resume a previously paused subscription.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: resumeApiSubscription
responses:
"200":
description: API's subscription successfully resumed
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/_accept:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Accept an API subscription
description: |-
Accept an API subscription with an optional starting / ending dates and reason.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: acceptApiSubscription
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/AcceptSubscription"
required: true
responses:
"200":
description: API's subscription successfully accepted
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/_reject:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Reject an API subscription
description: |-
Reject an API subscription with an optional reason.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: rejectApiSubscription
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RejectSubscription"
required: true
responses:
"200":
description: API's subscription successfully rejected
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/_transfer:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Transfer an API subscription
description: |-
Transfer an API subscription to another plan.
The targeted plan must be published and must have the same security type. Transfer cannot be performed if general conditions apply to the targeted plan.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: transferApiSubscription
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/TransferSubscription"
required: true
responses:
"200":
description: API's subscription successfully transferred
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/api-keys:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
get:
tags:
- API Subscriptions
summary: Get subscription's API Keys
description: |-
Get the subscription API Keys.
User must have the API_SUBSCRIPTION[READ] permission.
operationId: getApiSubscriptionApiKeys
responses:
"200":
$ref: "#/components/responses/SubscriptionApiKeysResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/api-keys/_renew:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
post:
tags:
- API Subscriptions
summary: Renew the subscription API Keys.
description: |-
Renew the subscription API Key by setting an expiration date on the existing active API Keys and creating a new API Key.
The newly created API Key is returned in response.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: renewApiSubscriptionApiKeys
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RenewApiKey"
required: true
responses:
"200":
description: API's subscription API Key successfully renewed
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/api-keys/{apiKeyId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
- $ref: "#/components/parameters/apiKeyIdParam"
put:
tags:
- API Subscriptions
summary: Update a subscription API Key
description: |-
Update the subscription API Key.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: updateApiSubscriptionApiKey
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateApiKey"
required: true
responses:
"200":
description: The subscription API Key.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/api-keys/{apiKeyId}/_revoke:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
- $ref: "#/components/parameters/apiKeyIdParam"
post:
tags:
- API Subscriptions
summary: Revoke a subscription API Key
description: |-
Revoke the subscription API Key by setting the revocation date to the current date and flagging it as revoked.
A notification will be sent to the subscriber according to his portal notification options.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: revokeApiSubscriptionApiKey
responses:
"200":
description: The revoked subscription API Key.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/subscriptions/{subscriptionId}/api-keys/{apiKeyId}/_reactivate:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/subscriptionIdParam"
- $ref: "#/components/parameters/apiKeyIdParam"
post:
tags:
- API Subscriptions
summary: Reactivate subscription API Key
description: |-
Reactivate the revoked or expired subscription API Key.
User must have the API_SUBSCRIPTION[UPDATE] permission.
operationId: reactivateApiSubscriptionApiKey
responses:
"200":
description: The reactivated subscription API Key.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
default:
$ref: "#/components/responses/Error"
# Analytics - Logs
/environments/{envId}/apis/{apiId}/logs:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
- $ref: "#/components/parameters/from"
- $ref: "#/components/parameters/to"
- $ref: "#/components/parameters/applicationIds"
- $ref: "#/components/parameters/planIds"
- $ref: "#/components/parameters/methods"
tags:
- Analytics - Logs
summary: Get API logs
description: |-
Get API logs.
User must have the API_LOG[READ] permission.
operationId: getApiLogs
responses:
"200":
$ref: "#/components/responses/ApiLogsResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/logs/{requestId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/requestIdParam"
get:
tags:
- Analytics - Logs
summary: Get API log for a request
description: |-
Get API log for a request.
User must have the API_LOG[READ] permission.
operationId: getApiLog
responses:
"200":
$ref: "#/components/responses/ApiLogResponse"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/logs/{requestId}/messages:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/requestIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- Analytics - Logs
summary: Get API Messages logs
description: |-
Get API Messages logs.
User must have the API_LOG[READ] permission.
operationId: getApiMessageLogs
responses:
"200":
$ref: "#/components/responses/ApiMessageLogsResponse"
default:
$ref: "#/components/responses/Error"
# API Documentation
/environments/{envId}/apis/{apiId}/pages:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
get:
parameters:
- $ref: "#/components/parameters/parentId"
tags:
- API Documentation
summary: Get API documentation pages
description: |-
Get API documentation pages.
When no parentId is specified, returns all the pages of the API.
When parentId is specified (either ID of a folder, or 'ROOT'), only the pages with the given parent are returned,
and the breadcrumb of the specified folder is added to the response.
User must have the API_DOCUMENTATION[READ] permission.
operationId: getApiPages
responses:
"200":
$ref: "#/components/responses/ApiDocumentationPagesResponse"
default:
$ref: "#/components/responses/Error"
post:
tags:
- API Documentation
summary: Create API documentation page
description: |-
Create API documentation. The result will be the created page or folder.
Only MARKDOWN and FOLDER types are supported.
User must have the API_DOCUMENTATION[CREATE] permission.
operationId: createDocumentationPage
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateDocumentation"
required: true
responses:
"201":
description: Created API Documentation
content:
application/json:
schema:
$ref: "#/components/schemas/Page"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/pages/{pageId}:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/pageIdParam"
get:
tags:
- API Documentation
summary: Get API Documentation Page
description: |-
Get API Documentation Page by ID.
User must have the API_DOCUMENTATION[READ] permission.
operationId: getApiPage
responses:
"200":
description: API Documentation Page
content:
application/json:
schema:
$ref: "#/components/schemas/Page"
default:
$ref: "#/components/responses/Error"
put:
tags:
- API Documentation
summary: Update API documentation page
description: |-
Update API documentation. The result will be the updated documentation.
Only MARKDOWN and FOLDER types are supported.
User must have the API_DOCUMENTATION[CREATE] permission.
operationId: updateDocumentationPage
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateDocumentation"
required: true
responses:
"200":
description: API Documentation Updated
content:
application/json:
schema:
$ref: "#/components/schemas/Page"
default:
$ref: "#/components/responses/Error"
delete:
tags:
- API Documentation
summary: Delete API documentation page
description: |-
Delete API documentation page.
A FOLDER will be deleted only if it is empty.
operationId: deleteDocumentationPage
responses:
"204":
description: API Documentation page deleted
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/pages/{pageId}/_publish:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/pageIdParam"
post:
tags:
- API Documentation
summary: Publish API Documentation Page
description: |-
Publish API Documentation Page. Returns the published page.
User must have the API_DOCUMENTATION[UPDATE] permission.
operationId: publishDocumentationPage
responses:
"200":
description: API Documentation Page
content:
application/json:
schema:
$ref: "#/components/schemas/Page"
default:
$ref: "#/components/responses/Error"
/environments/{envId}/apis/{apiId}/pages/{pageId}/_unpublish:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/apiIdParam"
- $ref: "#/components/parameters/pageIdParam"
post:
tags:
- API Documentation
summary: Unpublish API Documentation Page
description: |-
Unpublish API Documentation Page. Returns the unpublished page.
User must have the API_DOCUMENTATION[UPDATE] permission.
operationId: unpublishDocumentationPage
responses:
"200":
description: API Documentation Page
content:
application/json:
schema:
$ref: "#/components/schemas/Page"
default:
$ref: "#/components/responses/Error"
components:
schemas:
GraviteeLicense:
type: object
properties:
tier:
type: string
description: The tier gravitee is running on.
example: "tier-planet"
packs:
type: array
items:
type: string
description: The packs included in the tier gravitee is running on.
example:
- "pack-observability"
- "pack-event-native"
features:
type: array
items:
type: string
description: The features included in the tier gravitee is running on.
example:
- feature-debug-mode
- feature-datadog-reporter
Analytics:
type: object
properties:
enabled:
type: boolean
description: Whether or not analytics is enabled.
default: true
sampling:
$ref: "#/components/schemas/Sampling"
logging:
$ref: "#/components/schemas/LoggingV4"
Api:
oneOf:
- $ref: "#/components/schemas/ApiV1"
- $ref: "#/components/schemas/ApiV2"
- $ref: "#/components/schemas/ApiV4"
discriminator:
propertyName: definitionVersion
mapping:
V1: "#/components/schemas/ApiV1"
V2: "#/components/schemas/ApiV2"
V4: "#/components/schemas/ApiV4"
BaseApi:
type: object
properties:
id:
type: string
description: API's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: API's name. Duplicate names can exists.
example: My Api
description:
type: string
description: API's description. A short description of your API.
example: I can use many characters to describe this API.
GenericApi:
type: object
allOf:
- $ref: "#/components/schemas/BaseApi"
- properties:
crossId:
type: string
description: API's crossId. Identifies API across environments.
example: df83b2a4-cc3e-3f80-9f0d-c138c106c076
apiVersion:
type: string
description: API's version. It's a simple string only used in the portal.
example: v1.0
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
deployedAt:
type: string
format: date-time
description: The last date (as timestamp) when the API was deployed.
example: 1581256457163
createdAt:
type: string
format: date-time
description: The date (as timestamp) when the API was created.
example: 1581256457163
updatedAt:
type: string
format: date-time
description: The last date (as timestamp) when the API was updated.
example: 1581256457163
disableMembershipNotifications:
type: boolean
description: Disable membership notifications.
default: false
# metadata ==> dedicated resource
groups:
type: array
description: API's groups. Used to add team in your API.
example:
- MY_GROUP1
- MY_GROUP2
items:
type: string
state:
type: string
description: The state of the API regarding the gateway(s).
example: STARTED
enum:
- CLOSED
- INITIALIZED
- STARTED
- STOPPED
- STOPPING
deploymentState:
type: string
description: The deployment state of the API regarding the gateway(s).
example: DEPLOYED
enum:
- NEED_REDEPLOY
- DEPLOYED
visibility:
$ref: "#/components/schemas/Visibility"
labels:
type: array
description: The free list of labels associated with this API.
example:
- json
- read_only
- awesome
items:
type: string
lifecycleState:
$ref: "#/components/schemas/ApiLifecycleState"
tags:
type: array
description: The list of sharding tags associated with this API.
example:
- public
- private
items:
type: string
primaryOwner:
$ref: "#/components/schemas/PrimaryOwner"
categories:
type: array
description: The list of category keys associated with this API.
example:
- health
- media
items:
type: string
definitionContext:
$ref: "#/components/schemas/DefinitionContext"
workflowState:
$ref: "#/components/schemas/ApiWorkflowState"
responseTemplates:
type: object
additionalProperties:
type: object
additionalProperties:
$ref: "#/components/schemas/ResponseTemplate"
# plans ==> dedicated resource
resources:
type: array
items:
$ref: "#/components/schemas/Resource"
properties:
type: array
items:
$ref: "#/components/schemas/Property"
_links:
$ref: "#/components/schemas/ApiLinks"
required:
- definitionVersion
discriminator:
propertyName: definitionVersion
mapping:
V1: "#/components/schemas/ApiV1"
V2: "#/components/schemas/ApiV2"
V4: "#/components/schemas/ApiV4"
ApiV1:
type: object
title: "ApiV1"
allOf:
- $ref: "#/components/schemas/GenericApi"
- properties:
environmentId:
type: string
description: The environment's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
executionMode:
$ref: "#/components/schemas/ExecutionMode"
contextPath:
type: string
description: The context path of the API.
example: /my-api
proxy:
$ref: "#/components/schemas/Proxy"
paths:
type: object
additionalProperties:
type: array
description: a map where you can associate a path to a configuration (the
policies configuration)
items:
$ref: "#/components/schemas/Rule"
services:
$ref: "#/components/schemas/ApiServicesV2"
pathMappings:
type: array
description: The list of path mappings associated with this API.
items:
type: string
entrypoints:
type: array
description: The list of entrypoints associated with this API.
items:
$ref: "#/components/schemas/ApiEntrypoint"
ApiV2:
type: object
title: "ApiV2"
allOf:
- $ref: "#/components/schemas/GenericApi"
- properties:
environmentId:
type: string
description: The environment's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
executionMode:
$ref: "#/components/schemas/ExecutionMode"
contextPath:
type: string
description: The context path of the API.
example: /my-api
proxy:
$ref: "#/components/schemas/Proxy"
flowMode:
$ref: "#/components/schemas/FlowMode"
flows:
type: array
description: The list of flows associated with this API.
items:
$ref: "#/components/schemas/FlowV2"
services:
$ref: "#/components/schemas/ApiServicesV2"
pathMappings:
type: array
description: The list of path mappings associated with this API.
items:
type: string
entrypoints:
type: array
description: The list of entrypoints associated with this API.
items:
$ref: "#/components/schemas/ApiEntrypoint"
ApiV4:
type: object
title: "ApiV4"
allOf:
- $ref: "#/components/schemas/GenericApi"
- properties:
type:
$ref: "#/components/schemas/ApiType"
listeners:
type: array
description: The list of listeners associated with this API.
items:
$ref: "#/components/schemas/Listener"
endpointGroups:
type: array
items:
$ref: "#/components/schemas/EndpointGroupV4"
analytics:
$ref: "#/components/schemas/Analytics"
flowExecution:
$ref: "#/components/schemas/FlowExecution"
flows:
type: array
items:
$ref: "#/components/schemas/FlowV4"
services:
$ref: "#/components/schemas/ApiServices"
ApiLinks:
type: object
properties:
pictureUrl:
type: string
description: The URL to the API's picture.
example: https://gravitee.example.com/management/v2/environments/00f8c9e7-78fc-4907-b8c9-e778fc790750/apis/6c530064-0b2c-4004-9300-640b2ce0047b/picture
backgroundUrl:
type: string
description: The URL to the API's background.
example: https://gravitee.example.com/management/v2/environments/00f8c9e7-78fc-4907-b8c9-e778fc790750/apis/6c530064-0b2c-4004-9300-640b2ce0047b/background
ApiTransferOwnership:
type: object
properties:
userId:
type: string
description: The new primary owner ID (user's technical identifier). Can be null if userReference is defined.
userReference:
type: string
description: The new primary owner reference (user's reference provided by an identity provider). Can be null if userId is defined.
userType:
$ref: "#/components/schemas/MembershipMemberType"
poRole:
type: string
description: The name of the role that will be assigned to the current primary owner after the transfer.
CreateApi:
oneOf:
- $ref: "#/components/schemas/CreateApiV2"
- $ref: "#/components/schemas/CreateApiV4"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/CreateApiV2"
V4: "#/components/schemas/CreateApiV4"
CreateGenericApi:
type: object
properties:
name:
type: string
description: API's name. Duplicate names can exists.
example: My Api
minLength: 1
apiVersion:
type: string
description: API's version. It's a simple string only used in the portal.
example: v1.0
minLength: 1
description:
type: string
description: API's description. A short description of your API.
example: I can use many characters to describe this API.
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
groups:
type: array
description: API's groups. Used to add team in your API.
example:
- MY_GROUP1
- MY_GROUP2
items:
type: string
required: [name, apiVersion, definitionVersion]
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/CreateApiV2"
V4: "#/components/schemas/CreateApiV4"
CreateApiV2:
type: object
title: "CreateApiV2"
allOf:
- $ref: "#/components/schemas/CreateGenericApi"
- properties:
contextPath:
type: string
description: API's context path. It's the base path of your API.
example: /my-api
minLength: 3
endpoint:
type: string
description: API's endpoint. It's the base URL of your API.
example: https://my-api.mycompany.com
minLength: 1
flows:
type: array
items:
$ref: "#/components/schemas/FlowV2"
flowMode:
$ref: "#/components/schemas/FlowMode"
required: [contextPath, endpoint]
CreateApiV4:
type: object
title: "CreateApiV4"
allOf:
- $ref: "#/components/schemas/CreateGenericApi"
- properties:
type:
$ref: "#/components/schemas/ApiType"
tags:
type: array
description: The list of sharding tags associated with this API.
example:
- public
- private
items:
type: string
uniqueItems: true
listeners:
type: array
description: The list of listeners associated with this API.
items:
$ref: "#/components/schemas/Listener"
minItems: 1
endpointGroups:
type: array
items:
$ref: "#/components/schemas/EndpointGroupV4"
minItems: 1
analytics:
$ref: "#/components/schemas/Analytics"
flowExecution:
$ref: "#/components/schemas/FlowExecution"
flows:
type: array
items:
$ref: "#/components/schemas/FlowV4"
required: [listeners, endpointGroups, type]
DuplicateApiOptions:
type: object
properties:
contextPath:
type: string
description: The context path of the duplicated API.
version:
type: string
description: The version of the duplicated API. If it is not defined, the value of the source API is used.
filteredFields:
type: array
description: The list of API fields that can be excluded to create the new API.
items:
type: string
enum:
- GROUPS
- PLANS
- MEMBERS
- PAGES
uniqueItems: true
required:
- contextPath
- filteredFields
ExportApiV4:
type: object
properties:
api:
$ref: "#/components/schemas/ApiV4"
members:
type: array
description: The list of members associated with this API.
items:
$ref: "#/components/schemas/Member"
uniqueItems: true
metadata:
type: array
description: The list of API's metadata.
items:
$ref: "#/components/schemas/Metadata"
uniqueItems: true
pages:
type: array
description: The list of pages associated with this API.
items:
$ref: "#/components/schemas/Page"
uniqueItems: true
plans:
type: array
description: The list of plans associated with this API.
items:
$ref: "#/components/schemas/PlanV4"
uniqueItems: true
apiPicture:
type: string
format: base64
description: The API's picture.
apiBackground:
type: string
format: base64
description: The API's background.
apiMedia:
type: array
description: The list of API's media used in pages.
items:
$ref: "#/components/schemas/Media"
UpdateApi:
oneOf:
- $ref: "#/components/schemas/UpdateApiV2"
- $ref: "#/components/schemas/UpdateApiV4"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/UpdateApiV2"
V4: "#/components/schemas/UpdateApiV4"
UpdateGenericApi:
type: object
properties:
name:
type: string
description: API's name. Duplicate names can exists.
example: My Api
minLength: 1
apiVersion:
type: string
description: API's version. It's a simple string only used in the portal.
example: v1.0
minLength: 1
description:
type: string
description: API's description. A short description of your API.
example: I can use many characters to describe this API.
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
groups:
type: array
description: API's groups. Used to add team in your API.
example:
- MY_GROUP1
- MY_GROUP2
items:
type: string
tags:
type: array
description: The list of sharding tags associated with this API.
example:
- public
- private
items:
type: string
resources:
type: array
items:
$ref: "#/components/schemas/Resource"
responseTemplates:
type: object
additionalProperties:
type: object
additionalProperties:
$ref: "#/components/schemas/ResponseTemplate"
visibility:
$ref: "#/components/schemas/Visibility"
categories:
type: array
description: The list of category ids or keys associated with this API.
example:
- 6c530064-0b2c-4004-9300-640b2ce0047b
- 12559b64-0b2c-4004-9300-640b2ce0047b
- media
- health
items:
type: string
labels:
type: array
description: The free list of labels associated with this API.
example:
- json
- read_only
- awesome
items:
type: string
lifecycleState:
$ref: "#/components/schemas/ApiLifecycleState"
disableMembershipNotifications:
type: boolean
description: Disable membership notifications.
default: false
properties:
type: array
items:
$ref: "#/components/schemas/Property"
required: [name, apiVersion, definitionVersion]
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/UpdateApiV2"
V4: "#/components/schemas/UpdateApiV4"
UpdateApiV2:
type: object
title: "UpdateApiV2"
allOf:
- $ref: "#/components/schemas/UpdateGenericApi"
- properties:
proxy:
$ref: "#/components/schemas/Proxy"
flowMode:
$ref: "#/components/schemas/FlowMode"
flows:
type: array
description: The list of flows associated with this API.
items:
$ref: "#/components/schemas/FlowV2"
services:
$ref: "#/components/schemas/ApiServicesV2"
pathMappings:
type: array
description: The list of path mappings associated with this API.
items:
type: string
executionMode:
$ref: "#/components/schemas/ExecutionMode"
required: [contextPath, endpoint]
UpdateApiV4:
type: object
title: "UpdateApiV4"
allOf:
- $ref: "#/components/schemas/UpdateGenericApi"
- properties:
type:
$ref: "#/components/schemas/ApiType"
listeners:
type: array
description: The list of listeners associated with this API.
items:
$ref: "#/components/schemas/Listener"
minItems: 1
endpointGroups:
type: array
items:
$ref: "#/components/schemas/EndpointGroupV4"
minItems: 1
analytics:
$ref: "#/components/schemas/Analytics"
flowExecution:
$ref: "#/components/schemas/FlowExecution"
flows:
type: array
items:
$ref: "#/components/schemas/FlowV4"
services:
$ref: "#/components/schemas/ApiServices"
required: [listeners, endpointGroups, type]
ApiDeployment:
type: object
properties:
deploymentLabel:
type: string
description: Label for an Api deployment. Duplicate names can exists.
example: My deployment
maxLength: 32
ApiLifecycleState:
type: string
description: The status of the API regarding the console.
example: CREATED
enum:
- ARCHIVED
- CREATED
- DEPRECATED
- PUBLISHED
- UNPUBLISHED
ApiServices:
type: object
properties:
dynamicProperty:
$ref: "#/components/schemas/ServiceV4"
ApiSearchQuery:
type: object
properties:
query:
type: string
description: The query to search for.
example: my api
ids:
type: array
items:
type: string
description: List of ids to find
example:
- apiId-1
- apiId-2
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
ApiType:
type: string
description: API's type.
example: MESSAGE
enum:
- MESSAGE
- PROXY
Visibility:
type: string
description: The visibility of the resource regarding the portal.
example: PUBLIC
enum:
- PUBLIC
- PRIVATE
ApiWorkflowState:
type: string
description: The status of the API regarding the review feature.
example: DRAFT
enum:
- DRAFT
- IN_REVIEW
- REQUEST_FOR_CHANGES
- REVIEW_OK
readOnly: true
ChannelSelector:
type: object
title: "ChannelSelector"
required:
- type
- channel
- channelOperator
allOf:
- $ref: "#/components/schemas/BaseSelector"
- type: object
properties:
operations:
type: array
description: The list of operations associated with this channel selector.
items:
type: string
description: The operation associated with this channel selector.
enum:
- PUBLISH
- SUBSCRIBE
uniqueItems: true
channel:
type: string
description: The channel of the selector
example: /my/channel
default: /
channelOperator:
$ref: "#/components/schemas/Operator"
entrypoints:
type: array
items:
type: string
uniqueItems: true
ConditionSelector:
type: object
title: "ConditionSelector"
required:
- type
- condition
allOf:
- $ref: "#/components/schemas/BaseSelector"
- type: object
properties:
condition:
type: string
description: The condition of the selector
example: ${#jsonPath(payload, '$.myField') == 'myValue'}
Cors:
type: object
properties:
allowCredentials:
type: boolean
allowHeaders:
uniqueItems: true
type: array
items:
type: string
allowMethods:
uniqueItems: true
type: array
items:
type: string
allowOrigin:
uniqueItems: true
type: array
items:
type: string
enabled:
type: boolean
exposeHeaders:
uniqueItems: true
type: array
items:
type: string
maxAge:
type: integer
format: int32
default: -1
runPolicies:
type: boolean
Dlq:
type: object
properties:
endpoint:
type: string
description: The endpoint of the DLQ.
DefinitionContext:
type: object
description: the context where the api definition was created
properties:
origin:
type: string
description: The origin of the API.
example: MANAGEMENT
enum:
- MANAGEMENT
- KUBERNETES
mode:
deprecated: true
type: string
description: |-
The mode of the API.
fully_managed: Mode indicating the api is fully managed by the origin and so, only the origin should be able to manage the api.
api_definition_only: Mode indicating the api is partially managed by the origin and so, only the origin should be able to manage the api definition part of the api. This includes everything regarding the definition of the apis (plans, flows, metadata, ...)
example: FULLY_MANAGED
enum:
- FULLY_MANAGED
- API_DEFINITION_ONLY
syncFrom:
type: string
description: |-
syncFrom stands for where the Gateway should source the API definition from.
If the value is KUBERNETES, then the gateway will sync the definition by listening to changes
issued on a kubernetes config map. If the value is MANAGEMENT, then the gateway will sync
the definition using the same datastore as APIM.
Defining MANAGEMENT as source for sync is useful e.g. when a single operator should operate
on gateways deployed on multiple kubernetes clusters.
example: MANAGEMENT
enum:
- MANAGEMENT
- KUBERNETES
readOnly: true
DefinitionVersion:
type: string
description: API's gravitee definition version.
example: V4
enum:
- V1
- V2
- V4
EndpointV4:
type: object
properties:
name:
type: string
description: The name of the endpoint
example: default-endpoint
nullable: false
type:
type: string
description: The type of the endpoint
example: mock
nullable: false
weight:
type: integer
format: int32
description: The weight of the endpoint
default: 1
inheritConfiguration:
type: boolean
description: Is the configuration of the endpoint inherited from the endpoint group it belongs to.
default: false
configuration:
type: object
sharedConfigurationOverride:
type: object
services:
$ref: "#/components/schemas/EndpointServices"
secondary:
type: boolean
description: Is the endpoint a secondary endpoint.
default: false
tenants:
type: array
description: The list of tenants associated to the endpoint.
items:
type: string
required:
- type
EndpointGroupV4:
type: object
properties:
name:
type: string
description: The name of the endpoint group
example: default-endpoint-group
nullable: false
type:
type: string
description: The type of the endpoint group
example: default
nullable: false
loadBalancer:
$ref: "#/components/schemas/LoadBalancer"
sharedConfiguration:
type: object
endpoints:
type: array
items:
$ref: "#/components/schemas/EndpointV4"
services:
$ref: "#/components/schemas/EndpointGroupServices"
required:
- type
EndpointGroupServices:
type: object
properties:
discovery:
$ref: "#/components/schemas/ServiceV4"
healthCheck:
$ref: "#/components/schemas/ServiceV4"
EndpointServices:
type: object
properties:
healthCheck:
$ref: "#/components/schemas/ServiceV4"
Entrypoint:
type: object
required:
- type
properties:
type:
type: string
description: The type of the entrypoint
example: http-get
nullable: false
qos:
$ref: "#/components/schemas/Qos"
dlq:
$ref: "#/components/schemas/Dlq"
configuration:
type: object
Environment:
type: object
properties:
id:
type: string
description: Environment's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Environment's name. Duplicate names can exists.
example: My Environment
minLength: 1
description:
type: string
description: Environment's description. A short description of your Environment.
example: I can use many characters to describe this Environment.
minLength: 1
Error:
type: object
properties:
httpStatus:
type: integer
format: int32
description: The error code
example: 400
message:
type: string
description: The error message
example: Bad request
technicalCode:
type: string
description: A technical code to identify the error
example: invalid.import.definition
parameters:
type: object
description: A map of parameters to be used in the error message
additionalProperties:
type: string
details:
type: array
description: A list of details about the error
items:
type: object
properties:
message:
type: string
description: The error message
example: Bad request
location:
type: string
description: The json path of the field in error.
example: updateApi.properties[0].key
invalidValue:
description: The invalid value.
FlowV4:
type: object
properties:
id:
type: string
description: Flow's uuid.
example: 4e6abbd2-c0c6-462d-be9e-6371209af34b
name:
type: string
description: Flow's name.
example: My Flow
enabled:
type: boolean
description: Is the flow enabled.
default: true
selectors:
type: array
items:
$ref: "#/components/schemas/Selector"
request:
type: array
items:
$ref: "#/components/schemas/StepV4"
response:
type: array
items:
$ref: "#/components/schemas/StepV4"
subscribe:
type: array
items:
$ref: "#/components/schemas/StepV4"
publish:
type: array
items:
$ref: "#/components/schemas/StepV4"
tags:
type: array
items:
type: string
description: Flow's tags.
example:
- tag1
- tag2
uniqueItems: true
FlowExecution:
type: object
properties:
mode:
$ref: "#/components/schemas/FlowMode"
matchRequired:
type: boolean
description: Is the flow execution match required.
default: false
FlowMode:
type: string
description: API's flow mode.
example: BEST_MATCH
default: DEFAULT
enum:
- BEST_MATCH
- DEFAULT
HttpListener:
type: object
title: "HttpListener"
required:
- type
allOf:
- $ref: "#/components/schemas/BaseListener"
- type: object
properties:
paths:
type: array
minItems: 1
items:
$ref: "#/components/schemas/PathV4"
pathMappings:
type: array
items:
type: string
cors:
$ref: "#/components/schemas/Cors"
HttpMethod:
type: string
description: The method of the selector
example: GET
enum:
- CONNECT
- DELETE
- GET
- HEAD
- OPTIONS
- PATCH
- POST
- PUT
- TRACE
- OTHER
HttpSelector:
type: object
title: "HttpSelector"
required:
- type
- path
- pathOperator
allOf:
- $ref: "#/components/schemas/BaseSelector"
- type: object
properties:
path:
type: string
description: The path of the selector
example: /my/path
default: /
pathOperator:
$ref: "#/components/schemas/Operator"
methods:
type: array
items:
$ref: "#/components/schemas/HttpMethod"
uniqueItems: true
Links:
description: List of links for pagination
properties:
self:
type: string
description: Link to current resource
first:
type: string
description: In a paginated response, link to the first page
last:
type: string
description: In a paginated response, link to the last page
previous:
type: string
description: In a paginated response, link to the previous page. Maybe null if current is the first page
next:
type: string
description: In a paginated response, link to the next page. Maybe null if current is the last page
Listener:
oneOf:
- $ref: "#/components/schemas/HttpListener"
- $ref: "#/components/schemas/SubscriptionListener"
- $ref: "#/components/schemas/TcpListener"
discriminator:
propertyName: type
mapping:
HTTP: "#/components/schemas/HttpListener"
TCP: "#/components/schemas/TcpListener"
SUBSCRIPTION: "#/components/schemas/SubscriptionListener"
BaseListener:
type: object
required:
- type
properties:
type:
$ref: "#/components/schemas/ListenerType"
entrypoints:
type: array
minItems: 1
items:
$ref: "#/components/schemas/Entrypoint"
servers:
type: array
items:
type: string
discriminator:
propertyName: type
mapping:
HTTP: "#/components/schemas/HttpListener"
TCP: "#/components/schemas/TcpListener"
SUBSCRIPTION: "#/components/schemas/SubscriptionListener"
ListenerType:
type: string
description: Listener type.
example: HTTP
enum:
- HTTP
- SUBSCRIPTION
- TCP
LoadBalancer:
type: object
properties:
type:
type: string
description: Load balancer type.
example: ROUND_ROBIN
default: ROUND_ROBIN
enum:
- RANDOM
- ROUND_ROBIN
- WEIGHTED_RANDOM
- WEIGHTED_ROUND_ROBIN
LoggingV4:
type: object
properties:
condition:
type: string
messageCondition:
type: string
content:
$ref: "#/components/schemas/LoggingContentV4"
phase:
$ref: "#/components/schemas/LoggingPhase"
mode:
$ref: "#/components/schemas/LoggingModeV4"
LoggingContentV4:
type: object
properties:
headers:
type: boolean
messageHeaders:
type: boolean
payload:
type: boolean
messagePayload:
type: boolean
messageMetadata:
type: boolean
LoggingModeV4:
type: object
properties:
endpoint:
type: boolean
entrypoint:
type: boolean
LoggingPhase:
type: object
properties:
request:
type: boolean
response:
type: boolean
MetadataResponse:
description: Generic object to handle additional information about an entity. Can also be used for pagination data.
type: object
MoreInformation:
type: object
properties:
description:
type: string
description: Plugin's description.
example: Let your consumers send synchronous, on-demand requests for events via a standard HTTP GET requests. Use a standard HTTP proxy to mediate between client applications as data consumers and event brokers such as Kafka.
documentationUrl:
type: string
description: Plugin's documentation URL.
example: https://documentation.gravitee.io
schemaImg:
type: string
description: Plugin's schema image as base64.
format: base64
example: data:image/png;base64,aFDqfda
Operator:
type: string
description: The path operator of the selector
example: EQUALS
default: STARTS_WITH
enum:
- EQUALS
- STARTS_WITH
Organization:
type: object
properties:
id:
type: string
description: Organization's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Organization's name. Duplicate names can exists.
example: My Organization
minLength: 1
description:
type: string
description: Organization's description. A short description of your Organization.
example: I can use many characters to describe this Organization.
minLength: 1
Pagination:
description: Generic object to handle pagination data.
type: object
properties:
page:
type: integer
description: The current page.
perPage:
type: integer
description: The number of items requested per page.
pageCount:
type: integer
description: The total number of pages.
pageItemsCount:
type: integer
description: The number of items for the current page.
totalCount:
type: integer
format: int64
description: The total number of items.
Path:
type: object
properties:
host:
type: string
path:
type: string
default: "/"
overrideAccess:
type: boolean
default: false
PathV4:
type: object
properties:
host:
type: string
path:
type: string
default: "/"
overrideAccess:
type: boolean
default: false
ApiReview:
type: object
properties:
message:
type: string
description: Optional message from the API reviewer.
BasePlan:
type: object
properties:
id:
type: string
description: Plan's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Plan's name. Duplicate names can exists.
example: My Api plan
description:
type: string
description: Plan's description. A short description of your plan.
example: I can use a hundred characters to describe this plan.
apiId:
type: string
description: Id of the API owning the plan.
example: 6c530064-0b2c-4004-9300-640b2ce0047b
security:
$ref: "#/components/schemas/PlanSecurity"
GenericPlan:
type: object
allOf:
- $ref: "#/components/schemas/BasePlan"
- properties:
characteristics:
type: array
items:
type: string
closedAt:
type: string
format: date-time
description: The datetime when the plan was closed.
example: 2023-05-25T12:40:46.184Z
commentMessage:
type: string
description: A message from the API Publisher that is displayed to the consumer at subscription time.
example: Explain why you want to subscribe.
commentRequired:
type: boolean
description: A flag indicating if the consumer has to write a "consumer message" or if he/she can leave the field blank.
createdAt:
type: string
format: date-time
description: The last datetime when the plan was created.
example: 2023-05-25T12:40:46.184Z
crossId:
type: string
description: Plan's crossId. Identifies plan across environments.
example: df83b2a4-cc3e-3f80-9f0d-c138c106c076
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
description:
type: string
description: Plan's description. A short description of your plan.
example: I can use a hundred characters to describe this plan.
excludedGroups:
type: array
description: Groups of users which are not allowed to subscribe to this plan.
example:
- MY_GROUP1
- MY_GROUP2
items:
type: string
generalConditions:
type: string
order:
type: integer
publishedAt:
type: string
format: date-time
description: The last datetime when the plan was published.
example: 2023-05-25T12:40:46.184Z
selectionRule:
type: string
status:
$ref: "#/components/schemas/PlanStatus"
tags:
type: array
description: The list of sharding tags associated with this plan.
example:
- public
- private
items:
type: string
type:
$ref: "#/components/schemas/PlanType"
updatedAt:
type: string
format: date-time
description: The last datetime when the plan was updated.
example: 2023-05-25T12:40:46.184Z
validation:
$ref: "#/components/schemas/PlanValidation"
required:
- definitionVersion
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/PlanV2"
V4: "#/components/schemas/PlanV4"
PlanV4:
type: object
title: "PlanV4"
allOf:
- $ref: "#/components/schemas/GenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV4"
mode:
$ref: "#/components/schemas/PlanMode"
Plan:
oneOf:
- $ref: "#/components/schemas/PlanV2"
- $ref: "#/components/schemas/PlanV4"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/PlanV2"
V4: "#/components/schemas/PlanV4"
PlanSecurity:
type: object
properties:
type:
$ref: "#/components/schemas/PlanSecurityType"
configuration:
type: object
required:
- type
PlanSecurityType:
type: string
description: Plan security type.
example: KEY_LESS
enum:
- KEY_LESS
- API_KEY
- OAUTH2
- JWT
PlanStatus:
type: string
description: Plan status.
example: STAGING
enum:
- STAGING
- PUBLISHED
- DEPRECATED
- CLOSED
PlanType:
type: string
description: Plan type.
example: API
enum:
- API
- CATALOG
PlanValidation:
type: string
description: Plan validation type.
example: AUTO
enum:
- AUTO
- MANUAL
CreatePlan:
oneOf:
- $ref: "#/components/schemas/CreatePlanV2"
- $ref: "#/components/schemas/CreatePlanV4"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/CreatePlanV2"
V4: "#/components/schemas/CreatePlanV4"
CreateGenericPlan:
type: object
properties:
crossId:
type: string
description: Plan's crossId. Identifies plan across environments.
example: df83b2a4-cc3e-3f80-9f0d-c138c106c076
characteristics:
type: array
items:
type: string
commentMessage:
type: string
description: A message from the API Publisher that is displayed to the consumer at subscription time.
example: Explain why you want to subscribe.
commentRequired:
type: boolean
description: A flag indicating if the consumer has to write a "consumer message" or if he/she can leave the field blank.
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
description:
type: string
description: Plan's description. A short description of your Plan.
example: I can use a hundred characters to describe this plan.
excludedGroups:
type: array
description: Groups of users which are not allowed to subscribe to this plan.
example:
- MY_GROUP1
- MY_GROUP2
items:
type: string
generalConditions:
type: string
description: This field contains the UUID of the documentation page that is used as General Conditions.
example: 4e3de652-2301-48ba-bde6-522301e8ba3a
name:
type: string
description: Plan's name. Duplicate names can exists.
example: My Api plan
order:
type: integer
description: Simple order that could be used by a front end to display plans in a certain order. To highlight a plan on the portal for instance.
example: 0
security:
$ref: "#/components/schemas/PlanSecurity"
selectionRule:
type: string
description: An optional EL expression that will be evaluated at request time to select this plan.
tags:
type: array
description: The list of sharding tags associated with this plan.
example:
- public
- private
items:
type: string
validation:
$ref: "#/components/schemas/PlanValidation"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/CreatePlanV2"
V4: "#/components/schemas/CreatePlanV4"
required:
- definitionVersion
CreatePlanV2:
type: object
title: "CreatePlanV2"
allOf:
- $ref: "#/components/schemas/CreateGenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV2"
CreatePlanV4:
type: object
title: "CreatePlanV4"
allOf:
- $ref: "#/components/schemas/CreateGenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV4"
mode:
$ref: "#/components/schemas/PlanMode"
PlanMode:
type: string
description: The behavioural mode of the Plan (Standard for classical plan, Push for subscription plan).
example: STANDARD
enum:
- STANDARD
- PUSH
UpdatePlan:
oneOf:
- $ref: "#/components/schemas/UpdatePlanV2"
- $ref: "#/components/schemas/UpdatePlanV4"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/UpdatePlanV2"
V4: "#/components/schemas/UpdatePlanV4"
UpdateGenericPlan:
type: object
properties:
crossId:
type: string
description: Plan's crossId. Identifies plan across environments.
example: df83b2a4-cc3e-3f80-9f0d-c138c106c076
characteristics:
type: array
items:
type: string
commentMessage:
type: string
description: A message from the API Publisher that is displayed to the consumer at subscription time.
example: Explain why you want to subscribe.
commentRequired:
type: boolean
description: A flag indicating if the consumer has to write a "consumer message" or if he/she can leave the field blank.
definitionVersion:
$ref: "#/components/schemas/DefinitionVersion"
description:
type: string
description: Plan's description. A short description of your Plan.
example: I can use a hundred characters to describe this plan.
excludedGroups:
type: array
description: Groups of users which are not allowed to subscribe to this plan.
example:
- MY_GROUP1
- MY_GROUP2
items:
type: string
generalConditions:
type: string
description: This field contains the UUID of the documentation page that is used as General Conditions.
example: 4e3de652-2301-48ba-bde6-522301e8ba3a
name:
type: string
description: Plan's name. Duplicate names can exists.
example: My Api plan
order:
type: integer
description: Simple order that could be used by a front end to display plans in a certain order. To highlight a plan on the portal for instance.
example: 0
security:
type: object
properties:
configuration:
type: object
selectionRule:
type: string
description: An optional EL expression that will be evaluated at request time to select this plan.
tags:
type: array
description: The list of sharding tags associated with this plan.
example:
- public
- private
items:
type: string
validation:
$ref: "#/components/schemas/PlanValidation"
discriminator:
propertyName: definitionVersion
mapping:
V2: "#/components/schemas/UpdatePlanV2"
V4: "#/components/schemas/UpdatePlanV4"
required:
- definitionVersion
UpdatePlanV2:
type: object
title: "UpdatePlanV2"
allOf:
- $ref: "#/components/schemas/UpdateGenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV2"
paths:
type: object
additionalProperties:
type: array
items:
$ref: "#/components/schemas/Rule"
UpdatePlanV4:
type: object
title: "UpdatePlanV4"
allOf:
- $ref: "#/components/schemas/UpdateGenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV4"
BaseSubscription:
type: object
properties:
id:
type: string
description: Subscription's uuid.
example: 34f8c9e7-68fd-4922-b8c9-e778fc790777
Subscription:
allOf:
- $ref: "#/components/schemas/BaseSubscription"
- properties:
api:
$ref: "#/components/schemas/BaseApi"
plan:
$ref: "#/components/schemas/BasePlan"
application:
$ref: "#/components/schemas/BaseApplication"
consumerMessage:
type: string
description: Message given by the api consumer when subscribing to the api.
publisherMessage:
type: string
description: Message given by the api publisher when accepting or rejecting the subscription.
metadata:
type: object
description: A list of metadata associated to this subscription.
additionalProperties:
type: string
daysToExpirationOnLastNotification:
type: integer
format: int32
description: Number of days before the expiration of this subscription when the last pre-expiration notification was sent.
consumerConfiguration:
$ref: "#/components/schemas/SubscriptionConsumerConfiguration"
failureCause:
type: string
description: Details about the last failure encountered on this subscription.
status:
$ref: "#/components/schemas/SubscriptionStatus"
consumerStatus:
$ref: "#/components/schemas/SubscriptionConsumerStatus"
processedBy:
$ref: "#/components/schemas/BaseUser"
subscribedBy:
$ref: "#/components/schemas/BaseUser"
processedAt:
type: string
format: date-time
description: The datetime when the subscription was processed.
example: 2023-05-18T12:40:46.184Z
startingAt:
type: string
format: date-time
description: The datetime when the subscription starts. No starting date means the subscription starts immediately.
example: 2023-05-20T12:30:42.101Z
endingAt:
type: string
format: date-time
description: The datetime when the subscription ends. No ending date means the subscription never ends.
example: 2023-05-25T12:40:46.184Z
createdAt:
type: string
format: date-time
description: The datetime when the subscription was created.
example: 2023-05-18T12:40:46.184Z
updatedAt:
type: string
format: date-time
description: The last datetime when the subscription was updated.
example: 2023-05-25T12:40:46.184Z
closedAt:
type: string
format: date-time
description: The datetime when the subscription was closed.
example: 2023-05-31T13:40:46.184Z
pausedAt:
type: string
format: date-time
description: The datetime when the subscription was paused by the api publisher.
example: 2023-05-25T12:40:46.184Z
consumerPausedAt:
type: string
format: date-time
description: The datetime when the subscription was paused by the api consumer.
example: 2023-05-25T12:40:46.184Z
SubscriptionStatus:
type: string
description: The status of the subscription manageable by the api publisher.
example: ACCEPTED
enum:
- PENDING
- REJECTED
- ACCEPTED
- CLOSED
- PAUSED
- RESUMED
SubscriptionConsumerStatus:
type: string
description: The status of the subscription manageable by the api consumer.
example: STOPPED
enum:
- STARTED
- STOPPED
- FAILURE
SubscriptionConsumerConfiguration:
type: object
description: Consumer configuration associated to the subscription in case it is attached to a push plan.
properties:
entrypointId:
type: string
description: The id of the targeted entrypoint
example: webhook
channel:
type: string
description: The channel to consume
example: /channel1
entrypointConfiguration:
type: object
description: The configuration to use at subscription time to push to the target service.
example: |
{
"callbackUrl": "https://webhook.site/aaaaaaaa-ffff-ffff-ffff-aaaaaaaa",
"headers": [
{
"name": "demoHeader",
"value": "my-value"
},
{
"name": "anotherHeader",
"value": "my-value2"
}
]
}
required: [entrypointId]
CreateSubscription:
type: object
properties:
applicationId:
type: string
description: The id of the application subscribing.
planId:
type: string
description: The id plan the application is subscribing to.
customApiKey:
type: string
description: Optional custom API Key that can be given when the subscription is related to an api-key plan and custom API Key support is enabled.
consumerConfiguration:
$ref: "#/components/schemas/SubscriptionConsumerConfiguration"
metadata:
type: object
description: A list of metadata associated to this subscription.
additionalProperties:
type: string
apiKeyMode:
$ref: "#/components/schemas/ApiKeyMode"
required: [applicationId, planId]
UpdateSubscription:
type: object
properties:
consumerConfiguration:
$ref: "#/components/schemas/SubscriptionConsumerConfiguration"
metadata:
type: object
description: A list of metadata associated to this subscription.
additionalProperties:
type: string
startingAt:
type: string
format: date-time
description: The datetime when the subscription starts. No starting date means the subscription starts immediately.
example: 2023-05-20T12:30:42.101Z
endingAt:
type: string
format: date-time
description: The datetime when the subscription ends. No ending date means the subscription never ends.
example: 2023-05-25T12:40:46.184Z
VerifySubscription:
type: object
properties:
applicationId:
type: string
description: The id of the application subscribing.
apiKey:
type: string
description: 'The API Key that needs to be verified. Should not contain: ^ # % @ \\ / ; = ? | ~ , (space)'
pattern: '^[^#%@/;=?|^~, \\]*$'
required: [applicationId, apiKey]
VerifySubscriptionResponse:
type: object
properties:
ok:
type: boolean
description: Indicates whether the creation can be done or not.
reason:
type: string
description: An optional reason giving details about the result.
AcceptSubscription:
type: object
properties:
reason:
type: string
description: Optional reason explaining why the subscription has been accepted.
customApiKey:
type: string
description: Optional custom API Key that can be given when the subscription is related to an api-key plan and custom API Key support is enabled.
startingAt:
type: string
format: date-time
description: The datetime when the subscription starts. No starting date means the subscription starts immediately.
example: 2023-05-20T12:30:42.101Z
endingAt:
type: string
format: date-time
description: The datetime when the subscription ends. No ending date means the subscription never ends.
example: 2023-05-25T12:40:46.184Z
RejectSubscription:
type: object
properties:
reason:
type: string
description: Optional reason explaining why the subscription has been rejected.
TransferSubscription:
type: object
properties:
planId:
type: string
description: The plan identifier to transfer the subscription to.
ApiKey:
type: object
properties:
id:
type: string
description: The internal UUID of the API Key.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
key:
type: string
description: The API Key value to use to call the protected api.
example: my-api-key
application:
$ref: "#/components/schemas/BaseApplication"
subscriptions:
type: array
items:
$ref: "#/components/schemas/BaseSubscription"
description: The list of subscriptions using this API Key. Multiple subscription is possible with shared API Key.
revoked:
type: boolean
description: Flag indicating that the API Key has been revoked.
paused:
type: boolean
description: Flag indicating that the API Key has been paused.
expired:
type: boolean
description: Flag indicating that the API Key has expired.
daysToExpirationOnLastNotification:
type: integer
format: int32
description: Number of days before the expiration of this subscription when the last pre-expiration notification was sent.
expireAt:
type: string
format: date-time
description: The datetime when the API Key expires. No date means no expiration.
example: 2023-05-18T12:40:46.184Z
createdAt:
type: string
format: date-time
description: The datetime when the API Key has been created.
example: 2023-01-18T12:40:46.184Z
updatedAt:
type: string
format: date-time
description: The datetime when the API Key has been updated.
example: 2023-01-18T12:40:46.184Z
revokedAt:
type: string
format: date-time
description: The datetime when the API Key has been revoke. No date means not revoked.
example: 2023-01-18T12:40:46.184Z
UpdateApiKey:
type: object
properties:
expireAt:
type: string
format: date-time
description: The datetime when the API Key expires. No date means no expiration.
example: 2023-05-18T12:40:46.184Z
RenewApiKey:
type: object
properties:
customApiKey:
type: string
description: Optional custom API Key that can be given when custom API Key support is enabled.
ApiKeyMode:
type: string
description: |
The mode of an application regarding ApiKey plans.
* UNSPECIFIED: no selected mode yet
* EXCLUSIVE: an API Key is generated for each new subscription
* SHARED: reuse always the same API Key for all subscriptions
example: UNSPECIFIED
enum:
- SHARED
- EXCLUSIVE
- UNSPECIFIED
BaseUser:
type: object
description: Base information about a user.
properties:
id:
type: string
description: User's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
displayName:
type: string
description: User's name.
example: John Doe
BaseApplication:
type: object
properties:
id:
type: string
description: Application's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Application's name. Duplicate names can exist.
example: My App
description:
type: string
description: Application's description. A short description of your App.
example: I can use a hundred characters to describe this App.
domain:
type: string
description: Application's domain. Domain used by application, if relevant.
example: https://my-app.com
type:
type: string
description: Application's type.
example: iOS
primaryOwner:
$ref: "#/components/schemas/PrimaryOwner"
apiKeyMode:
$ref: "#/components/schemas/ApiKeyMode"
BaseGroup:
type: object
properties:
id:
type: string
description: Group's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Group's name.
example: Gravitee group
minLength: 1
Group:
type: object
allOf:
- $ref: "#/components/schemas/BaseGroup"
- properties:
eventRules:
type: array
items:
$ref: "#/components/schemas/GroupEvent"
description: Event rules for the group.
manageable:
type: boolean
description: Current user can manage group.
createdAt:
type: string
format: date-time
description: Group's creation date.
example: 2018-11-23T22:00:00.000Z
updatedAt:
type: string
format: date-time
description: Group's last updated date.
example: 2018-11-23T22:00:00.000Z
maxInvitation:
type: integer
description: Maximum number of group members.
apiRole:
type: string
description: The Api role of the group.
lockApiRole:
type: boolean
description: Api role cannot be changed.
applicationRole:
type: string
description: The Application role of the group.
lockApplicationRole:
type: boolean
description: Application role cannot be changed.
systemInvitation:
type: boolean
description: Invitation via user search enabled.
emailInvitation:
type: boolean
description: Email invitation enabled.
disableMembershipNotifications:
type: boolean
description: Notifications of new members are disabled.
primaryOwner:
type: boolean
description: Group's members contain one primary owner.
GroupEvent:
type: string
description: Type of group event.
enum:
- API_CREATE
- APPLICATION_CREATE
Member:
type: object
properties:
id:
type: string
description: Member's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
displayName:
type: string
description: Member's name.
example: John Doe
minLength: 1
roles:
type: array
items:
$ref: "#/components/schemas/Role"
description: The list of roles for this Member.
Role:
type: object
properties:
name:
type: string
description: Role's name.
example: OWNER
scope:
$ref: "#/components/schemas/RoleScope"
RoleScope:
type: string
description: Scope of a role.
enum:
- API
- APPLICATION
- GROUP
- ENVIRONMENT
- ORGANIZATION
- PLATFORM
AddApiMember:
type: object
description: Membership can be created for existing users, or for users provided by external identity provider. Thus, either userId or externalReference are required.
properties:
userId:
type: string
description: Technical identifier for existing user.
externalReference:
type: string
description: User's reference for user provided from an identity provider.
roleName:
type: string
description: The name of the role
minLength: 1
required: [roleName]
UpdateApiMember:
type: object
properties:
roleName:
type: string
description: The name of the role
minLength: 1
required: [roleName]
PrimaryOwner:
type: object
properties:
id:
type: string
description: Owner's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
email:
type: string
description: Owner's email. Can be null if owner is a group.
displayName:
type: string
description: Owner's name.
example: John Doe
minLength: 1
type:
$ref: "#/components/schemas/MembershipMemberType"
Property:
type: object
required:
- key
- value
properties:
key:
type: string
value:
type: string
encrypted:
type: boolean
dynamic:
type: boolean
encryptable:
type: boolean
writeOnly: true
Qos:
type: string
description: Type of the quality of service.
example: NONE
default: AUTO
enum:
- NONE
- AUTO
- AT_MOST_ONCE
- AT_LEAST_ONCE
Resource:
type: object
required:
- name
- type
- configuration
properties:
name:
type: string
type:
type: string
configuration:
type: object
enabled:
type: boolean
ResponseTemplate:
type: object
properties:
# TODO: How to specify that json output is "status"?
statusCode:
type: integer
headers:
type: object
additionalProperties:
type: string
body:
type: string
propagateErrorKeyToLogs:
type: boolean
Sampling:
type: object
properties:
type:
type: string
description: The type of the sampling
enum:
- PROBABILITY
- TEMPORAL
- COUNT
value:
type: string
description: The value of the sampling
required:
- type
MembershipMemberType:
type: string
description: The type of membership
enum:
- USER
- GROUP
Selector:
oneOf:
- $ref: "#/components/schemas/HttpSelector"
- $ref: "#/components/schemas/ChannelSelector"
- $ref: "#/components/schemas/ConditionSelector"
discriminator:
propertyName: type
mapping:
HTTP: "#/components/schemas/HttpSelector"
CHANNEL: "#/components/schemas/ChannelSelector"
CONDITION: "#/components/schemas/ConditionSelector"
BaseSelector:
properties:
type:
type: string
description: Selector type.
example: HTTP
enum:
- HTTP
- CHANNEL
- CONDITION
discriminator:
propertyName: type
mapping:
HTTP: "#/components/schemas/HttpSelector"
CHANNEL: "#/components/schemas/ChannelSelector"
CONDITION: "#/components/schemas/ConditionSelector"
required:
- type
ServiceV4:
type: object
properties:
overrideConfiguration:
type: boolean
description: Override the configuration of the service
default: false
configuration:
type: object
description: The configuration of the service
enabled:
type: boolean
description: Is the service enabled or not.
default: true
type:
type: string
BaseStep:
type: object
properties:
name:
type: string
description: The name of the step
description:
type: string
description: The description of the step
enabled:
type: boolean
description: Is the step enabled or not.
default: true
policy:
type: string
description: The policy of the step
configuration:
type: object
description: The configuration of the step
condition:
type: string
description: The condition of the step
StepV4:
allOf:
- $ref: "#/components/schemas/BaseStep"
- properties:
messageCondition:
type: string
description: The message condition of the step
SubscriptionListener:
title: "SubscriptionListener"
required:
- type
allOf:
- $ref: "#/components/schemas/BaseListener"
TcpListener:
title: "TcpListener"
required:
- type
allOf:
- $ref: "#/components/schemas/BaseListener"
- type: object
properties:
hosts:
description: >-
A list of hostnames for which the API will match against SNI.
This must be unique for all TCP listener for a given server id. See 'servers' attribute
type: array
minItems: 1
items:
type: string
minLength: 1
required:
- "hosts"
VerifyApiPaths:
title: "VerifyApiPaths"
properties:
apiId:
type: string
paths:
type: array
items:
$ref: "#/components/schemas/Path"
required: [paths]
## API V2 specific schemas
ApiEntrypoint:
type: object
properties:
target:
type: string
description: The target of the entrypoint.
example: /my-api
host:
type: string
description: The host of the entrypoint.
example: my-api.mycompany.com
tags:
type: array
description: The list of sharding tags associated with this entrypoint.
example:
- public
- private
items:
type: string
Consumer:
type: object
properties:
consumerType:
$ref: "#/components/schemas/ConsumerType"
consumerId:
type: string
description: The id of the consumer.
example: myTag
ConsumerType:
type: string
description: The type of the consumer.
default: TAG
enum:
- TAG
DynamicPropertyProvider:
type: string
description: The type of the dynamic property provider.
example: HTTP
enum:
- HTTP
DynamicPropertyService:
type: object
properties:
schedule:
type: string
description: The schedule of the service
provider:
$ref: "#/components/schemas/DynamicPropertyProvider"
configuration:
oneOf:
- $ref: "#/components/schemas/HttpDynamicPropertyProviderConfiguration"
discriminator:
propertyName: provider
mapping:
HTTP: "#/components/schemas/HttpDynamicPropertyProviderConfiguration"
enabled:
type: boolean
description: Is the service enabled or not.
default: true
EndpointV2:
oneOf:
- $ref: "#/components/schemas/HttpEndpointV2"
discriminator:
propertyName: type
mapping:
http: "#/components/schemas/HttpEndpointV2"
grpc: "#/components/schemas/HttpEndpointV2"
BaseEndpointV2:
type: object
properties:
name:
type: string
description: The name of the endpoint
example: default-endpoint
nullable: false
target:
type: string
description: The target of the endpoint
example: http://mycompany.com
weight:
type: integer
format: int32
description: The weight of the endpoint
default: 1
backup:
type: boolean
description: Is the endpoint a backup or not.
default: false
status:
$ref: "#/components/schemas/EndpointStatus"
tenants:
type: array
description: The list of tenants associated with this endpoint.
example:
- my-tenant
items:
type: string
type:
type: string
description: The type of the endpoint.
example: HTTP
inherit:
type: boolean
description: Inherit the configuration of the parent endpoint group.
default: false
healthCheck:
$ref: "#/components/schemas/EndpointHealthCheckService"
required:
- type
HttpEndpointV2:
title: "HttpEndpointV2"
allOf:
- $ref: "#/components/schemas/BaseEndpointV2"
- properties:
httpProxy:
$ref: "#/components/schemas/HttpProxy"
httpClientOptions:
$ref: "#/components/schemas/HttpClientOptions"
httpClientSslOptions:
$ref: "#/components/schemas/HttpClientSslOptions"
headers:
type: array
description: The list of headers associated with this endpoint.
example:
- name: X-My-Header
value: my-value
items:
$ref: "#/components/schemas/HttpHeader"
healthCheck:
$ref: "#/components/schemas/EndpointHealthCheckService"
EndpointDiscoveryService:
type: object
properties:
provider:
type: string
description: The provider of the service
configuration:
type: object
description: The configuration of the service
enabled:
type: boolean
description: Is the service enabled or not.
default: true
EndpointGroupV2:
type: object
properties:
name:
type: string
description: Endpoint group's name.
example: My Endpoint Group
minLength: 1
endpoints:
type: array
description: The list of endpoints associated with this endpoint group.
items:
$ref: "#/components/schemas/EndpointV2"
loadBalancer:
$ref: "#/components/schemas/LoadBalancer"
services:
$ref: "#/components/schemas/EndpointGroupServicesV2"
httpProxy:
$ref: "#/components/schemas/HttpProxy"
httpClientOptions:
$ref: "#/components/schemas/HttpClientOptions"
httpClientSslOptions:
$ref: "#/components/schemas/HttpClientSslOptions"
headers:
type: array
description: The list of headers associated with this endpoint group.
example:
- name: X-My-Header
value: my-value
items:
$ref: "#/components/schemas/HttpHeader"
EndpointHealthCheckService:
allOf:
- $ref: "#/components/schemas/HealthCheckService"
- properties:
inherit:
type: boolean
description: Inherit the configuration of the parent endpoint.
EndpointStatus:
type: string
description: The status of the endpoint.
example: UP
enum:
- UP
- DOWN
- TRANSITIONALLY_DOWN
- TRANSITIONALLY_UP
ExecutionMode:
type: string
description: The execution mode of the API.
example: V4_EMULATION_ENGINE
default: V4_EMULATION_ENGINE
enum:
- V3
- V4_EMULATION_ENGINE
Failover:
type: object
properties:
maxAttempts:
type: integer
format: int32
description: The maximum number of attempts.
default: 1
retryTimeout:
type: integer
format: int64
description: The retry timeout in ms
default: 10000
cases:
type: array
description: The list of cases associated with this failover.
items:
$ref: "#/components/schemas/FailoverCase"
default: ["TIMEOUT"]
FailoverCase:
type: string
description: The case of the failover.
enum:
- TIMEOUT
FlowStage:
type: string
description: The stage of the flow.
enum:
- PLATFORM
- PLAN
- API
FlowV2:
type: object
properties:
id:
type: string
description: Flow's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Flow's name.
example: My Flow
pathOperator:
$ref: "#/components/schemas/PathOperator"
pre:
type: array
items:
$ref: "#/components/schemas/StepV2"
post:
type: array
items:
$ref: "#/components/schemas/StepV2"
enabled:
type: boolean
description: Is the flow enabled.
default: true
methods:
type: array
items:
$ref: "#/components/schemas/HttpMethod"
condition:
type: string
description: The condition to evaluate to determine if the flow should be executed.
example: "{#request.headers['x-foo'] == 'bar'}"
consumers:
type: array
items:
$ref: "#/components/schemas/Consumer"
stage:
$ref: "#/components/schemas/FlowStage"
HealthCheckRequest:
type: object
properties:
path:
type: string
description: The path of the request
example: /my/path
method:
$ref: "#/components/schemas/HttpMethod"
headers:
type: array
items:
$ref: "#/components/schemas/HttpHeader"
body:
type: string
description: The body of the request
example: my body
fromRoot:
type: boolean
description: Is the request from the root or not
default: false
HealthCheckResponse:
type: object
properties:
assertions:
type: array
items:
type: string
description: The assertion to check
example: "{#response.status == 200}"
HealthCheckService:
type: object
properties:
schedule:
type: string
description: The schedule of the service
steps:
type: array
items:
$ref: "#/components/schemas/HealthCheckStep"
enabled:
type: boolean
description: Is the service enabled or not.
HealthCheckStep:
type: object
properties:
name:
type: string
description: The name of the step
default: default-step
request:
$ref: "#/components/schemas/HealthCheckRequest"
response:
$ref: "#/components/schemas/HealthCheckResponse"
HttpClientOptions:
type: object
properties:
idleTimeout:
type: integer
format: int32
description: The idle timeout of the http client in ms
default: 60000
keepAliveTimeout:
type: integer
format: int32
description: The keep-alive timeout of the http client in ms
default: 30000
connectTimeout:
type: integer
format: int32
description: The connect timeout of the http client in ms
default: 5000
keepAlive:
type: boolean
description: The keep alive parameter of the http client
default: true
readTimeout:
type: integer
format: int32
description: The read timeout of the http client in ms
default: 10000
pipelining:
type: boolean
description: The pipelining parameter of the http client
default: false
maxConcurrentConnections:
type: integer
format: int32
description: The max connections of the http client
default: 100
useCompression:
type: boolean
description: Use compression or not
default: true
propagateClientAcceptEncoding:
type: boolean
description: Propagate the client accept encoding or not
default: false
followRedirects:
type: boolean
description: Follow redirects or not
default: false
clearTextUpgrade:
type: boolean
description: Clear text upgrade or not
default: true
version:
$ref: "#/components/schemas/ProtocolVersion"
HttpClientSslOptions:
type: object
properties:
trustAll:
type: boolean
description: Trust all certificates or not
default: false
hostnameVerifier:
type: boolean
description: Should the hostname be verified or not
default: false
trustStore:
$ref: "#/components/schemas/TrustStore"
keyStore:
$ref: "#/components/schemas/KeyStore"
headers:
type: array
items:
$ref: "#/components/schemas/HttpHeader"
HttpDynamicPropertyProviderConfiguration:
type: object
title: "HttpDynamicPropertyProviderConfiguration"
properties:
url:
type: string
description: The url of the dynamic property provider
example: http://my-provider.com
specification:
type: string
description: The specification of the dynamic property provider
example: my-specification
useSystemProxy:
type: boolean
description: Use the system proxy or not
default: false
method:
$ref: "#/components/schemas/HttpMethod"
headers:
type: array
items:
$ref: "#/components/schemas/HttpHeader"
body:
type: string
description: The body of the request
example: my body
provider:
$ref: "#/components/schemas/DynamicPropertyProvider"
required:
- provider
HttpHeader:
type: object
properties:
name:
type: string
description: The name of the header
example: my-header
value:
type: string
description: The value of the header
example: my-value
HttpProxy:
type: object
properties:
enabled:
type: boolean
description: Is the proxy enabled or not
default: false
useSystemProxy:
type: boolean
description: Use the system proxy or not
default: false
host:
type: string
description: The host of the proxy
example: my-proxy.com
port:
type: integer
description: The port of the proxy
example: 8080
username:
type: string
description: The username used to connect to the proxy
example: my-username
password:
type: string
description: The password used to connect to the proxy
example: my-password
type:
$ref: "#/components/schemas/HttpProxyType"
HttpProxyType:
type: string
description: The type of the proxy.
example: HTTP
enum:
- HTTP
- SOCKS4
- SOCKS5
KeyStore:
oneOf:
- $ref: "#/components/schemas/JKSKeyStore"
- $ref: "#/components/schemas/PEMKeyStore"
- $ref: "#/components/schemas/PKCS12KeyStore"
- $ref: "#/components/schemas/NoneKeyStore"
discriminator:
propertyName: type
mapping:
JKS: "#/components/schemas/JKSKeyStore"
PEM: "#/components/schemas/PEMKeyStore"
PKCS12: "#/components/schemas/PKCS12KeyStore"
NONE: "#/components/schemas/NoneKeyStore"
KeyStoreType:
type: string
description: The type of the key store.
example: JKS
enum:
- JKS
- PEM
- PKCS12
- NONE
BaseKeyStore:
type: object
properties:
type:
$ref: "#/components/schemas/KeyStoreType"
discriminator:
propertyName: type
mapping:
JKS: "#/components/schemas/JKSKeyStore"
PEM: "#/components/schemas/PEMKeyStore"
PKCS12: "#/components/schemas/PKCS12KeyStore"
NONE: "#/components/schemas/NoneKeyStore"
required:
- type
JKSKeyStore:
title: "JKSKeyStore"
allOf:
- $ref: "#/components/schemas/BaseKeyStore"
- properties:
path:
type: string
description: The path of the key store
example: /path/to/KeyStore.jks
content:
type: string
description: The content of the key store
password:
type: string
description: The password of the key store
PEMKeyStore:
title: "PEMKeyStore"
allOf:
- $ref: "#/components/schemas/BaseKeyStore"
- properties:
keyPath:
type: string
description: The path of the key store
example: /path/to/KeyStore.pem
keyContent:
type: string
description: The content of the key store
certPath:
type: string
description: The path of the key store
example: /path/to/KeyStore.pem
certContent:
type: string
description: The content of the key store
PKCS12KeyStore:
title: "PKCS12KeyStore"
allOf:
- $ref: "#/components/schemas/BaseKeyStore"
- properties:
path:
type: string
description: The path of the key store
example: /path/to/KeyStore.jks
content:
type: string
description: The content of the key store
password:
type: string
description: The password of the key store
NoneKeyStore:
title: "NoneKeyStore"
allOf:
- $ref: "#/components/schemas/BaseKeyStore"
LoggingV2:
type: object
properties:
mode:
$ref: "#/components/schemas/LoggingModeV2"
scope:
$ref: "#/components/schemas/LoggingScope"
content:
$ref: "#/components/schemas/LoggingContentV2"
condition:
type: string
description: The condition of the logging
example: "{#context.attributes['my-attribute'] == 'my-value'}"
LoggingContentV2:
type: string
description: The content of the logging.
example: NONE
enum:
- NONE
- HEADERS
- PAYLOADS
- HEADERS_PAYLOADS
LoggingModeV2:
type: string
description: The mode of the logging.
example: NONE
enum:
- NONE
- CLIENT
- PROXY
- CLIENT_PROXY
LoggingScope:
type: string
description: The scope of the logging.
example: REQUEST
enum:
- NONE
- REQUEST
- RESPONSE
- REQUEST_RESPONSE
PathOperator:
type: object
properties:
path:
type: string
description: The path of the selector
example: /my/path
operator:
$ref: "#/components/schemas/Operator"
PlanV2:
type: object
title: "PlanV2"
allOf:
- $ref: "#/components/schemas/GenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV2"
paths:
type: object
additionalProperties:
type: array
items:
$ref: "#/components/schemas/Rule"
ProtocolVersion:
type: string
description: The protocol version.
example: HTTP_1_1
default: HTTP_1_1
enum:
- HTTP_1_1
- HTTP_2
Proxy:
type: object
properties:
virtualHosts:
type: array
items:
$ref: "#/components/schemas/VirtualHost"
groups:
type: array
items:
$ref: "#/components/schemas/EndpointGroupV2"
failover:
$ref: "#/components/schemas/Failover"
cors:
$ref: "#/components/schemas/Cors"
logging:
$ref: "#/components/schemas/LoggingV2"
stripContextPath:
type: boolean
default: false
preserveHost:
type: boolean
default: false
servers:
type: array
items:
type: string
ApiServicesV2:
type: object
properties:
dynamicProperty:
$ref: "#/components/schemas/DynamicPropertyService"
healthCheck:
$ref: "#/components/schemas/HealthCheckService"
EndpointGroupServicesV2:
type: object
properties:
discovery:
$ref: "#/components/schemas/EndpointDiscoveryService"
StepV2:
allOf:
- $ref: "#/components/schemas/BaseStep"
TrustStore:
oneOf:
- $ref: "#/components/schemas/JKSTrustStore"
- $ref: "#/components/schemas/PEMTrustStore"
- $ref: "#/components/schemas/PKCS12TrustStore"
- $ref: "#/components/schemas/NoneTrustStore"
discriminator:
propertyName: type
mapping:
JKS: "#/components/schemas/JKSTrustStore"
PEM: "#/components/schemas/PEMTrustStore"
PKCS12: "#/components/schemas/PKCS12TrustStore"
NONE: "#/components/schemas/NoneTrustStore"
TrustStoreType:
type: string
description: The type of the trust store.
example: JKS
enum:
- JKS
- PEM
- PKCS12
- NONE
BaseTrustStore:
type: object
properties:
type:
$ref: "#/components/schemas/TrustStoreType"
required:
- type
discriminator:
propertyName: type
mapping:
JKS: "#/components/schemas/JKSTrustStore"
PEM: "#/components/schemas/PEMTrustStore"
PKCS12: "#/components/schemas/PKCS12TrustStore"
NONE: "#/components/schemas/NoneTrustStore"
JKSTrustStore:
title: "JKSTrustStore"
allOf:
- $ref: "#/components/schemas/BaseTrustStore"
- properties:
path:
type: string
description: The path of the trust store
example: /path/to/truststore.jks
content:
type: string
description: The content of the trust store
password:
type: string
description: The password of the trust store
PEMTrustStore:
title: "PEMTrustStore"
allOf:
- $ref: "#/components/schemas/BaseTrustStore"
- properties:
path:
type: string
description: The path of the trust store
example: /path/to/truststore.pem
content:
type: string
description: The content of the trust store
PKCS12TrustStore:
title: "PKCS12TrustStore"
allOf:
- $ref: "#/components/schemas/BaseTrustStore"
- properties:
path:
type: string
description: The path of the trust store
example: /path/to/truststore.jks
content:
type: string
description: The content of the trust store
password:
type: string
description: The password of the trust store
NoneTrustStore:
title: "NoneTrustStore"
allOf:
- $ref: "#/components/schemas/BaseTrustStore"
VirtualHost:
type: object
properties:
host:
type: string
description: The host of the virtual host
path:
type: string
description: The path of the virtual host
default: /
overrideEntrypoint:
type: boolean
description: Override the entrypoint or not
default: false
# Analytics - Logs
ApiLog:
type: object
properties:
timestamp:
type: string
format: date-time
description: The date (as timestamp) of the log.
example: 2023-05-18T12:40:46.184Z
id:
type: string
description: The internal UUID of the Log.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
requestId:
type: string
description: The id of the request.
example: 1719d8d1-8d01-48f6-99d8-d18d0178f6d4
method:
$ref: "#/components/schemas/HttpMethod"
clientIdentifier:
type: string
description: The client identifier of the request.
example: 12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0
plan:
$ref: "#/components/schemas/BasePlan"
application:
$ref: "#/components/schemas/BaseApplication"
transactionId:
type: string
description: The id of the transaction.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
status:
type: integer
description: The response's status.
example: 200
requestEnded:
type: boolean
description: The flag indicating if the request has ended.
example: true
ApiMessageLog:
type: object
properties:
requestId:
type: string
description: The id of the request.
example: 1719d8d1-8d01-48f6-99d8-d18d0178f6d4
timestamp:
type: string
format: date-time
description: The date (as timestamp) of the log.
example: 2023-05-18T12:40:46.184Z
clientIdentifier:
type: string
description: The client identifier of the request.
example: 12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0
correlationId:
type: string
description: The correlation id.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
parentCorrelationId:
type: string
description: The parent correlation id.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
operation:
type: string
description: The operation.
example: subscribe
entrypoint:
$ref: "#/components/schemas/ApiMessageLogContent"
endpoint:
$ref: "#/components/schemas/ApiMessageLogContent"
ApiLogRequestContent:
type: object
description: The log request content.
properties:
method:
$ref: "#/components/schemas/HttpMethod"
uri:
type: string
description: URI of the request.
example: /my-api
headers:
type: object
description: The list of headers associated with this message.
example:
- name: X-My-Header
value: [my-value]
body:
type: string
description: The request's body.
example: my body
ApiLogResponseContent:
type: object
description: The log response content.
properties:
status:
type: integer
description: The response's status.
example: 200
headers:
type: object
description: The list of headers associated with this message.
example:
- name: X-My-Header
value: [my-value]
body:
type: string
description: The response's body.
example: my body
ApiMessageLogContent:
type: object
description: The message content.
example: |
{
"id": "0",
"payload": "mock message",
"headers": {
"X-Mock": [
"mocked"
]
},
"metadata": {
"MessageMetadata": "A metadata"
}
}
properties:
id:
type: string
description: The internal UUID of the Message.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
connectorId:
type: string
description: The id of connector for this log.
example: kafka
payload:
type: string
description: The payload of the Message.
example: "This is a message"
isError:
type: boolean
description: Is the Message in error.
example: false
headers:
type: object
description: The list of headers associated with this message.
example:
- name: X-My-Header
value: [my-value]
metadata:
type: object
description: The list of Message's metadata.
ApiLogHeader:
type: object
properties:
name:
type: string
description: The name of the header
example: my-header
value:
type: array
description: The values of the header
example: [my-value]
items:
type: string
ApiLogMetadata:
type: object
properties:
name:
type: string
description: The name of the metadata
example: my-metadata
value:
type: string
description: The value of the metadata
example: [my-value]
# Documentation pages
AccessControl:
type: object
properties:
referenceId:
type: string
description: The id of the resource used to check the access control
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
referenceType:
type: string
description: The type of the resource used to check the access control
example:
- GROUP
- ROLE
Media:
type: object
properties:
id:
type: string
description: Media's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
hash:
type: string
description: Media's hash.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
type:
type: string
description: Media's type.
example: image/png
subType:
type: string
description: Media's sub type.
example: png
fileName:
type: string
description: Media's file name.
example: my-image.png
size:
type: integer
format: int64
description: Media's size.
example: 1000
data:
type: string
format: byte
description: Media's data.
example: binary encoded data
createdAt:
type: string
format: date-time
description: Media's creation date.
example: 2018-11-23T22:00:00.000Z
Page:
description: Documentation page. Can be of multiple formats.
type: object
properties:
id:
type: string
description: Page's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
crossId:
type: string
description: Page's cross uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Page's name.
example: My Page
type:
$ref: "#/components/schemas/PageType"
content:
type: string
description: Page's content.
example: My Page content
order:
type: integer
description: Page's order.
example: 1
lastContributor:
type: string
description: Page's last contributor. Id of a user.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
published:
type: boolean
description: Page's published status.
example: true
visibility:
$ref: "#/components/schemas/Visibility"
updatedAt:
type: string
format: date-time
description: Page's last update date.
example: 2018-01-01T00:00:00.000Z
contentType:
type: string
description: Page's content type.
example: application/json
source:
$ref: "#/components/schemas/PageSource"
configuration:
type: object
description: Page's configuration.
additionalProperties:
type: string
homepage:
type: boolean
description: Page's homepage status.
example: true
parentId:
type: string
description: Page's parent id.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
parentPath:
type: string
description: Page's parent path.
example: /parent
excludedGroups:
type: array
description: List of group ids that are considered when looking for acces control.
items:
type: string
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
excludedAccessControls:
type: boolean
description: Flag to restrict access to user matching the restrictions.
accessControls:
type: array
description: List of access controls.
items:
$ref: "#/components/schemas/AccessControl"
attachedMedia:
type: array
description: List of attached media.
items:
$ref: "#/components/schemas/PageMedia"
metadata:
type: object
description: Page's metadata.
additionalProperties:
type: string
translations:
type: array
description: List of page translations.
items:
$ref: "#/components/schemas/Page"
contentRevision:
$ref: "#/components/schemas/Revision"
hidden:
type: boolean
description: If folder is published but not shown in Portal.
generalConditions:
type: boolean
description: If page is used as General Conditions of an active plan.
PageMedia:
type: object
properties:
name:
type: string
description: Media's name.
example: My Media
hash:
type: string
description: Media's hash.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
attachedAt:
type: string
format: date-time
description: Media's attachment date.
example: 2018-01-01T00:00:00.000Z
PageSource:
type: object
properties:
type:
type: string
description: The type of the page source (=fetcher type).
example:
- http-fetcher
- git-fetcher
- gitlab-fetcher
- github-fetcher
- bitbucket-fetcher
configuration:
type: object
description: Page source's configuration.
PageType:
type: string
description: The type of the page.
example: MARKDOWN
enum:
- ASCIIDOC
- ASYNCAPI
- MARKDOWN
- MARKDOWN_TEMPLATE
- SWAGGER
- FOLDER
- LINK
- ROOT
- SYSTEM_FOLDER
- TRANSLATION
CreateDocumentation:
type: object
properties:
name:
type: string
description: Page's name.
example: My Page
minLength: 1
type:
type: string
description: The type of the page. Only MARKDOWN and FOLDER types can be created.
example: MARKDOWN
enum:
- MARKDOWN
- FOLDER
visibility:
$ref: "#/components/schemas/Visibility"
parentId:
type: string
description: Page's parent id.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
required:
- name
- type
discriminator:
propertyName: type
mapping:
FOLDER: "#/components/schemas/CreateDocumentationFolder"
MARKDOWN: "#/components/schemas/CreateDocumentationMarkdown"
CreateDocumentationFolder:
title: "CreateDocumentationFolder"
description: Create documentation folder.
type: object
allOf:
- $ref: "#/components/schemas/CreateDocumentation"
required:
- name
- type
CreateDocumentationMarkdown:
title: "CreateDocumentationMarkdown"
description: Create documentation markdown page.
type: object
allOf:
- $ref: "#/components/schemas/CreateDocumentation"
- properties:
content:
type: string
description: Page's content.
example: My Page content
homepage:
type: boolean
description: Page's homepage status.
example: true
required:
- name
- type
UpdateDocumentation:
type: object
properties:
type:
type: string
description: The type of documentation to update.
enum:
- FOLDER
- MARKDOWN
name:
type: string
description: Page's name.
example: My Page
minLength: 1
order:
type: integer
description: Page's order.
example: 1
default: 0
minimum: 0
visibility:
$ref: "#/components/schemas/Visibility"
required:
- type
- name
discriminator:
propertyName: type
mapping:
FOLDER: "#/components/schemas/UpdateDocumentationFolder"
MARKDOWN: "#/components/schemas/UpdateDocumentationMarkdown"
UpdateDocumentationFolder:
title: "UpdateDocumentationFolder"
description: Update documentation folder.
type: object
allOf:
- $ref: "#/components/schemas/UpdateDocumentation"
UpdateDocumentationMarkdown:
title: "UpdateDocumentationMarkdown"
description: Update documentation markdown page.
type: object
allOf:
- $ref: "#/components/schemas/UpdateDocumentation"
- properties:
content:
type: string
description: Page's content.
example: My Page content
homepage:
type: boolean
description: Page's homepage status.
example: true
Revision:
type: object
properties:
id:
type: string
description: Id of the page used to fill the content attributes.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
revision:
type: integer
description: Revision number.
example: 1
Breadcrumb:
type: object
properties:
position:
type: integer
description: Distance of folder from the root
example: 1
id:
type: string
description: Id of the folder
example: folder-id
name:
type: string
description: Name of the folder
example: A lovely folder name
# Metadata Page
Metadata:
type: object
properties:
key:
type: string
description: The key of the metadata.
minLength: 1
name:
type: string
description: The name of the metadata.
format:
$ref: "#/components/schemas/MetadataFormat"
value:
type: string
description: The value of the metadata.
minLength: 1
defaultValue:
type: string
description: The default value of the metadata.
MetadataFormat:
type: string
description: The format of the metadata.
example: DATE
enum:
- STRING
- NUMERIC
- BOOLEAN
- DATE
- MAIL
- URL
Rule:
type: object
properties:
methods:
type: array
items:
$ref: "#/components/schemas/HttpMethod"
description:
type: string
description: The description of the rule
enabled:
type: boolean
description: Is the rule enabled or not.
default: true
operation:
type: string
description: The operation of the rule
configuration:
type: object
description: The configuration of the rule
additionalProperties:
type: object
parameters:
#############
# PathParam #
#############
orgIdParam:
name: orgId
in: path
required: true
description: Id of an organization.
schema:
type: string
default: DEFAULT
envIdParam:
name: envId
in: path
required: true
description: Id or Hrid (Human readable Id) of an environment.
schema:
type: string
default: DEFAULT
apiIdParam:
name: apiId
in: path
required: true
description: Id of an API.
schema:
type: string
requestIdParam:
name: requestId
in: path
required: true
description: Id of a request.
schema:
type: string
groupIdParam:
name: groupId
in: path
required: true
description: Id of a group.
schema:
type: string
memberIdParam:
name: memberId
in: path
required: true
description: Id of an API member.
schema:
type: string
pageIdParam:
name: pageId
in: path
required: true
description: Id of a documentation page.
schema:
type: string
planIdParam:
name: planId
in: path
required: true
description: Id of a plan.
schema:
type: string
subscriptionIdParam:
name: subscriptionId
in: path
required: true
description: Id of a subscription.
schema:
type: string
apiKeyIdParam:
name: apiKeyId
in: path
required: true
description: Id of an API Key.
schema:
type: string
endpointIdParam:
name: endpointId
in: path
required: true
description: Id of an endpoint.
schema:
type: string
entrypointIdParam:
name: entrypointId
in: path
required: true
description: Id of an entrypoint.
schema:
type: string
policyIdParam:
name: policyId
in: path
required: true
description: Id of a policy.
schema:
type: string
###############################
# Pagination Query Parameters #
###############################
apiSortByParam:
name: sortBy
in: query
required: false
description: |-
Possibility to sort APIs results by field.
Can be ascending or descending with minus '-' prefix.
By default, no sort is applied.
schema:
type: string
example: name
enum:
- name
- -name
- paths
- -paths
pageParam:
name: page
in: query
required: false
description: The page number for pagination.
schema:
type: integer
default: 1
perPageParam:
name: perPage
in: query
required: false
description: |
The number of items per page for pagination.
schema:
type: integer
default: 10
###############################
# Other Query Parameters #
###############################
apisSearchExpandsParam:
name: expands
in: query
description: Expansion of data to return in APIs.
schema:
type: array
items:
type: string
enum:
- deploymentState
apisGetExpandsParam:
name: expands
in: query
description: Expansion of data to return in APIs.
schema:
type: array
items:
type: string
enum:
- deploymentState
- primaryOwner
from:
name: from
in: query
required: false
description: |
The timestamp from which the logs will be returned.
schema:
type: integer
to:
name: to
in: query
required: false
description: |
The timestamp to which the logs will be returned.
schema:
type: integer
applicationIds:
name: applicationIds
description: List of application ids to filter on.
in: query
explode: false
schema:
type: array
items:
type: string
parentId:
name: parentId
in: query
required: false
description: Id of the parent folder or 'ROOT' for the top folder.
examples:
root:
value: ROOT
summary: Hard-coded value for top level folder
parentId:
value: 919a8df8-6e53-11ee-b962-0242ac120002
summary: ID of the parent folder
schema:
type: string
planIds:
name: planIds
description: List of plan ids to filter on.
in: query
explode: false
schema:
type: array
items:
type: string
methods:
name: methods
description: List of HTTP request methods to filter on.
in: query
explode: false
schema:
type: array
items:
$ref: "#/components/schemas/HttpMethod"
statuses:
name: statuses
description: List of http statuses to filter on.
in: query
explode: false
schema:
type: array
items:
type: integer
responses:
EnvironmentsResponse:
description: Page of environments
content:
application/json:
schema:
properties:
data:
description: List of Environments.
type: array
items:
$ref: "#/components/schemas/Environment"
metadata:
$ref: "#/components/schemas/MetadataResponse"
links:
$ref: "#/components/schemas/Links"
ApisResponse:
description: Page of apis
content:
application/json:
schema:
title: "ApisResponse"
properties:
data:
description: List of Apis.
type: array
items:
$ref: "#/components/schemas/Api"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
GroupsResponse:
description: Page of Groups
content:
application/json:
schema:
title: "GroupsResponse"
properties:
data:
description: List of groups.
type: array
items:
$ref: "#/components/schemas/Group"
links:
$ref: "#/components/schemas/Links"
metadata:
$ref: "#/components/schemas/MetadataResponse"
pagination:
$ref: "#/components/schemas/Pagination"
ImageResponse:
description: An image
content:
"image/*":
schema:
type: string
format: binary
PlansResponse:
description: Page of API plans
content:
application/json:
schema:
title: "PlansResponse"
properties:
data:
description: List of API plans.
type: array
items:
$ref: "#/components/schemas/Plan"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
SubscribersResponse:
description: Page of API subscribers
content:
application/json:
schema:
title: "SubscribersResponse"
properties:
data:
description: List of API subscribers.
type: array
items:
$ref: "#/components/schemas/BaseApplication"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
SubscriptionsResponse:
description: Page of API subscriptions
content:
application/json:
schema:
title: "SubscriptionsResponse"
properties:
data:
description: List of API subscriptions.
type: array
items:
$ref: "#/components/schemas/Subscription"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
SubscriptionApiKeysResponse:
description: Page of subscription API Keys
content:
application/json:
schema:
title: "SubscriptionApiKeysResponse"
properties:
data:
description: List of subscription API Keys.
type: array
items:
$ref: "#/components/schemas/ApiKey"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
MembersResponse:
description: Page of API members
content:
application/json:
schema:
title: "MembersResponse"
properties:
data:
description: List of API members.
type: array
items:
$ref: "#/components/schemas/Member"
links:
$ref: "#/components/schemas/Links"
metadata:
$ref: "#/components/schemas/MetadataResponse"
pagination:
$ref: "#/components/schemas/Pagination"
SchemaFormResponse:
description: Schema form of a plugin
content:
application/json:
schema:
type: object
Error:
description: Generic error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
VerifyApiPathsResponse:
description: Result of the API paths verification
content:
application/json:
schema:
title: "VerifyApiPathsResponse"
properties:
ok:
type: boolean
description: Indicates whether the paths are valid.
reason:
type: string
description: An optional reason giving details about the result.
# Analytics - Logs
ApiLogsResponse:
description: Page of API Logs
content:
application/json:
schema:
title: "ApiLogsResponse"
properties:
data:
description: List of API logs.
type: array
items:
$ref: "#/components/schemas/ApiLog"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
ApiLogResponse:
description: API log for a particular request
content:
application/json:
schema:
title: "ApiLogResponse"
description: API log for a request.
properties:
timestamp:
type: string
format: date-time
description: The date (as timestamp) of the log.
example: 2023-05-18T12:40:46.184Z
apiId:
type: string
description: The id of the api.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
requestId:
type: string
description: The id of the request.
example: 1719d8d1-8d01-48f6-99d8-d18d0178f6d4
clientIdentifier:
type: string
description: The client identifier of the request.
example: 12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0
transactionId:
type: string
description: The id of the transaction.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
requestEnded:
type: boolean
description: The flag indicating if the request has ended.
example: true
entrypointRequest:
$ref: "#/components/schemas/ApiLogRequestContent"
entrypointResponse:
$ref: "#/components/schemas/ApiLogResponseContent"
endpointRequest:
$ref: "#/components/schemas/ApiLogRequestContent"
endpointResponse:
$ref: "#/components/schemas/ApiLogResponseContent"
ApiMessageLogsResponse:
description: Page of API Messages Logs
content:
application/json:
schema:
title: "ApiMessageLogsResponse"
properties:
data:
description: List of API Messages logs.
type: array
items:
$ref: "#/components/schemas/ApiMessageLog"
pagination:
$ref: "#/components/schemas/Pagination"
links:
$ref: "#/components/schemas/Links"
# API Documentation
ApiDocumentationPagesResponse:
description: API documentation pages
content:
application/json:
schema:
title: "ApiDocumentationPagesResponse"
properties:
pages:
type: array
items:
$ref: "#/components/schemas/Page"
breadcrumb:
type: array
description: Breadcrumb to the root folder. Only returned when parentId is specified.
items:
$ref: "#/components/schemas/Breadcrumb"
securitySchemes:
BasicAuth:
type: http
scheme: basic
CookieAuth:
type: apiKey
in: cookie
name: Auth-Graviteeio-APIM