openapi: 3.0.3
info:
  title: I_TiMessengerInformation
  description: |
    This is a REST interface that provides information to TI-Messenger clients.

    The client uses a Matrix-OpenID-Token for authentication on all REST
    operations. The bearer token can be obtained from the homeserver via
    POST /_matrix/client/v3/user/{userId}/openid/request_token).
  version: 1.0.0
  ### 1.0.0
  # - initial version
  contact:
    name: gematik GmbH
    email: software-development@gematik.de
    url: "https://www.gematik.de"
  license:
    name: Apache 2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0"

externalDocs:
  description: TI-Messenger-API
  url: https://github.com/gematik/api-ti-messenger

servers:
  - url: https://{server}/tim-information
    variables:
      server:
        description: "The server hosting this interface."
        default: tobereplaced.de

tags:
  - name: info
    description: "Information about this interface itself."
  - name: lookUpServer
    description: "Operations for server lookup."

paths:
  /:
    get:
      tags:
        - info
      summary: "Retrieve metadata about this interface."
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoObject"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/server/findByIk:
    get:
      tags:
        - lookUpServer
      summary: "Resolve an IK number to the associated TI-Messenger server name."
      parameters:
        - in: query
          name: ikNumber
          description: "IK number to look up."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
                required:
                  - serverName
                properties:
                  serverName:
                    type: string
                    description: "The TI-Messenger server name for the given IK number."
                    example: "gematiker-kk.de"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/server/isInsurance:
    get:
      tags:
        - lookUpServer
      summary: "Check whether a TI-Messenger server name represents an insurance."
      parameters:
        - in: query
          name: serverName
          description: "The server name to query."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
                required:
                  - isInsurance
                properties:
                  isInsurance:
                    type: boolean
                    description: "`true` if the server name represents an insurance or `false` otherwise."
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

# Descriptions of common components
components:
  responses:
    NotFound:
      description: "The specified resource was not found"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: "Unauthorized"
    Forbidden:
      description: "Forbidden - you are not allowed to do this"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequest:
      description: "Bad Request"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    InfoObject:
      required:
        - title
        - version
      readOnly: true
      type: object
      properties:
        title:
          type: string
          description: "The service's title."
          example: "Contact Information API des TI-Messengers"
        description:
          type: string
          description: "Short description of the service."
          example: "Contact Information API des TI-Messengers. Betreiber: <Betreibername>"
        contact:
          type: string
          description: "Contact information of the operator."
        version:
          type: string
          description: "Version of the `TiMessengerContactInformation.yaml` interface."
          example: "1.0.0"

    Error:
      type: object
      properties:
        errorCode:
          description: "A code identifying this error."
          type: string
        errorMessage:
          description: "A readable message describing the error."
          type: string
      required:
        - errorCode
        - errorMessage

  securitySchemes:
    bearerMatrixOpenIdTokenAuth: # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT # optional, arbitrary value for documentation purposes

# the security applies to all operations
security:
  - bearerMatrixOpenIdTokenAuth: [] # use the same name as above