Upd: Endpoint descriptions and summary for service APIs

Signed-off-by: Lal Chandran <[email protected]>

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":

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

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

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:

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

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"

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

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

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

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

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"

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

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"

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"

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"

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

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"

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

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

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:

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':

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:

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:

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

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

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

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"

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"

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"