TARDIS Discovery Application API

# Copyright 2025 Deutsche Telekom IT GmbH
#
# SPDX-License-Identifier: Apache-2.0

openapi: 3.0.3
info:
  title: Application Api
  description: >-
    API of the TARDIS control plane. With this API, you can manage your
    Applications.

    This is a **read-only** API. You can only read the resources. 

    For creating and updating resources, you may use the Rover-API.


    **Important:** 

    - You may use this API by subscribing to it by using the usual process. 

    You **do not** need to add `scopes` as the default scope is set to
    `tardis:user:read`.

    If you require more permissions, please contact the TARDIS team.


    - This is a Team-API and may be used by any team using TARDIS. 

    In the future, you can simply use your Team-credentials to access this API.
  contact:
    name: TARDIS
    url: https://developer.telekom.de/docs/src/tardis_customer_handbook/support/
    email: FMB_TARDIS_Support@telekom.de
  version: 2.0.0
  x-api-category: TARDIS
servers:
  - url: https://api.telekom.de/application/v2
security:
  - OAuth2:
      - tardis:admin:all
tags:
  - name: Application
    description: Manage applications
paths:
  /applications:
    get:
      tags:
        - Application
      summary: Find all Applications
      description: Find all Applications
      operationId: getAllApplications
      parameters:
        - $ref: '#/components/parameters/Icto'
        - $ref: '#/components/parameters/Apid'
        - $ref: '#/components/parameters/Psiid'
        - $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/ApplicationListResponse'
        '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:user:obfuscated
            - 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:
        - Application
      summary: Create an Application
      operationId: createApplication
      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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreateRequest'
      responses:
        '202':
          description: ACCEPTED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationResponse'
        '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}:
    get:
      tags:
        - Application
      summary: Find an existing Application
      description: Find an existing Application
      operationId: getApplication
      parameters:
        - $ref: 'common.yaml#/components/parameters/ApplicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationResponse'
        '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:user:obfuscated
            - 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:
        - Application
      summary: Update an existing Application
      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: updateApplication
      parameters:
        - $ref: 'common.yaml#/components/parameters/ApplicationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdateRequest'
      responses:
        '202':
          description: ACCEPTED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationResponse'
        '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:
        - Application
      summary: Delete an Application
      description: Delete an application - all ApiSubscriptions are deleted as well
      operationId: deleteApplication
      parameters:
        - $ref: 'common.yaml#/components/parameters/ApplicationId'
      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}/status:
    get:
      tags:
        - Application
      summary: Find an existing Application and return its status
      description: Find an existing Application and return its status
      operationId: getApplicationStatus
      parameters:
        - $ref: 'common.yaml#/components/parameters/ApplicationId'
      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
components:
  parameters:
    Icto:
      name: icto
      in: query
      description: Filter by icto
      required: false
      schema:
        type: string
    Apid:
      name: apid
      in: query
      description: Filter by apid
      required: false
      schema:
        type: string
    Psiid:
      name: psiid
      in: query
      description: Filter by psiid (pattern configurable via PSIID_PATTERN env var)
      required: false
      schema:
        type: string
  schemas:
    Application:
      type: object
      properties:
        id:
          type: string
          example: hub42--team2--myapp
          readOnly: true
        name:
          description: 'allowed characters: [a-z],[0-9],[-]'
          type: string
          pattern: '[a-z0-9-]+'
          example: myapp
        team:
          $ref: '#/components/schemas/Team'
        zone:
          type: string
          example: aws
        icto:
          type: string
          pattern: icto-[0-9]{5}
          example: icto-12345
        apid:
          type: string
          pattern: '^AP-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$'
          example: AP-12AB-34AB-56AB
        psiid:
          type: string
          description: PSI identifier (pattern configurable via PSIID_PATTERN env var, default ^PSI-[0-9]{6}$)
          example: PSI-123456
        status:
          $ref: 'common.yaml#/components/schemas/Status'
        security:
          $ref: '#/components/schemas/Security'
    ApplicationCreateRequest:
      required:
        - hub
        - team
        - name
        - zone
      type: object
      allOf:
        - $ref: '#/components/schemas/Application'
    ApplicationUpdateRequest:
      required:
        - team
        - zone
      type: object
      properties:
        team:
          $ref: '#/components/schemas/Team'
        zone:
          type: string
          example: aws
        icto:
          type: string
          pattern: icto-[0-9]{5}
          example: icto-12345
        apid:
          type: string
          pattern: '^AP-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$'
          example: AP-12AB-34AB-56AB
        psiid:
          type: string
          description: PSI identifier (pattern configurable via PSIID_PATTERN env var, default ^PSI-[0-9]{6}$)
          example: PSI-123456
    ApplicationResponse:
      type: object
      readOnly: true
      required:
        - id
        - hub
        - team
        - name
        - zone
      allOf:
        - $ref: '#/components/schemas/Application'
    ApplicationListResponse:
      type: object
      properties:
        paging:
          $ref: 'common.yaml#/components/schemas/Paging'
        _links:
          $ref: 'common.yaml#/components/schemas/Links'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationResponse'
    Team:
      type: object
      required:
        - hub
        - name
        - email
        - category
      description: >-
        Team is a group of people who are responsible for the application. The
        team is used for notifications and access control.
      properties:
        hub:
          type: string
          description: 'allowed characters: [a-z],[0-9],[-]'
          pattern: '[a-z0-9-]+'
          example: eni
        name:
          type: string
          description: 'allowed characters: [a-z],[0-9],[-]'
          pattern: '[a-z0-9-]+'
          example: hyperion
        email:
          type: string
          readOnly: true
          description: contact email address of the team
          format: email
        category:
          type: string
          readOnly: true
          example: CUSTOMER
    Security:
      type: object
      required:
        - ipRestrictions
      description: >-
        Contains information related to security configuration like IP
        restrictions etc.
      properties:
        ipRestrictions:
          $ref: '#/components/schemas/IpRestrictions'
    IpRestrictions:
      type: object
      description: >-
        A list of allowed IP addresses that will be used to consume APIs this
        application is subscribed to.  The IP addresses need to be in a valid
        CIDR notation. For example 125.5.89.20 or 160.77.58.30/16.
      properties:
        allow:
          type: array
          items:
            type: string