diff --git a/src/openapi/TiMessengerInformation.yaml b/src/openapi/TiMessengerInformation.yaml index 859a77bc..5bdd3b71 100644 --- a/src/openapi/TiMessengerInformation.yaml +++ b/src/openapi/TiMessengerInformation.yaml @@ -2,19 +2,11 @@ openapi: 3.0.3 info: title: I_TiMessengerInformation description: | - # Overview - This is a TI-Messenger REST interface that provides Informations for TI-Messenger Clients. - # Context - ## Authentication - The TI-Messenger-Client uses a Matrix-OpenID-Token from his Messenger-Service for - authentication on all REST operations. The bearer token can be obtained from the - homeserver. (POST /_matrix/client/v3/user/{userId}/openid/request_token). - TI-Messenger-Client ---> Messenger-Proxy ---> Homeserver - ## REST operations - The interface provides read informations for a TI-Messenger-Client - TI-Messenger-Client ---> Messenger-Proxy + This is a REST interface that provides information to TI-Messenger clients. - # Information + 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 @@ -36,69 +28,97 @@ servers: serverDomain: description: The domain of the server default: tobereplaced.de + tags: - name: info - description: This operation returns meta data about this interface and the status of available resources + description: "Information about this interface itself." - name: lookUpDomain - description: Operations for domain lookup + description: "Operations for domain lookup." paths: /: get: tags: - info - summary: "Get information about the interface" - description: Returns the meta data of this interface. - operationId: getInfo + summary: "Retrieve metadata about this interface." responses: "200": - description: OK + description: "OK" content: application/json: schema: $ref: "#/components/schemas/InfoObject" "403": $ref: "#/components/responses/Forbidden" - default: - $ref: "#/components/responses/DefaultResponse" /v1/domain/findByIk: - parameters: - - in: query - name: ikNumber - description: "IK number to lookup the domain for." - required: true - schema: - type: string get: tags: - lookUpDomain - summary: "Find domain by IK number" - description: "Returns the domain that hosts users which belong to the given IK number." - operationId: getDomain + summary: "Resolve an IK number to the associated TI-Messenger domain." + parameters: + - in: query + name: ikNumber + description: "IK number to look up." + required: true + schema: + type: string responses: "200": - description: "The domain hosting users for the given ik number." + description: "OK" content: application/json: schema: - type: string - description: "the domain for the given ik number" - example: "gematiker-kk.de" + type: object + required: + - domain + properties: + domain: + type: string + description: "The TI-Messenger domain for the given IK number." + example: "gematiker-kk.de" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - default: - $ref: "#/components/responses/DefaultResponse" + + /v1/domain/isInsurance: + get: + tags: + - lookUpDomain + summary: "Check whether a TI-Messenger domain represents an insurance." + parameters: + - in: query + name: domain + description: "The domain 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 domain represents an insurance or `false` otherwise." + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" # Descriptions of common components components: responses: DefaultResponse: - description: "The default error response" + description: "Default error response." content: application/json: schema: @@ -126,7 +146,6 @@ components: schemas: InfoObject: - description: "" required: - title - version @@ -135,29 +154,28 @@ components: properties: title: type: string - description: "Der Titel der Anwendung" + description: "The service's title." example: "Contact Information API des TI-Messengers" description: type: string - description: "Short description of the application" + description: "Short description of the service." example: "Contact Information API des TI-Messengers. Betreiber: " contact: type: string - description: "Kontaktinformationen des Betreibers" + description: "Contact information of the operator." version: type: string - description: "Version der implementierten TiMessengerContactInformation.yaml" + description: "Version of the `TiMessengerContactInformation.yaml` interface." example: "1.0.0" Error: - description: "Default error object with information about the occurred error" type: object properties: errorCode: - description: "a code identifying this error" + description: "A code identifying this error." type: string errorMessage: - description: "a readable message describing the error" + description: "A readable message describing the error." type: string required: - errorCode