openapi: 3.0.3
info:
title: Gravitee.io APIM - Management API
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: /management/v2
description: Gravitee.io APIM - Management API -v2
tags:
- name: APIs
description: Everything about APIs
- 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: Group
description: Everything about groups
- name: Installation
description: Base resources about the installation
- name: Plugins - Endpoints
description: Everything about endpoint plugins
- name: Plugins - Entrypoints
description: Everything about entrypoint plugins
- name: Plugins - Policies
description: Everything about policies plugins
paths:
# APIs
/environments/{envId}/apis:
parameters:
- $ref: "#/components/parameters/envIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
- $ref: "#/components/parameters/apiExpandsParam"
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/apiExpandsParam"
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/{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"
# 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/{groupId}/members:
parameters:
- $ref: "#/components/parameters/envIdParam"
- $ref: "#/components/parameters/groupIdParam"
get:
parameters:
- $ref: "#/components/parameters/pageParam"
- $ref: "#/components/parameters/perPageParam"
tags:
- Group
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:
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}:
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:
- 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:
- 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"
# Plugins - Endpoints
/plugins/endpoints:
get:
tags:
- Plugins - Endpoints
summary: Get available endpoints on the platform
description: |
Get available endpoint types on the platform.
User must be authenticated.
operationId: getEndpoints
responses:
"200":
description: List of Endpoints.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ConnectorPlugin"
default:
$ref: "#/components/responses/Error"
/plugins/endpoints/{endpointId}:
parameters:
- $ref: "#/components/parameters/endpointIdParam"
get:
tags:
- Plugins - Endpoints
summary: Get an endpoint
description: |
Get an endpoint type.
User must be authenticated.
operationId: getEndpoint
responses:
"200":
description: Endpoint
content:
application/json:
schema:
$ref: "#/components/schemas/ConnectorPlugin"
default:
$ref: "#/components/responses/Error"
/plugins/endpoints/{endpointId}/documentation:
parameters:
- $ref: "#/components/parameters/endpointIdParam"
get:
tags:
- Plugins - Endpoints
summary: Get an endpoint documentation
description: |
Get the documentation of an endpoint.
User must be authenticated.
operationId: getEndpointDocumentation
responses:
"200":
description: Documentation of the endpoint
content:
text/plain:
schema:
type: string
default:
$ref: "#/components/responses/Error"
/plugins/endpoints/{endpointId}/more-information:
parameters:
- $ref: "#/components/parameters/endpointIdParam"
get:
tags:
- Plugins - Endpoints
summary: Get more information about how to use a given endpoint
description: |
More information about the endpoint.
User must be authenticated.
operationId: getEndpointMoreInformation
responses:
"200":
description: More information of the endpoint
content:
application/json:
schema:
$ref: "#/components/schemas/MoreInformation"
default:
$ref: "#/components/responses/Error"
/plugins/endpoints/{endpointId}/schema:
parameters:
- $ref: "#/components/parameters/endpointIdParam"
get:
tags:
- Plugins - Endpoints
summary: Get an endpoint schema
description: |
Get the JSON schema that describes the configuration of an endpoint.
User must be authenticated.
operationId: getEndpointSchema
responses:
"200":
$ref: "#/components/responses/SchemaFormResponse"
default:
$ref: "#/components/responses/Error"
/plugins/endpoints/{endpointId}/shared-configuration-schema:
parameters:
- $ref: "#/components/parameters/endpointIdParam"
get:
tags:
- Plugins - Endpoints
summary: Get an endpoint shared configuration schema
description: |
Get an endpoint shared configuration schema.
User must be authenticated.
operationId: getEndpointSharedConfigurationSchema
responses:
"200":
$ref: "#/components/responses/SchemaFormResponse"
default:
$ref: "#/components/responses/Error"
# Plugins - Entrypoints
/plugins/entrypoints:
get:
tags:
- Plugins - Entrypoints
summary: Get available entrypoints on the platform
description: |
Get available entrypoint types on the platform.
User must be authenticated.
operationId: getEntrypoints
responses:
"200":
description: List of Entrypoints.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ConnectorPlugin"
default:
$ref: "#/components/responses/Error"
/plugins/entrypoints/{entrypointId}:
parameters:
- $ref: "#/components/parameters/entrypointIdParam"
get:
tags:
- Plugins - Entrypoints
summary: Get an entrypoint
description: |
Get an entrypoint type.
User must be authenticated.
operationId: getEntrypoint
responses:
"200":
description: Entrypoint
content:
application/json:
schema:
$ref: "#/components/schemas/ConnectorPlugin"
default:
$ref: "#/components/responses/Error"
/plugins/entrypoints/{entrypointId}/documentation:
parameters:
- $ref: "#/components/parameters/entrypointIdParam"
get:
tags:
- Plugins - Entrypoints
summary: Get an entrypoint documentation
description: |
Get the documentation of an entrypoint.
User must be authenticated.
operationId: getEntrypointDocumentation
responses:
"200":
description: Documentation of the entrypoint
content:
text/plain:
schema:
type: string
default:
$ref: "#/components/responses/Error"
/plugins/entrypoints/{entrypointId}/more-information:
parameters:
- $ref: "#/components/parameters/entrypointIdParam"
get:
tags:
- Plugins - Entrypoints
summary: Get more information about how to use a given entrypoint
description: |
More information about the entrypoint.
User must be authenticated.
operationId: getEntrypointMoreInformation
responses:
"200":
description: More information of the entrypoint
content:
application/json:
schema:
$ref: "#/components/schemas/MoreInformation"
default:
$ref: "#/components/responses/Error"
/plugins/entrypoints/{entrypointId}/schema:
parameters:
- $ref: "#/components/parameters/entrypointIdParam"
get:
tags:
- Plugins - Entrypoints
summary: Get an entrypoint schema
description: |
Get the JSON schema that describes the configuration of an entrypoint.
User must be authenticated.
operationId: getEntrypointSchema
responses:
"200":
$ref: "#/components/responses/SchemaFormResponse"
default:
$ref: "#/components/responses/Error"
/plugins/entrypoints/{entrypointId}/subscription-schema:
parameters:
- $ref: "#/components/parameters/entrypointIdParam"
get:
parameters:
- name: display
in: query
description: Display the schema in a specific format..
required: false
schema:
type: string
default: gio-form-json-schema
enum:
- gv-schema-form
- gio-form-json-schema
tags:
- Plugins - Entrypoints
summary: Get an entrypoint subscription schema
description: |
Get the JSON schema that describes the subscription to a given entrypoint.
User must be authenticated.
operationId: getEntrypointSubscriptionSchema
responses:
"200":
$ref: "#/components/responses/SchemaFormResponse"
default:
$ref: "#/components/responses/Error"
# Plugins - Policies
/plugins/policies:
get:
tags:
- Plugins - Policies
summary: Get available policies on the platform
description: |
Get available policies on the platform.
User must be authenticated.
operationId: getPolicies
responses:
"200":
description: List of Policies.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PolicyPlugin"
default:
$ref: "#/components/responses/Error"
/plugins/policies/{policyId}:
parameters:
- $ref: "#/components/parameters/policyIdParam"
get:
tags:
- Plugins - Policies
summary: Get a policy
description: |
Get a policy.
User must be authenticated.
operationId: getPolicy
responses:
"200":
description: Policy
content:
application/json:
schema:
$ref: "#/components/schemas/PolicyPlugin"
default:
$ref: "#/components/responses/Error"
/plugins/policies/{policyId}/documentation:
parameters:
- $ref: "#/components/parameters/policyIdParam"
get:
tags:
- Plugins - Policies
summary: Get a policy documentation
description: |
Get the documentation of a policy.
User must be authenticated.
operationId: getPolicyDocumentation
responses:
"200":
description: Documentation of the entrypoint
content:
text/plain:
schema:
type: string
default:
$ref: "#/components/responses/Error"
/plugins/policies/{policyId}/schema:
parameters:
- $ref: "#/components/parameters/policyIdParam"
get:
parameters:
- name: display
in: query
description: Display the schema in a specific format..
required: false
schema:
type: string
default: gio-form-json-schema
enum:
- gv-schema-form
- gio-form-json-schema
tags:
- Plugins - Policies
summary: Get a policy schema
description: |
Get the JSON schema that describes the configuration of a policy.
User must be authenticated.
operationId: getPolicySchema
responses:
"200":
$ref: "#/components/responses/SchemaFormResponse"
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: ApiV1
V2: ApiV2
V4: 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 ids associated with this API.
example:
- 6c530064-0b2c-4004-9300-640b2ce0047b
- 12559b64-0b2c-4004-9300-640b2ce0047b
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"
discriminator:
propertyName: definitionVersion
mapping:
V1: ApiV1
V2: ApiV2
V4: ApiV4
required:
- definitionVersion
ApiV1:
type: object
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
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
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
CreateApi:
oneOf:
- $ref: "#/components/schemas/CreateApiV2"
- $ref: "#/components/schemas/CreateApiV4"
discriminator:
propertyName: definitionVersion
mapping:
V2: CreateApiV2
V4: 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: CreateApiV2
V4: CreateApiV4
CreateApiV2:
type: object
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
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]
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: UpdateApiV2
V4: 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 associated with this API.
example:
- 6c530064-0b2c-4004-9300-640b2ce0047b
- 12559b64-0b2c-4004-9300-640b2ce0047b
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: UpdateApiV2
V4: UpdateApiV4
UpdateApiV2:
type: object
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
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
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
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'}
ConnectorFeature:
type: string
description: A feature used by a connector
example: LIMIT
enum:
- LIMIT
- RESUME
- DLQ
ConnectorMode:
type: string
description: A mode used by a connector
example: SUBSCRIBE
enum:
- SUBSCRIBE
- PUBLISH
- REQUEST_RESPONSE
ConnectorPlugin:
type: object
allOf:
- $ref: "#/components/schemas/PlatformPlugin"
- type: object
properties:
supportedApiType:
$ref: "#/components/schemas/ApiType"
supportedModes:
type: array
items:
$ref: "#/components/schemas/ConnectorMode"
uniqueItems: true
supportedQos:
type: array
items:
$ref: "#/components/schemas/Qos"
uniqueItems: true
supportedListenerType:
$ref: "#/components/schemas/ListenerType"
availableFeatures:
type: array
items:
$ref: "#/components/schemas/ConnectorFeature"
uniqueItems: true
schema:
type: string
description: The schema of the plugin.
subscriptionSchema:
type: string
description: The subscription schema of the plugin.
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:
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
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:
type: object
description: The invalid value.
FlowV4:
type: object
properties:
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
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
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: HttpListener
TCP: TcpListener
SUBSCRIPTION: 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: HttpListener
TCP: TcpListener
SUBSCRIPTION: 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://docs.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
description: The total number of items.
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: PlanV2
V4: PlanV4
PlanV4:
type: object
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: PlanV2
V4: 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: CreatePlanV2
V4: 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: CreatePlanV2
V4: CreatePlanV4
required:
- definitionVersion
CreatePlanV2:
type: object
allOf:
- $ref: "#/components/schemas/CreateGenericPlan"
- properties:
flows:
type: array
items:
$ref: "#/components/schemas/FlowV2"
CreatePlanV4:
type: object
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: UpdatePlanV2
V4: 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: UpdatePlanV2
V4: UpdatePlanV4
required:
- definitionVersion
UpdatePlanV2:
type: object
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
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
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.
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"
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]
PolicyPlugin:
type: object
allOf:
- $ref: "#/components/schemas/PlatformPlugin"
- type: object
properties:
proxy:
type: array
uniqueItems: true
items:
$ref: "#/components/schemas/ExecutionPhase"
message:
type: array
uniqueItems: true
items:
$ref: "#/components/schemas/ExecutionPhase"
PlatformPlugin:
type: object
properties:
id:
type: string
description: Plugin's uuid.
example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
name:
type: string
description: Plugin's name.
example: My Plugin
minLength: 1
description:
type: string
description: Plugin's description.
example: I can use many characters to describe this plugin.
minLength: 1
icon:
type: string
description: Plugin's icon.
minLength: 1
category:
type: string
description: Plugin's category.
example: policy
minLength: 1
version:
type: string
description: Plugin's version.
example: 1.0.0
minLength: 1
deployed:
type: boolean
description: The deployment status of the plugin.
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:
type: string
description: Owner's type.
example: USER
enum:
- USER
- GROUP
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
Sampling:
type: object
properties:
type:
type: string
description: The type of the sampling
enum:
- PROBABILITY
- TEMPORAL
- COUNT
- QUERY
value:
type: string
description: The value of the sampling
required:
- type
Selector:
oneOf:
- $ref: "#/components/schemas/HttpSelector"
- $ref: "#/components/schemas/ChannelSelector"
- $ref: "#/components/schemas/ConditionSelector"
discriminator:
propertyName: type
mapping:
HTTP: HttpSelector
CHANNEL: ChannelSelector
CONDITION: ConditionSelector
BaseSelector:
properties:
type:
type: string
description: Selector type.
example: HTTP
enum:
- HTTP
- CHANNEL
- CONDITION
discriminator:
propertyName: type
mapping:
HTTP: HttpSelector
CHANNEL: ChannelSelector
CONDITION: 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:
allOf:
- $ref: "#/components/schemas/BaseListener"
TcpListener:
allOf:
- $ref: "#/components/schemas/BaseListener"
## 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: HttpDynamicPropertyProviderConfiguration
enabled:
type: boolean
description: Is the service enabled or not.
default: true
EndpointV2:
oneOf:
- $ref: "#/components/schemas/HttpEndpointV2"
discriminator:
propertyName: type
mapping:
http: 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: true
healthCheck:
$ref: "#/components/schemas/EndpointHealthCheckService"
discriminator:
propertyName: type
mapping:
http: HttpEndpointV2
required:
- type
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.
default: true
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
ExecutionPhase:
type: string
description: The execution phase of a policy.
example: REQUEST
enum:
- REQUEST
- RESPONSE
- MESSAGE_REQUEST
- MESSAGE_RESPONSE
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"
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.
default: true
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
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
properties:
url:
type: string
description: The url of the dynamic property provider
example: http://my-provider.com
specification:
type: object
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
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:
allOf:
- $ref: "#/components/schemas/BaseKeyStore"
- properties:
alias:
type: string
description: The alias of the key store
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
keyPassword:
type: string
description: The key password of the key store
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:
allOf:
- $ref: "#/components/schemas/BaseKeyStore"
- properties:
alias:
type: string
description: The alias of the key store
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
keyPassword:
type: string
description: The key password of the key store
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
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"
discriminator:
propertyName: type
mapping:
JKS: "#/components/schemas/JKSTrustStore"
PEM: "#/components/schemas/PEMTrustStore"
PKCS12: "#/components/schemas/PKCS12TrustStore"
NONE: "#/components/schemas/NoneTrustStore"
JKSTrustStore:
allOf:
- $ref: "#/components/schemas/BaseTrustStore"
- properties:
alias:
type: string
description: The alias of the trust store
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:
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:
allOf:
- $ref: "#/components/schemas/BaseTrustStore"
- properties:
alias:
type: string
description: The alias of the trust store
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:
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
# 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"
generalConditions:
type: boolean
description: Is the page used as General Conditions for a plan.
contentRevision:
$ref: "#/components/schemas/Revision"
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
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
# 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
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
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 #
###############################
apiExpandsParam:
name: expands
in: query
description: Expansion of data to return in APIs.
schema:
type: array
items:
type: string
enum:
- deploymentState
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"
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"
securitySchemes:
BasicAuth:
type: http
scheme: basic
CookieAuth:
type: apiKey
in: cookie
name: Auth-Graviteeio-APIM