With an ApiExposure you can define and API you want to expose on TARDIS, to provide it to other consumers. It is only possible to expose the entire API. It is not possible to expose a single resource. Therefore, every exposure needs the API Base Path which you can find in the Open API Specification File of your API and the upstream URL.
openapi: 3.0.1
info:
title: Controlplane Api ApiChangelog ApiExposure API
description: API of the TARDIS control plane. With this API configuration connectivity between different Tardis instances in ensured
contact:
name: TARDIS
url: https://developer.telekom.de/docs/src/tardis_customer_handbook/support/
email: FMB_TARDIS_Support@telekom.de
version: 1.0.0
x-api-category: TARDIS
x-vendor: false
servers:
- url: https://api.telekom.de/controlplane/v1
tags:
- name: ApiExposure
description: 'With an ApiExposure you can define and API you want to expose on TARDIS,
to provide it to other consumers. It is only possible to expose the entire
API. It is not possible to expose a single resource. Therefore, every
exposure needs the API Base Path which you can find in the Open API
Specification File of your API and the upstream URL.
'
paths:
/applications/{applicationId}/apiexposures:
get:
tags:
- ApiExposure
summary: Find all ApiExposures
description: Find all ApiExposures of this application
operationId: getAllApiExposures
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
- $ref: common.yaml#/components/parameters/Limit
- $ref: common.yaml#/components/parameters/Offset
- $ref: common.yaml#/components/parameters/Sort
responses:
'200':
description: OK
headers:
X-Total-Count:
$ref: common.yaml#/components/headers/XTotalCount
X-Result-Count:
$ref: common.yaml#/components/headers/XResultCount
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExposureListResponse'
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:admin:read
- tardis:admin:obfuscated
- tardis:supervisor:read
- tardis:hub:all
- tardis:hub:read
- tardis:hub:obfuscated
- tardis:team:all
- tardis:team:read
- tardis:team:obfuscated
- tardis:user:all
- tardis:user:read
- tardis:user:obfuscated
post:
deprecated: true
tags:
- ApiExposure
summary: Create an ApiExposures
description: 'Creating and updating resources is asynchronous, which is why the status
is given as an answer to a POST/PUT request, since it is possible that
the resource to be created has not yet been processed at the time the
response is created. If the status after creation is in state
"Processing", the resource must be queried with GET to see whether it
was created successfully or whether errors/warnings are written in the
status. If the creation/update is incorrect, the processing status will
be set to blocked. Otherwise to "failed". Status 201 means, that we
accepted the request and there are no syntactic or semantic errors, but
there can occur failures in the after processing. That will be shown in
the status if you request the appropriate resource.
'
operationId: createApiExposure
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExposureCreateRequest'
responses:
'202':
description: ACCEPTED
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExposureResponse'
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:hub:all
- tardis:team:all
- tardis:user:all
/applications/{applicationId}/apiexposures/{apiExposureName}:
get:
tags:
- ApiExposure
summary: Find an existing ApiExposure
description: Find an existing ApiExposure
operationId: getApiExposure
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
- name: apiExposureName
description: The name of the ApiExposure
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExposureResponse'
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'404':
$ref: common.yaml#/components/responses/NotFound
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:admin:read
- tardis:admin:obfuscated
- tardis:supervisor:read
- tardis:hub:all
- tardis:hub:read
- tardis:hub:obfuscated
- tardis:team:all
- tardis:team:read
- tardis:team:obfuscated
- tardis:user:all
- tardis:user:read
- tardis:user:obfuscated
put:
deprecated: true
tags:
- ApiExposure
summary: Update an existing ApiExposure
description: 'Creating and updating resources is asynchronous, which is why the status
is given as an answer to a POST/PUT request, since it is possible that
the resource to be created has not yet been processed at the time the
response is created. If the status after creation is in state
"Processing", the resource must be queried with GET to see whether it
was created successfully or whether errors/warnings are written in the
status. If the creation/update is incorrect, the processing status will
be set to blocked. Otherwise to "failed". Status 201 means, that we
accepted the request and there are no syntactic or semantic errors, but
there can occur failures in the after processing. That will be shown in
the status if you request the appropriate resource.
'
operationId: updateApiExposure
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
- name: apiExposureName
in: path
description: The name of the ApiExposure
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExposureUpdateRequest'
responses:
'202':
description: ACCEPTED
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExposureResponse'
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'404':
$ref: common.yaml#/components/responses/NotFound
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:hub:all
- tardis:team:all
- tardis:user:all
delete:
deprecated: true
tags:
- ApiExposure
summary: Delete an ApiExposure
description: Delete an ApiExposure
operationId: deleteApiExposure
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
- name: apiExposureName
in: path
description: The name of the ApiExposure
required: true
schema:
type: string
responses:
'204':
description: DELETED
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'404':
$ref: common.yaml#/components/responses/NotFound
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:hub:all
- tardis:team:all
- tardis:user:all
/applications/{applicationId}/apiexposures/{apiExposureName}/status:
get:
tags:
- ApiExposure
summary: Find an existing ApiExposure and return its status
description: Find an existing ApiExposure and return its status
operationId: getApiExposureStatus
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
- name: apiExposureName
description: The name of the ApiExposure
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: common.yaml#/components/schemas/ResourceStatusResponse
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'404':
$ref: common.yaml#/components/responses/NotFound
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:admin:read
- tardis:admin:obfuscated
- tardis:supervisor:read
- tardis:hub:all
- tardis:hub:read
- tardis:hub:obfuscated
- tardis:team:all
- tardis:team:read
- tardis:team:obfuscated
- tardis:user:all
- tardis:user:read
- tardis:user:obfuscated
/applications/{applicationId}/apiexposures/{apiExposureName}/apisubscriptions:
get:
tags:
- ApiExposure
summary: Find all ApiSubscriptions of this ApiExposure
description: Find all ApiSubscriptions of this ApiExposure
operationId: getAllExposureApiSubscriptions
parameters:
- $ref: common.yaml#/components/parameters/ApplicationId
- name: apiExposureName
description: The name of the ApiExposure
in: path
required: true
schema:
type: string
- $ref: common.yaml#/components/parameters/Limit
- $ref: common.yaml#/components/parameters/Offset
- $ref: common.yaml#/components/parameters/Sort
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiSubscriptionListResponse'
'400':
$ref: common.yaml#/components/responses/BadRequest
'401':
$ref: common.yaml#/components/responses/Unauthorized
'403':
$ref: common.yaml#/components/responses/Forbidden
'415':
$ref: common.yaml#/components/responses/UnsupportedMediaType
'500':
$ref: common.yaml#/components/responses/ServerError
security:
- OAuth2:
- tardis:admin:all
- tardis:admin:read
- tardis:admin:obfuscated
- tardis:supervisor:read
- tardis:hub:all
- tardis:hub:read
- tardis:hub:obfuscated
- tardis:team:all
- tardis:team:read
- tardis:team:obfuscated
- tardis:user:all
- tardis:user:read
- tardis:user:obfuscated
components:
schemas:
ApiExposure:
type: object
properties:
basePath:
type: string
pattern: ^\/[a-zA-Z0-9\/-]*$
upstream:
type: string
format: uri
variant:
type: string
description: 'Defines the type of API exposure and determines which gateway
the route should be provisioned on.
Supported values:
- null or ''DEFAULT'': Regular API exposure on Stargate gateway (backward compatible)
- ''MCP'': MCP exposure provisioned on aiGateway
- ''TELECONTEXTMCP'': MCP exposure on aiGateway with automatic Telecontext integration
'
enum:
- DEFAULT
- MCP
- TELECONTEXTMCP
example: DEFAULT
approval:
$ref: '#/components/schemas/ApprovalStrategy'
rateLimit:
$ref: '#/components/schemas/RateLimit'
visibility:
$ref: '#/components/schemas/Visibility'
security:
$ref: '#/components/schemas/SubscriberSecurity'
failover:
$ref: '#/components/schemas/ExposureFailover'
loadBalancing:
$ref: '#/components/schemas/LoadBalancing'
trustedTeams:
type: array
items:
$ref: common.yaml#/components/schemas/TeamRef
removeHeaders:
type: array
items:
type: string
ExposureFailover:
type: object
properties:
zone:
type: string
example: aws
SubscriptionFailover:
type: array
readOnly: true
items:
type: object
properties:
zone:
type: string
readOnly: true
example: aws
gatewayUrl:
type: string
readOnly: true
example: https://stargate-playground.live.dhei.telekom.de/eni/echo/v1
ApprovalStrategy:
enum:
- AUTO
- SIMPLE
- FOUREYES
type: string
SubscriberSecurity:
discriminator:
propertyName: type
mapping:
oauth2: '#/components/schemas/OAuth2'
basicAuth: '#/components/schemas/BasicAuth'
oneOf:
- $ref: '#/components/schemas/OAuth2'
- $ref: '#/components/schemas/BasicAuth'
Visibility:
enum:
- ENTERPRISE
- WORLD
- ZONE
type: string
ApiExposureResponse:
type: object
readOnly: true
required:
- name
- zone
- basePath
- upstream
- visibility
allOf:
- $ref: '#/components/schemas/ApiExposure'
- properties:
name:
type: string
readOnly: true
example: eni-heartbeat-v1
zone:
type: string
readOnly: true
status:
$ref: common.yaml#/components/schemas/Status
ApiSubscriptionListResponse:
properties:
paging:
$ref: common.yaml#/components/schemas/Paging
_links:
$ref: common.yaml#/components/schemas/Links
items:
type: array
items:
$ref: '#/components/schemas/ApiSubscriptionResponse'
OAuth2:
type: object
required:
- type
properties:
type:
type: string
enum:
- oauth2
tokenEndpoint:
type: string
clientId:
type: string
clientSecret:
type: string
scopes:
type: array
items:
type: string
username:
type: string
password:
type: string
refreshToken:
type: string
grantType:
type: string
tokenRequest:
type: string
enum:
- body
- header
description: Specifies if the authentication data should be sent to the external IDP via headers or in the body of the request
Server:
type: object
readOnly: true
properties:
upstream:
type: string
readOnly: true
weight:
type: integer
readOnly: true
ApiExposureUpdateRequest:
type: object
required:
- upstream
- basePath
- approval
- visibility
allOf:
- $ref: '#/components/schemas/ApiExposure'
ApiSubscription:
type: object
properties:
basePath:
description: Must match pattern ^\/[a-zA-Z0-9\/-]*$
type: string
example: /my-hub/my-app/v1
pattern: ^\/[a-zA-Z0-9\/-]*$
security:
$ref: '#/components/schemas/SubscriberSecurity'
ApiSubscriptionResponse:
type: object
readOnly: true
allOf:
- $ref: '#/components/schemas/ApiSubscription'
- properties:
name:
type: string
readOnly: true
example: eni-echo-v1
zone:
type: string
readOnly: true
gatewayUrl:
type: string
readOnly: true
example: https://stargate-playground.live.dhei.telekom.de/eni/echo/v1
status:
$ref: common.yaml#/components/schemas/Status
application:
$ref: common.yaml#/components/schemas/ApplicationRef
team:
$ref: common.yaml#/components/schemas/TeamRef
approval:
$ref: '#/components/schemas/Approval'
failover:
$ref: '#/components/schemas/SubscriptionFailover'
RateLimit:
type: object
properties:
second:
format: int32
type: integer
minute:
format: int32
type: integer
hour:
format: int32
type: integer
faultTolerant:
type: boolean
hideClientHeaders:
type: boolean
BasicAuth:
type: object
required:
- type
- username
- password
properties:
type:
type: string
enum:
- basicAuth
username:
type: string
password:
type: string
ApiExposureCreateRequest:
type: object
required:
- basePath
- upstream
- visibility
allOf:
- $ref: '#/components/schemas/ApiExposure'
LoadBalancing:
type: object
readOnly: true
properties:
servers:
type: array
readOnly: true
items:
$ref: '#/components/schemas/Server'
Approval:
type: object
readOnly: true
required:
- status
- comment
properties:
status:
type: string
example: granted
comment:
type: string
example: trusted team
decider:
type: string
example: hyperion@telekom.de
timestamp:
type: string
format: date-time
example: '2022-09-28T16:05:46.384Z'
ApiExposureListResponse:
properties:
paging:
$ref: common.yaml#/components/schemas/Paging
_links:
$ref: common.yaml#/components/schemas/Links
items:
type: array
items:
$ref: '#/components/schemas/ApiExposureResponse'