From 4c8032a4e0d323d9d68a369ed8c8cd338b2875e0 Mon Sep 17 00:00:00 2001 From: Max Martens Date: Wed, 30 Apr 2025 12:32:31 +0200 Subject: [PATCH] TP PAD Swagger with only final endpoints incouded --- src/openapi/apim/TP-PAD.yaml | 299 +++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 src/openapi/apim/TP-PAD.yaml diff --git a/src/openapi/apim/TP-PAD.yaml b/src/openapi/apim/TP-PAD.yaml new file mode 100644 index 0000000..2e70980 --- /dev/null +++ b/src/openapi/apim/TP-PAD.yaml @@ -0,0 +1,299 @@ +openapi: 3.0.1 +info: + title: Personal Account Data (PAD) APIs for TouchPoint + description: >- + These APIs connect directly to the PADP APIs in GBO APIM and are implemented in Logic Apps + in the Integration Layer. + version: '1.0' +servers: + - url: https://api.integratielaag.nl/abt/touchpoint/1.0 + description: API ABT GBO APIM +tags: + - name: Personal Data APIs for TouchPoint + description: Personal Data APIs for TouchPoint, no Service Engine in between! +paths: + /personal-data/{xtat}: + post: + tags: + - Personal Data APIs for TouchPoint + summary: Add the supplied Personal Data to the given xTAT (that should not contain any Personal Data yet). + description: |- + - The given xTAT should not contain any Personal Data yet (the PATCH endpoint should be used in that case) - if the given xTAT already contains Personal Data, an error is thrown; + - The given e-mail address will be used for future OTP challenges to manage the Personal Data in the future - this e-mail adress should therefore be validated; + - If the e-mail address is not yet validated by other means (e.g. the e-mail address is used for login, or is entered twice to prevent typos), an OTP challenge for the e-mail address should be triggered and supplied to this endpoint; + - xTAT and e-mail address are always required, for the Personal Data it is allowed to supply any subset, or all three data attributes; + - Each of the three data attributes is validated - for the requirements per attribute, see the descriptions in the request details below; + - If any attribute fails validation, none of the attributes will be added to the xTAT. + operationId: CreatePersonalData + parameters: + - name: xtat + in: path + required: true + example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d' + schema: + type: string + format: uuid + requestBody: + content: + multipart/form-data: + schema: + type: object + required: + - email + properties: + email: + type: string + format: email + description: Email address to be used for OTP challenges to prove ownership and manage the Personal Data in the future + example: 8Z9dG@example.com + otp: + type: string + pattern: ^[0-9]{6}$ + description: OTP is optional, should be supplied if the e-mail address is not yet validated by other means (e.g. the e-mail address is used for login, or is entered twice to prevent typo's) + example: "053395" + name: + type: string + description: Should consist of at least two words (first name and last name) + example: John Doe + birthDate: + type: string + format: date + description: Should be a date between 1900-01-01 and today, in the format `YYYY-MM-DD` + example: 2000-01-01 + photo: + type: string + description: Should be a JPG image, with a filesize of max. 512KB and resolution between 520x520 and 720x720 pixels + format: binary + encoding: + photo: + contentType: image/jpeg + responses: + '201': + description: Created + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + get: + tags: + - Personal Data APIs for TouchPoint + summary: Retrieve the decrypted Personal Data for the given xTAT, using the OTP for verification of ownership. + description: OTP challenge is required to retrieve the Personal Data. + operationId: GetDecryptedPersonalData + parameters: + - name: xtat + in: path + required: true + schema: + type: string + format: uuid + example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d' + - name: otp + in: query + required: true + description: OTP challenge code that the token owner received in their e-mail inbox. OTP is always required for managing existing Personal Data. + schema: + type: string + pattern: ^[0-9]{6}$ + example: "053395" + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DecryptedPersonalData' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + patch: + tags: + - Personal Data APIs for TouchPoint + summary: Update the supplied personal data for the given xTAT, using the OTP for verification of ownership. + description: This is a PATCH call, so only the personal data that the user desires to change need to be supplied. Integration layer supplements with any other existing personal data to be able to call GBO (PUT call). + operationId: UpdatePersonalData + parameters: + - name: xtat + in: path + required: true + schema: + type: string + format: uuid + example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d' + requestBody: + content: + multipart/form-data: + schema: + type: object + required: + - otp + properties: + otp: + type: string + pattern: ^[0-9]{6}$ + description: OTP challenge code that the token owner received in their e-mail inbox. OTP is always required for managing existing Personal Data. + example: "053395" + name: + type: string + description: Should consist of at least two words (first name and last name) + example: John Doe + birthDate: + type: string + format: date + description: Should be a date between 1900-01-01 and today, in the format `YYYY-MM-DD` + example: 2000-01-01 + photo: + type: string + description: Should be a JPG image, with a filesize of max. 512KB and resolution between 520x520 and 720x720 pixels + format: binary + encoding: + photo: + contentType: image/jpeg + responses: + '200': + description: OK + /personal-data/generate-otp: + get: + tags: + - Personal Data APIs for TouchPoint + summary: Trigger OTP email for the given xTAT or e-mail address, to prove ownership + operationId: GenerateOtp + description: |- + Generate an OTP challenge e-mail to prove ownership of the given e-mail address or xTAT.\ + Only one type of parameter can be supplied, either xtat or email. When both are supplied, an error is thrown. + parameters: + - name: xtat + in: query + required: false + schema: + type: string + format: uuid + example: 'c3a6c0f2-3b6a-4b9a-9c5d-5d9c6b3a4c5d' + - name: email + in: query + required: false + schema: + type: string + format: email + example: 'sV4yj@example.com' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/OtpResponse' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' +components: + schemas: + DecryptedData: + type: object + properties: + name: + type: string + nullable: true + birthdate: + type: string + nullable: true + photo: + type: string + description: Base64 encoded photo + format: byte + nullable: true + additionalProperties: false + DecryptedPersonalData: + type: object + properties: + decryptedData: + $ref: '#/components/schemas/DecryptedData' + additionalProperties: false + Error: + type: object + properties: + code: + type: string + nullable: true + data: + type: array + items: + type: string + nullable: true + message: + type: string + nullable: true + additionalProperties: false + ErrorResponse: + type: object + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Error' + nullable: true + exceptionClassName: + type: string + nullable: true + exceptionStackTrace: + type: string + nullable: true + additionalProperties: false + Metadata: + type: object + properties: + encryptedEphemeralKey: + type: string + nullable: true + additionalProperties: false + OtpResponse: + type: object + properties: + maskedEmailAddress: + type: string + nullable: true + additionalProperties: false \ No newline at end of file