From 91fba59522bb8c1a7f9bf8152fd98e6971d64d05 Mon Sep 17 00:00:00 2001 From: Lal Chandran Date: Tue, 21 Nov 2023 20:45:02 +0100 Subject: [PATCH] Upd: Endpoint descriptions and summary for service APIs Signed-off-by: Lal Chandran --- openapi/v2023.11.1/bundled.yaml | 102 +++++++----------- .../paths/configCreateIndividual.yaml | 2 +- .../paths/serviceAgreementList.yaml | 6 +- .../paths/serviceAgreementRead.yaml | 4 +- .../paths/serviceCreateIndividual.yaml | 5 +- .../serviceCreateIndividualConsentRecord.yaml | 8 +- ...teIndividualConsentRecordAndSignature.yaml | 5 +- ...iceCreateIndividualConsentRecordDraft.yaml | 10 +- ...reateIndividualConsentRecordSignature.yaml | 9 +- .../paths/serviceDeleteAllRecords.yaml | 15 ++- ...serviceListDataAgreementRecordHistory.yaml | 7 +- ...iceListDataAttributesForDataAgreement.yaml | 6 +- ...tIndividualAgreementConsentRecordList.yaml | 11 +- ...erviceListIndividualConsentRecordList.yaml | 4 +- .../paths/serviceListIndividuals.yaml | 1 + .../v2023.11.1/paths/servicePolicyRead.yaml | 6 +- .../paths/serviceReadDataSharingUi.yaml | 5 +- openapi/v2023.11.1/paths/serviceReadIdp.yaml | 5 +- .../paths/serviceReadIndividual.yaml | 7 +- .../serviceReadIndividualRecordRead.yaml | 8 +- .../paths/serviceReadOrganisation.yaml | 5 +- .../serviceReadOrganisationCoverImage.yaml | 6 +- .../paths/serviceReadOrganisationImage.yaml | 4 +- .../serviceReadOrganisationLogoImage.yaml | 2 + .../paths/serviceUpdateIndividual.yaml | 3 +- .../serviceUpdateIndividualConsentRecord.yaml | 9 +- ...pdateIndividualConsentRecordSignature.yaml | 6 +- ...erificationAgreementConsentRecordRead.yaml | 4 +- .../serviceVerificationAgreementList.yaml | 4 +- .../serviceVerificationConsentRecordList.yaml | 4 +- 30 files changed, 134 insertions(+), 139 deletions(-) diff --git a/openapi/v2023.11.1/bundled.yaml b/openapi/v2023.11.1/bundled.yaml index f42a024..49dd1b4 100644 --- a/openapi/v2023.11.1/bundled.yaml +++ b/openapi/v2023.11.1/bundled.yaml @@ -1367,7 +1367,7 @@ paths: /config/individual: post: summary: CREATE - Create individual - description: This endpoint creates an individual for an organisation in the consent block system. This is used to onboard existing or new users. + description: This endpoint creates an individual for an organisation in the consent building block. This is used to onboard existing or new users. operationId: configCreatePolicy responses: '200': @@ -2900,8 +2900,8 @@ paths: - onboard /service/organisation/coverimage: get: - summary: READ - Read organization cover image - description: Read organization cover image + summary: READ - Read organisation cover image + description: This endpoint is used to retrieve the existing cover image for the organisation. The cover image is used to display in the privacy dashboard. operationId: serviceReadOrganisationCoverImage responses: '200': @@ -2914,7 +2914,7 @@ paths: /service/organisation/logoimage: get: summary: READ - Read organisation logo image - description: Read organisation logo image + description: Read organisation logo image This endpoint is used to retrieve the existing logo image for the organisation. The logo image is used to display in the privacy dashboard as well in data sharing UIs. operationId: serviceReadOrganisationLogoImage deprecated: false responses: @@ -2926,8 +2926,8 @@ paths: - service /service/idp/open-id: get: - summary: READ - Read IdP - description: READ - Read IdP + summary: READ - Read IdP details + description: This endpoint is used to read the IdP details configured by the organisation in the consent building block. operationId: serviceReadIdp parameters: - description: Unique ID of an object @@ -2971,8 +2971,8 @@ paths: - service /service/organisation: get: - description: READ - Read organisation summary: READ - Read organisation + description: 'This endpoint is used to read the organisation information as configured by the organisation in the consent building block. This is used, for e.g., in the privacy dashboard.' operationId: serviceReadOrganisation deprecated: false responses: @@ -3011,7 +3011,7 @@ paths: /service/data-agreements: get: summary: LIST - List all active data agreements - description: LIST - List active data agreements + description: This endpoint is used to list all active data agreements by the organisation in consent building block. The results are returned with pagination. operationId: serviceAgreementList parameters: - $ref: '#/paths/~1config~1data-agreements/get/parameters/0' @@ -3040,7 +3040,7 @@ paths: '/service/data-agreement/{dataAgreementId}': get: summary: READ - Read data agreement - description: READ - Read data agreement + description: This endpoint is used to read the data agreement defined by the organisation in consent building block. operationId: serviceAgreementRead parameters: - description: Unique ID of an object @@ -3071,8 +3071,8 @@ paths: - service '/service/data-agreement/{dataAgreementId}/data-attributes': get: - summary: LIST - List all data attributes for data agreement - description: LIST - List all latest versions of data attribute associated with an DataAgreement and the presented revisionId of that DataAgreement + summary: LIST - List data attributes + description: This endpoint is used to read the data attributes defined in a particular data agreement revision. operationId: serviceAgreementDataRead parameters: - $ref: '#/paths/~1audit~1data-agreement~1%7BdataAgreementId%7D/get/parameters/0' @@ -3101,8 +3101,8 @@ paths: - service '/service/policy/{policyId}': get: - summary: READ - Read policy - description: READ - Fetch the latest version of a Policy and the presented revisionId of an associated DataAgreement + summary: READ - Read data policy + description: This endpoint is used to read latest version of data policy defined in the organisation in the consent building block. operationId: servicePolicyRead parameters: - description: Unique ID of an object @@ -3137,7 +3137,7 @@ paths: /service/verification/data-agreements: get: summary: LIST - List all consent records - description: LIST - List all consent records + description: This endpoint is used to list all consent records available for an organisation defined in the consent building block. The results are paginated. operationId: serviceVerificationAgreementList parameters: - $ref: '#/paths/~1config~1policies/get/parameters/1' @@ -3169,7 +3169,7 @@ paths: '/service/verification/consent-record/{consentRecordId}': get: summary: READ - Read latest consent record - description: READ - Read latest consent record. + description: This endpoint is used to read the latest consent record for an organisation in the consent building block. operationId: serviceVerificationAgreementConsentRecordRead parameters: - $ref: '#/paths/~1audit~1consent-record~1%7BconsentRecordId%7D/get/parameters/0' @@ -3198,7 +3198,7 @@ paths: /service/verification/consent-records: get: summary: LIST - List all consent records - description: LIST - List all consent records + description: This endpoint is used to list all consent records available for an organisation defined in the consent building block. The results are paginated. operationId: serviceVerificationConsentRecordList parameters: - $ref: '#/paths/~1config~1policies/get/parameters/1' @@ -3230,7 +3230,7 @@ paths: '/service/individual/record/data-agreement/{dataAgreementId}': post: summary: CREATE - Create consent record - description: 'CREATE - For a particular individual and a particular data agreement, create a new consent record pointing to the current revision of a given data agreement.' + description: This endpoint is used to create a consent record when an individial records their consent (e.g. in the privacy dashboard) against a data agreement. operationId: serviceCreateIndividualConsentRecord parameters: - $ref: '#/paths/~1audit~1data-agreement~1%7BdataAgreementId%7D/get/parameters/0' @@ -3254,13 +3254,9 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '1.2' - x-specification-usecase: UC-C-PIC-I-002 get: summary: READ - Read consent record - description: READ - Read consent record. There should be one unambiguous DataAgreementRecord for an Individual and an DataAgreement. + description: This endpoint is used to read a consent record for an individial for a chosen data agreement. There should be one unambiguous consent record for an individual. operationId: serviceReadIndividualRecordRead parameters: - $ref: '#/paths/~1audit~1data-agreement~1%7BdataAgreementId%7D/get/parameters/0' @@ -3281,14 +3277,10 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '' - x-specification-usecase: UC-C-PIC-I-001 /service/individual/record/consent-record/draft: post: - summary: CREATE - Create DRAFT consent record - description: CREATE - Create a DRAFT (unsaved) consent record and signature objects (without a PK) for a given dataAgreementId. + summary: CREATE - Create draft consent record + description: This endpoint is used to create a draft (unsaved) consent record and signature object (without a PKI) for a data agreement. operationId: serviceCreateIndividualConsentRecordDraft parameters: - description: An object with id individualId @@ -3328,14 +3320,10 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '1.2' - x-specification-usecase: UC-C-PIC-I-002 /service/individual/record/consent-record: post: summary: CREATE - Create consent record and signature - description: CREATE - Create a paired consent record and signature object. Returns the same objects with the PK defined. + description: This endpoint is used to create a consent record and signature object. This returns the same objects with the PK defined. operationId: serviceCreateIndividualConsentRecordAndSignature parameters: - $ref: '#/paths/~1service~1individual~1record/delete/parameters/0' @@ -3380,7 +3368,7 @@ paths: x-specification-usecase: UC-C-PIC-I-002 get: summary: LIST - List all consent records for individual - description: LIST - List all current unambiguous consent records stored for individual + description: This endpoint is used to list all consent records for an individual belonging to an organiation defined in the consent building block. operationId: serviceListIndividualConsentRecordList parameters: - $ref: '#/paths/~1config~1policies/get/parameters/1' @@ -3412,8 +3400,8 @@ paths: x-specification-usecase: UC-C-PIC-I-001 /service/individual/record: delete: - summary: DELETE - Delete all consent records for an individual - description: 'DELETE - Cascading delete operation for Right To Be Forgotten, deletes all consent records that shall not be retained and have a "forgettable" DataAgreement. May also delete an unsigned consent record, for instance in cases where the user exits the signing process.' + summary: DELETE - Delete all consent records + description: 'This endpoint is used to delete all consent records for an individual belonging to an organiation defined in the consent building block. This could be used, for example to exercise digital rights (Right to be forgotten) and deletes all consent records that shall not be retained and have a "forgettable" data agreement. This may also delete an unsigned consent record, for instance in cases where the user exits the signing process.' operationId: serviceDeleteAllRecords parameters: - in: header @@ -3431,14 +3419,10 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '' - x-specification-usecase: UC-C-PIC-I-003 '/service/individual/record/consent-record/{consentRecordId}': put: summary: UPDATE - Update consent record - description: UPDATE - Update consent record. Note that updating a signed consent record invalidates its signature. + description: This endpoint is used to update an existing consent record for a given data agreement for an organiation defined in the consent building block. Note that updating a signed consent record invalidates its earlier signature. operationId: serviceUpdateIndividualConsentRecord parameters: - $ref: '#/paths/~1audit~1consent-record~1%7BconsentRecordId%7D/get/parameters/0' @@ -3490,14 +3474,10 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '' - x-specification-usecase: UC-C-PIC-I-003 '/service/individual/record/consent-record/{consentRecordId}/signature': post: summary: CREATE - Creates blank signature - description: CREATE - Creates and returns a blank Signature object for the consent record + description: This endpoint is used to create a blank signature object for the consent record for an individual in an organiation defined in the consent building block. CREATE - Creates and returns a blank Signature object for the consent record. operationId: serviceCreateIndividualConsentRecordSignature parameters: - description: Unique ID of an object @@ -3523,13 +3503,9 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '' - x-specification-usecase: UC-Post-Partum-001-Registration_PostPartum_and_InfantCare put: summary: UPDATE - Updates signature for consent record - description: UPDATE - Updates signature for consent record. This is used to add a signature to an existing unsigned consent record. Consent BB is responsible for updating the consent record state. + description: This endpoint is used to update a signature object for the consent record for an individual in an organiation defined in the consent building block. operationId: serviceUpdateIndividualConsentRecordSignature parameters: - description: Unique ID of an object @@ -3568,8 +3544,8 @@ paths: - service '/service/individual/record/data-agreement/{dataAgreementId}/all': get: - summary: LIST - List all consent records for data agreement - description: LIST - List all consent records for data agreement + summary: LIST - List all consent records + description: This endpoint is used to list all consent records existing for a data agreement for an organisation defined in the consent building block. The response is paginated. operationId: serviceListIndividualAgreementConsentRecordList parameters: - $ref: '#/paths/~1audit~1data-agreement~1%7BdataAgreementId%7D/get/parameters/0' @@ -3596,14 +3572,10 @@ paths: - BearerAuth: [] tags: - service - x-specification-crudl-model: '' - x-specification-pii-or-sensitive: 'True' - x-specification-scenario: '' - x-specification-usecase: UC-C-PIC-I-001 /service/individual/record/consent-record/history: get: - summary: LIST - List all consent record history - description: LIST - List all consent record history + summary: LIST - List consent record history + description: This endpoint is used to list all consent record history existing for an individual in an organisation defined in the consent building block. The response is paginated. operationId: serviceListDataAgreementRecordHistory tags: - service @@ -3658,7 +3630,7 @@ paths: /service/individual: post: summary: CREATE - Create individual - description: CREATE - Creates Individual in the Consent system + description: This endpoint creates an individual for an organisation in the consent building block. This is used to onboard existing or new users. operationId: configCreatePolicy requestBody: content: @@ -3695,7 +3667,7 @@ paths: '/service/individual/{individualId}': get: summary: READ - Read individual - description: READ - Read individual in the Consent system + description: 'This endpoint is used to read the individual''s information as defined by the organisation in the consent building block. This is used in privacy dashboard where the individuals can mark their consents, sign data agreement etc.' operationId: configReadIndividual parameters: - in: path @@ -3724,7 +3696,7 @@ paths: - service put: summary: UPDATE - Update individual - description: UPDATE - Updates individual in the Consent system + description: This endpoint is used to udpated an individual for an organisation defined in the consent building block. operationId: configUpdateIndividual parameters: - in: path @@ -3767,7 +3739,7 @@ paths: /service/individuals: get: summary: LIST - List all individuals - description: LIST - lists individuals in the system + description: LIST - lists individuals in the system This endpoint is used to list all individuals in the organisation defined in the consent building block. operationId: configListIndividuals parameters: - $ref: '#/paths/~1config~1policies/get/parameters/1' @@ -3797,7 +3769,7 @@ paths: '/service/image/{imageId}': get: summary: READ - Read organisation image - description: READ - Read organisation image + description: This endpoint is used to read an organisation image as defined in the consent building block. operationId: serviceReadOrganisationImage deprecated: false responses: @@ -3810,7 +3782,7 @@ paths: /service/data-sharing: get: summary: READ - Read data sharing UI - description: READ - Read data sharing UI + description: This endpoint is used to render the data sharing UI during a data exchange as defined by a (data source) organisation in the consent building block. operationId: serviceReadDataSharingUi parameters: - name: dataAgreementId diff --git a/openapi/v2023.11.1/paths/configCreateIndividual.yaml b/openapi/v2023.11.1/paths/configCreateIndividual.yaml index 48b998b..d0dc062 100644 --- a/openapi/v2023.11.1/paths/configCreateIndividual.yaml +++ b/openapi/v2023.11.1/paths/configCreateIndividual.yaml @@ -1,7 +1,7 @@ summary: CREATE - Create individual description: This endpoint creates an individual for an organisation in the - consent block system. This is used to onboard existing or new users. + consent building block. This is used to onboard existing or new users. operationId: "configCreatePolicy" responses: "200": diff --git a/openapi/v2023.11.1/paths/serviceAgreementList.yaml b/openapi/v2023.11.1/paths/serviceAgreementList.yaml index e1e713e..ef75c4d 100644 --- a/openapi/v2023.11.1/paths/serviceAgreementList.yaml +++ b/openapi/v2023.11.1/paths/serviceAgreementList.yaml @@ -1,5 +1,7 @@ summary: LIST - List all active data agreements -description: LIST - List active data agreements +description: + This endpoint is used to list all active data agreements by the + organisation in consent building block. The results are returned with pagination. operationId: serviceAgreementList parameters: - $ref: "../parameters/revisionId.yaml" @@ -24,4 +26,4 @@ responses: security: - BearerAuth: [] tags: - - service + - service \ No newline at end of file diff --git a/openapi/v2023.11.1/paths/serviceAgreementRead.yaml b/openapi/v2023.11.1/paths/serviceAgreementRead.yaml index e15a33e..a3112a8 100644 --- a/openapi/v2023.11.1/paths/serviceAgreementRead.yaml +++ b/openapi/v2023.11.1/paths/serviceAgreementRead.yaml @@ -1,5 +1,7 @@ summary: READ - Read data agreement -description: READ - Read data agreement +description: + This endpoint is used to read the data agreement defined by the + organisation in consent building block. operationId: serviceAgreementRead parameters: - description: Unique ID of an object diff --git a/openapi/v2023.11.1/paths/serviceCreateIndividual.yaml b/openapi/v2023.11.1/paths/serviceCreateIndividual.yaml index b0446ee..81b85bd 100644 --- a/openapi/v2023.11.1/paths/serviceCreateIndividual.yaml +++ b/openapi/v2023.11.1/paths/serviceCreateIndividual.yaml @@ -1,5 +1,7 @@ summary: CREATE - Create individual -description: "CREATE - Creates Individual in the Consent system" +description: + This endpoint creates an individual for an organisation in the + consent building block. This is used to onboard existing or new users. operationId: "configCreatePolicy" requestBody: content: @@ -18,7 +20,6 @@ requestBody: responses: "200": description: "" - content: application/json: schema: diff --git a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecord.yaml b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecord.yaml index fda383b..d8d7bf6 100644 --- a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecord.yaml +++ b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecord.yaml @@ -1,7 +1,7 @@ summary: CREATE - Create consent record description: - CREATE - For a particular individual and a particular data agreement, create - a new consent record pointing to the current revision of a given data agreement. + This endpoint is used to create a consent record when an individial records + their consent (e.g. in the privacy dashboard) against a data agreement. operationId: serviceCreateIndividualConsentRecord parameters: - $ref: "../parameters/dataAgreementId.yaml" @@ -25,7 +25,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: "" -x-specification-pii-or-sensitive: "True" -x-specification-scenario: "1.2" -x-specification-usecase: UC-C-PIC-I-002 diff --git a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordAndSignature.yaml b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordAndSignature.yaml index 5265749..2d3eee2 100644 --- a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordAndSignature.yaml +++ b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordAndSignature.yaml @@ -1,6 +1,7 @@ summary: CREATE - Create consent record and signature -description: CREATE - Create a paired consent record and signature object. Returns - the same objects with the PK defined. +description: + This endpoint is used to create a consent record and signature object. This + returns the same objects with the PK defined. operationId: serviceCreateIndividualConsentRecordAndSignature parameters: - $ref: "../parameters/individualIdHeader.yaml" diff --git a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordDraft.yaml b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordDraft.yaml index d6a8753..9143153 100644 --- a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordDraft.yaml +++ b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordDraft.yaml @@ -1,7 +1,7 @@ -summary: CREATE - Create DRAFT consent record +summary: CREATE - Create draft consent record description: - CREATE - Create a DRAFT (unsaved) consent record and signature objects (without - a PK) for a given dataAgreementId. + This endpoint is used to create a draft (unsaved) consent record and signature + object (without a PKI) for a data agreement. operationId: serviceCreateIndividualConsentRecordDraft parameters: - description: An object with id individualId @@ -41,7 +41,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: "" -x-specification-pii-or-sensitive: "True" -x-specification-scenario: "1.2" -x-specification-usecase: UC-C-PIC-I-002 diff --git a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordSignature.yaml b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordSignature.yaml index 492549c..ebcd785 100644 --- a/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordSignature.yaml +++ b/openapi/v2023.11.1/paths/serviceCreateIndividualConsentRecordSignature.yaml @@ -1,5 +1,8 @@ summary: CREATE - Creates blank signature -description: CREATE - Creates and returns a blank Signature object for the consent record +description: + This endpoint is used to create a blank signature object for the consent record + for an individual in an organiation defined in the consent building block. + CREATE - Creates and returns a blank Signature object for the consent record. operationId: serviceCreateIndividualConsentRecordSignature parameters: - description: Unique ID of an object @@ -25,7 +28,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: "" -x-specification-pii-or-sensitive: "True" -x-specification-scenario: "" -x-specification-usecase: UC-Post-Partum-001-Registration_PostPartum_and_InfantCare diff --git a/openapi/v2023.11.1/paths/serviceDeleteAllRecords.yaml b/openapi/v2023.11.1/paths/serviceDeleteAllRecords.yaml index e810f09..96f765b 100644 --- a/openapi/v2023.11.1/paths/serviceDeleteAllRecords.yaml +++ b/openapi/v2023.11.1/paths/serviceDeleteAllRecords.yaml @@ -1,7 +1,10 @@ -summary: DELETE - Delete all consent records for an individual -description: DELETE - Cascading delete operation for Right To Be Forgotten, deletes - all consent records that shall not be retained and have a "forgettable" DataAgreement. - May also delete an unsigned consent record, for instance in cases where the user +summary: DELETE - Delete all consent records +description: + This endpoint is used to delete all consent records for an individual belonging + to an organiation defined in the consent building block. This could be used, for + example to exercise digital rights (Right to be forgotten) and deletes + all consent records that shall not be retained and have a "forgettable" data agreement. + This may also delete an unsigned consent record, for instance in cases where the user exits the signing process. operationId: serviceDeleteAllRecords parameters: @@ -15,7 +18,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: '' -x-specification-pii-or-sensitive: 'True' -x-specification-scenario: '' -x-specification-usecase: UC-C-PIC-I-003 diff --git a/openapi/v2023.11.1/paths/serviceListDataAgreementRecordHistory.yaml b/openapi/v2023.11.1/paths/serviceListDataAgreementRecordHistory.yaml index a41541c..685d911 100644 --- a/openapi/v2023.11.1/paths/serviceListDataAgreementRecordHistory.yaml +++ b/openapi/v2023.11.1/paths/serviceListDataAgreementRecordHistory.yaml @@ -1,5 +1,8 @@ -summary: LIST - List all consent record history -description: LIST - List all consent record history +summary: LIST - List consent record history +description: + This endpoint is used to list all consent record history existing for an + individual in an organisation defined in the consent building block. The + response is paginated. operationId: serviceListDataAgreementRecordHistory tags: - service diff --git a/openapi/v2023.11.1/paths/serviceListDataAttributesForDataAgreement.yaml b/openapi/v2023.11.1/paths/serviceListDataAttributesForDataAgreement.yaml index 0ebb444..d635439 100644 --- a/openapi/v2023.11.1/paths/serviceListDataAttributesForDataAgreement.yaml +++ b/openapi/v2023.11.1/paths/serviceListDataAttributesForDataAgreement.yaml @@ -1,5 +1,7 @@ -summary: LIST - List all data attributes for data agreement -description: LIST - List all latest versions of data attribute associated with an DataAgreement and the presented revisionId of that DataAgreement +summary: LIST - List data attributes +description: + This endpoint is used to read the data attributes defined in a particular data agreement + revision. operationId: serviceAgreementDataRead parameters: - $ref: "../parameters/dataAgreementId.yaml" diff --git a/openapi/v2023.11.1/paths/serviceListIndividualAgreementConsentRecordList.yaml b/openapi/v2023.11.1/paths/serviceListIndividualAgreementConsentRecordList.yaml index d11e91b..fafe48c 100644 --- a/openapi/v2023.11.1/paths/serviceListIndividualAgreementConsentRecordList.yaml +++ b/openapi/v2023.11.1/paths/serviceListIndividualAgreementConsentRecordList.yaml @@ -1,5 +1,8 @@ -summary: LIST - List all consent records for data agreement -description: LIST - List all consent records for data agreement +summary: LIST - List all consent records +description: + This endpoint is used to list all consent records existing for a data + agreement for an organisation defined in the consent building block. The + response is paginated. operationId: serviceListIndividualAgreementConsentRecordList parameters: - $ref: "../parameters/dataAgreementId.yaml" @@ -26,7 +29,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: "" -x-specification-pii-or-sensitive: "True" -x-specification-scenario: "" -x-specification-usecase: UC-C-PIC-I-001 diff --git a/openapi/v2023.11.1/paths/serviceListIndividualConsentRecordList.yaml b/openapi/v2023.11.1/paths/serviceListIndividualConsentRecordList.yaml index f2f66b6..bd83f82 100644 --- a/openapi/v2023.11.1/paths/serviceListIndividualConsentRecordList.yaml +++ b/openapi/v2023.11.1/paths/serviceListIndividualConsentRecordList.yaml @@ -1,5 +1,7 @@ summary: LIST - List all consent records for individual -description: LIST - List all current unambiguous consent records stored for individual +description: + This endpoint is used to list all consent records for an individual belonging + to an organiation defined in the consent building block. operationId: serviceListIndividualConsentRecordList parameters: - $ref: "../parameters/offset.yaml" diff --git a/openapi/v2023.11.1/paths/serviceListIndividuals.yaml b/openapi/v2023.11.1/paths/serviceListIndividuals.yaml index a6399f1..e44b7f0 100644 --- a/openapi/v2023.11.1/paths/serviceListIndividuals.yaml +++ b/openapi/v2023.11.1/paths/serviceListIndividuals.yaml @@ -1,5 +1,6 @@ summary: LIST - List all individuals description: LIST - lists individuals in the system + This endpoint is used to list all individuals in the organisation defined in the consent building block. operationId: "configListIndividuals" parameters: - $ref: "../parameters/offset.yaml" diff --git a/openapi/v2023.11.1/paths/servicePolicyRead.yaml b/openapi/v2023.11.1/paths/servicePolicyRead.yaml index 549c37c..f366006 100644 --- a/openapi/v2023.11.1/paths/servicePolicyRead.yaml +++ b/openapi/v2023.11.1/paths/servicePolicyRead.yaml @@ -1,5 +1,7 @@ -summary: READ - Read policy -description: READ - Fetch the latest version of a Policy and the presented revisionId of an associated DataAgreement +summary: READ - Read data policy +description: + This endpoint is used to read latest version of data policy defined in the + organisation in the consent building block. operationId: servicePolicyRead parameters: - $ref: "../parameters/policyId.yaml" diff --git a/openapi/v2023.11.1/paths/serviceReadDataSharingUi.yaml b/openapi/v2023.11.1/paths/serviceReadDataSharingUi.yaml index d2b9db6..40e4f37 100644 --- a/openapi/v2023.11.1/paths/serviceReadDataSharingUi.yaml +++ b/openapi/v2023.11.1/paths/serviceReadDataSharingUi.yaml @@ -1,5 +1,8 @@ summary: READ - Read data sharing UI -description: READ - Read data sharing UI +description: + This endpoint is used to render the data sharing UI during + a data exchange as defined by a (data source) organisation in the consent + building block. operationId: serviceReadDataSharingUi parameters: - name: dataAgreementId diff --git a/openapi/v2023.11.1/paths/serviceReadIdp.yaml b/openapi/v2023.11.1/paths/serviceReadIdp.yaml index 9bccade..1ae6478 100644 --- a/openapi/v2023.11.1/paths/serviceReadIdp.yaml +++ b/openapi/v2023.11.1/paths/serviceReadIdp.yaml @@ -1,5 +1,6 @@ -summary: READ - Read IdP -description: READ - Read IdP +summary: READ - Read IdP details +description: + This endpoint is used to read the IdP details configured by the organisation in the consent building block. operationId: serviceReadIdp parameters: - $ref: "../parameters/idpId.yaml" diff --git a/openapi/v2023.11.1/paths/serviceReadIndividual.yaml b/openapi/v2023.11.1/paths/serviceReadIndividual.yaml index f99eeec..914980f 100644 --- a/openapi/v2023.11.1/paths/serviceReadIndividual.yaml +++ b/openapi/v2023.11.1/paths/serviceReadIndividual.yaml @@ -1,5 +1,8 @@ -summary: READ - Read individual -description: READ - Read individual in the Consent system +summary: READ - Read individual +description: + This endpoint is used to read the individual's information as defined by the organisation + in the consent building block. This is used in privacy dashboard where the individuals can + mark their consents, sign data agreement etc. operationId: "configReadIndividual" parameters: - in: path diff --git a/openapi/v2023.11.1/paths/serviceReadIndividualRecordRead.yaml b/openapi/v2023.11.1/paths/serviceReadIndividualRecordRead.yaml index 9ede518..48141ae 100644 --- a/openapi/v2023.11.1/paths/serviceReadIndividualRecordRead.yaml +++ b/openapi/v2023.11.1/paths/serviceReadIndividualRecordRead.yaml @@ -1,7 +1,7 @@ summary: READ - Read consent record description: - READ - Read consent record. There should be one unambiguous DataAgreementRecord for an Individual - and an DataAgreement. + This endpoint is used to read a consent record for an individial for a chosen + data agreement. There should be one unambiguous consent record for an individual. operationId: serviceReadIndividualRecordRead parameters: - $ref: "../parameters/dataAgreementId.yaml" @@ -22,7 +22,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: "" -x-specification-pii-or-sensitive: "True" -x-specification-scenario: "" -x-specification-usecase: UC-C-PIC-I-001 diff --git a/openapi/v2023.11.1/paths/serviceReadOrganisation.yaml b/openapi/v2023.11.1/paths/serviceReadOrganisation.yaml index 0b94f5b..a96c406 100644 --- a/openapi/v2023.11.1/paths/serviceReadOrganisation.yaml +++ b/openapi/v2023.11.1/paths/serviceReadOrganisation.yaml @@ -1,5 +1,8 @@ -description: READ - Read organisation summary: READ - Read organisation +description: + This endpoint is used to read the organisation information as configured by the + organisation in the consent building block. This is used, for e.g., in the privacy + dashboard. operationId: serviceReadOrganisation deprecated: false responses: diff --git a/openapi/v2023.11.1/paths/serviceReadOrganisationCoverImage.yaml b/openapi/v2023.11.1/paths/serviceReadOrganisationCoverImage.yaml index c29aab5..8162da8 100644 --- a/openapi/v2023.11.1/paths/serviceReadOrganisationCoverImage.yaml +++ b/openapi/v2023.11.1/paths/serviceReadOrganisationCoverImage.yaml @@ -1,5 +1,7 @@ -summary: READ - Read organization cover image -description: Read organization cover image +summary: READ - Read organisation cover image +description: + This endpoint is used to retrieve the existing cover image for the organisation. + The cover image is used to display in the privacy dashboard. operationId: serviceReadOrganisationCoverImage responses: '200': diff --git a/openapi/v2023.11.1/paths/serviceReadOrganisationImage.yaml b/openapi/v2023.11.1/paths/serviceReadOrganisationImage.yaml index f10bada..f6248a1 100644 --- a/openapi/v2023.11.1/paths/serviceReadOrganisationImage.yaml +++ b/openapi/v2023.11.1/paths/serviceReadOrganisationImage.yaml @@ -1,5 +1,7 @@ summary: READ - Read organisation image -description: READ - Read organisation image +description: + This endpoint is used to read an organisation image as defined + in the consent building block. operationId: serviceReadOrganisationImage deprecated: false responses: diff --git a/openapi/v2023.11.1/paths/serviceReadOrganisationLogoImage.yaml b/openapi/v2023.11.1/paths/serviceReadOrganisationLogoImage.yaml index 16256ec..25bf970 100644 --- a/openapi/v2023.11.1/paths/serviceReadOrganisationLogoImage.yaml +++ b/openapi/v2023.11.1/paths/serviceReadOrganisationLogoImage.yaml @@ -1,5 +1,7 @@ summary: READ - Read organisation logo image description: Read organisation logo image + This endpoint is used to retrieve the existing logo image for the organisation. The + logo image is used to display in the privacy dashboard as well in data sharing UIs. operationId: serviceReadOrganisationLogoImage deprecated: false responses: diff --git a/openapi/v2023.11.1/paths/serviceUpdateIndividual.yaml b/openapi/v2023.11.1/paths/serviceUpdateIndividual.yaml index a1b4492..f01cde4 100644 --- a/openapi/v2023.11.1/paths/serviceUpdateIndividual.yaml +++ b/openapi/v2023.11.1/paths/serviceUpdateIndividual.yaml @@ -1,5 +1,6 @@ summary: UPDATE - Update individual -description: UPDATE - Updates individual in the Consent system +description: + This endpoint is used to udpated an individual for an organisation defined in the consent building block. operationId: "configUpdateIndividual" parameters: - in: path diff --git a/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecord.yaml b/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecord.yaml index 09c34cb..a0a7024 100644 --- a/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecord.yaml +++ b/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecord.yaml @@ -1,5 +1,8 @@ summary: UPDATE - Update consent record -description: UPDATE - Update consent record. Note that updating a signed consent record invalidates its signature. +description: + This endpoint is used to update an existing consent record for a given data agreement + for an organiation defined in the consent building block. Note that updating a signed + consent record invalidates its earlier signature. operationId: serviceUpdateIndividualConsentRecord parameters: - $ref: "../parameters/consentRecordId.yaml" @@ -51,7 +54,3 @@ security: - BearerAuth: [] tags: - service -x-specification-crudl-model: "" -x-specification-pii-or-sensitive: "True" -x-specification-scenario: "" -x-specification-usecase: UC-C-PIC-I-003 diff --git a/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecordSignature.yaml b/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecordSignature.yaml index f206193..ac0f174 100644 --- a/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecordSignature.yaml +++ b/openapi/v2023.11.1/paths/serviceUpdateIndividualConsentRecordSignature.yaml @@ -1,7 +1,7 @@ summary: UPDATE - Updates signature for consent record -description: UPDATE - Updates signature for consent record. This is used - to add a signature to an existing unsigned consent record. Consent BB is responsible - for updating the consent record state. +description: + This endpoint is used to update a signature object for the consent record + for an individual in an organiation defined in the consent building block. operationId: serviceUpdateIndividualConsentRecordSignature parameters: - description: Unique ID of an object diff --git a/openapi/v2023.11.1/paths/serviceVerificationAgreementConsentRecordRead.yaml b/openapi/v2023.11.1/paths/serviceVerificationAgreementConsentRecordRead.yaml index 32677cf..0495cf5 100644 --- a/openapi/v2023.11.1/paths/serviceVerificationAgreementConsentRecordRead.yaml +++ b/openapi/v2023.11.1/paths/serviceVerificationAgreementConsentRecordRead.yaml @@ -1,5 +1,7 @@ summary: READ - Read latest consent record -description: READ - Read latest consent record. +description: + This endpoint is used to read the latest consent record for an organisation + in the consent building block. operationId: serviceVerificationAgreementConsentRecordRead parameters: - $ref: "../parameters/consentRecordId.yaml" diff --git a/openapi/v2023.11.1/paths/serviceVerificationAgreementList.yaml b/openapi/v2023.11.1/paths/serviceVerificationAgreementList.yaml index 08adfc0..32afcc0 100644 --- a/openapi/v2023.11.1/paths/serviceVerificationAgreementList.yaml +++ b/openapi/v2023.11.1/paths/serviceVerificationAgreementList.yaml @@ -1,5 +1,7 @@ summary: LIST - List all consent records -description: LIST - List all consent records +description: + This endpoint is used to list all consent records available for an organisation + defined in the consent building block. The results are paginated. operationId: serviceVerificationAgreementList parameters: - $ref: "../parameters/offset.yaml" diff --git a/openapi/v2023.11.1/paths/serviceVerificationConsentRecordList.yaml b/openapi/v2023.11.1/paths/serviceVerificationConsentRecordList.yaml index a722bd8..78bae0d 100644 --- a/openapi/v2023.11.1/paths/serviceVerificationConsentRecordList.yaml +++ b/openapi/v2023.11.1/paths/serviceVerificationConsentRecordList.yaml @@ -1,5 +1,7 @@ summary: LIST - List all consent records -description: LIST - List all consent records +description: + This endpoint is used to list all consent records available for an organisation + defined in the consent building block. The results are paginated. operationId: serviceVerificationConsentRecordList parameters: - $ref: "../parameters/offset.yaml"