LogoLogo
Give FeedbackGovStack Home
23Q4
23Q4
  • Consent
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
  • 9 Internal Workflows
  • 10 Other Resources
  • Internal use-case definitions
    • UC-C-PIC-A: Organisation Administration Use Cases (CONFIGURATION)
    • UC-C-PIC-I: Individual use cases (SERVICES)
    • UC-C-PIC-AT: Data Processing Auditor Use Cases (AUDIT)
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

Last updated 1 year ago

Was this helpful?

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

The provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Consent Building Block can be found in .

8.1 API specification

The following is an automated rendition of our latest .

8.1.1 Config APIs

8.1.2 Service APIs

8.1.3 Audit APIs

None

READ - get a Policy object + latest Revision. If a PolicyFilter is supplied and contains a revision_id, then this specific revision is returned.

get

READ - get a Policy object + latest Revision. If a PolicyFilter is supplied and contains a revision_id, then this specific revision is returned.

Authorizations
Path parameters
policyIdstringRequired

Unique ID of an object

Query parameters
revisionIdstringOptional

An object with id revisionId

Responses
200Success
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//config/policy/{policyId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
  {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
]

DELETE - Deletes an existing Policy object, returning the updated version and a new revision. Deleting a Policy is not possible if it's associated with active Agreement.

delete

DELETE - Deletes an existing Policy object, returning the updated version and a new revision. Deleting a Policy is not possible if it's associated with active Agreement.

Authorizations
Path parameters
policyIdstringRequired

Unique ID of an object

Responses
200Success
application/json
400
bad input parameter
delete
DELETE /apis/GovStack/consent-management-bb//config/policy/{policyId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "id": "",
  "schema_name": "",
  "object_id": "",
  "signed_without_object_id": "",
  "serialized_snapshot": "",
  "serialized_hash": "",
  "timestamp": "",
  "authorized_by_individual": {
    "id": "",
    "external_id": "",
    "external_id_type": "",
    "identity_provider_id": ""
  },
  "authorized_by_other": "",
  "successor": {
    "id": "",
    "schema_name": "",
    "object_id": "",
    "signed_without_object_id": "",
    "serialized_snapshot": "",
    "serialized_hash": "",
    "timestamp": "",
    "authorized_by_individual": {
      "id": "",
      "external_id": "",
      "external_id_type": "",
      "identity_provider_id": ""
    },
    "authorized_by_other": "",
    "successor": {
      "id": "",
      "schema_name": "",
      "object_id": "",
      "signed_without_object_id": "",
      "serialized_snapshot": "",
      "serialized_hash": "",
      "timestamp": "",
      "authorized_by_individual": {
        "id": "",
        "external_id": "",
        "external_id_type": "",
        "identity_provider_id": ""
      },
      "authorized_by_other": "",
      "successor": {
        "id": "",
        "schema_name": "",
        "object_id": "",
        "signed_without_object_id": "",
        "serialized_snapshot": "",
        "serialized_hash": "",
        "timestamp": "",
        "authorized_by_individual": {
          "id": "",
          "external_id": "",
          "external_id_type": "",
          "identity_provider_id": ""
        },
        "authorized_by_other": "",
        "successor": {
          "id": "",
          "schema_name": "",
          "object_id": "",
          "signed_without_object_id": "",
          "serialized_snapshot": "",
          "serialized_hash": "",
          "timestamp": "",
          "authorized_by_individual": {
            "id": "",
            "external_id": "",
            "external_id_type": "",
            "identity_provider_id": ""
          },
          "authorized_by_other": "",
          "successor": {
            "id": "",
            "schema_name": "",
            "object_id": "",
            "signed_without_object_id": "",
            "serialized_snapshot": "",
            "serialized_hash": "",
            "timestamp": "",
            "authorized_by_individual": {
              "id": "",
              "external_id": "",
              "external_id_type": "",
              "identity_provider_id": ""
            },
            "authorized_by_other": "",
            "successor": "[Circular Reference]",
            "predecessor_hash": "",
            "predecessor_signature": ""
          },
          "predecessor_hash": "",
          "predecessor_signature": ""
        },
        "predecessor_hash": "",
        "predecessor_signature": ""
      },
      "predecessor_hash": "",
      "predecessor_signature": ""
    },
    "predecessor_hash": "",
    "predecessor_signature": ""
  },
  "predecessor_hash": "",
  "predecessor_signature": ""
}

LIST - returns the current Policy

get

LIST - returns the current Policy

Authorizations
Path parameters
policyIdstringRequired

Unique ID of an object

Query parameters
offsetintegerOptional

Requested index for start of resources to be provided in response requested by client

limitintegerOptional

Requested number of resources to be provided in response requested by client

Responses
200Success
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//config/policy/{policyId}/revisions/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "id": "",
  "name": "",
  "version": "",
  "url": "",
  "jurisdiction": "",
  "industry_sector": "",
  "data_retention_period_days": "",
  "geographic_restriction": "",
  "storage_location": ""
}

Returns a list of readable Policy objects

get

LIST - Fetches list of readable Policy objects

Authorizations
Query parameters
revisionIdstringOptional

An object with id revisionId

offsetintegerOptional

Requested index for start of resources to be provided in response requested by client

limitintegerOptional

Requested number of resources to be provided in response requested by client

Responses
200
A list of Policy objects readable for the current session's credentials.
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//config/policies/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
  {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
]

READ - Fetch an Individual in the Consent system

get

READ - Fetch an Individual in the Consent system

Authorizations
Path parameters
individualIdstringRequired

Unique ID of an object

Responses
200Success
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//service/individual/{individualId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "id": "",
  "external_id": "",
  "external_id_type": "",
  "identity_provider_id": ""
}

LIST - lists individuals in the system

get

LIST - lists individuals in the system

Authorizations
Query parameters
offsetintegerOptional

Requested index for start of resources to be provided in response requested by client

limitintegerOptional

Requested number of resources to be provided in response requested by client

Responses
200Success
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//service/individuals/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
  {
    "id": "",
    "external_id": "",
    "external_id_type": "",
    "identity_provider_id": ""
  }
]

READ - fetches the latest version of a Policy and the presented revisionId of an associated Agreement

get

READ - fetches the latest version of a Policy and the presented revisionId of an associated Agreement

Authorizations
Path parameters
policyIdstringRequired

Unique ID of an object

Query parameters
revisionIdstringOptional

An object with id revisionId

Responses
200Success
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//service/policy/{policyId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
  {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
]

DELETE - Cascading delete operation for Right To Be Forgotten, deletes all Consent Records that shall not be retained and have a "forgettable" Agreement. May also delete an unsigned Consent Record, for instance in cases where the user exits the signing process. Individual ID supplied as HTTP header.

delete

DELETE - Cascading delete operation for Right To Be Forgotten, deletes all Consent Records that shall not be retained and have a "forgettable" Agreement. May also delete an unsigned Consent Record, for instance in cases where the user exits the signing process. Individual ID supplied as HTTP header.

Authorizations
Responses
200Success
400
bad input parameter
delete
DELETE /apis/GovStack/consent-management-bb//service/individual/record/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

READ

get

READ

Authorizations
Path parameters
consentRecordIdstringRequired

Unique ID of an object

Responses
200Success
application/json
400
bad input parameter
get
GET /apis/GovStack/consent-management-bb//audit/consentrecord/{consentRecordId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "id": "",
  "agreement": {
    "id": "",
    "version": "",
    "controller": {
      "id": "",
      "name": "",
      "url": ""
    },
    "policy": {
      "id": "",
      "name": "",
      "version": "",
      "url": "",
      "jurisdiction": "",
      "industry_sector": "",
      "data_retention_period_days": "",
      "geographic_restriction": "",
      "storage_location": ""
    },
    "purpose": {
      "id": "",
      "name": "",
      "description": "",
      "serialized_hash": ""
    },
    "lawful_basis": "",
    "data_use": "",
    "dpia": "",
    "signature": {
      "id": "",
      "payload": "",
      "signature": "",
      "verification_method": "",
      "verification_payload": "",
      "verification_payload_hash": "",
      "verification_artifact": "",
      "verification_signed_by": "",
      "verification_signed_as": "",
      "verification_jws_header": "",
      "timestamp": "",
      "signed_without_object_reference": "",
      "object_type": "",
      "object_reference": ""
    },
    "active": "",
    "forgettable": "",
    "compatible_with_version": {
      "id": "",
      "version": "",
      "controller": {
        "id": "",
        "name": "",
        "url": ""
      },
      "policy": {
        "id": "",
        "name": "",
        "version": "",
        "url": "",
        "jurisdiction": "",
        "industry_sector": "",
        "data_retention_period_days": "",
        "geographic_restriction": "",
        "storage_location": ""
      },
      "purpose": {
        "id": "",
        "name": "",
        "description": "",
        "serialized_hash": ""
      },
      "lawful_basis": "",
      "data_use": "",
      "dpia": "",
      "signature": {
        "id": "",
        "payload": "",
        "signature": "",
        "verification_method": "",
        "verification_payload": "",
        "verification_payload_hash": "",
        "verification_artifact": "",
        "verification_signed_by": "",
        "verification_signed_as": "",
        "verification_jws_header": "",
        "timestamp": "",
        "signed_without_object_reference": "",
        "object_type": "",
        "object_reference": ""
      },
      "active": "",
      "forgettable": "",
      "compatible_with_version": {
        "id": "",
        "version": "",
        "controller": {
          "id": "",
          "name": "",
          "url": ""
        },
        "policy": {
          "id": "",
          "name": "",
          "version": "",
          "url": "",
          "jurisdiction": "",
          "industry_sector": "",
          "data_retention_period_days": "",
          "geographic_restriction": "",
          "storage_location": ""
        },
        "purpose": {
          "id": "",
          "name": "",
          "description": "",
          "serialized_hash": ""
        },
        "lawful_basis": "",
        "data_use": "",
        "dpia": "",
        "signature": {
          "id": "",
          "payload": "",
          "signature": "",
          "verification_method": "",
          "verification_payload": "",
          "verification_payload_hash": "",
          "verification_artifact": "",
          "verification_signed_by": "",
          "verification_signed_as": "",
          "verification_jws_header": "",
          "timestamp": "",
          "signed_without_object_reference": "",
          "object_type": "",
          "object_reference": ""
        },
        "active": "",
        "forgettable": "",
        "compatible_with_version": {
          "id": "",
          "version": "",
          "controller": {
            "id": "",
            "name": "",
            "url": ""
          },
          "policy": {
            "id": "",
            "name": "",
            "version": "",
            "url": "",
            "jurisdiction": "",
            "industry_sector": "",
            "data_retention_period_days": "",
            "geographic_restriction": "",
            "storage_location": ""
          },
          "purpose": {
            "id": "",
            "name": "",
            "description": "",
            "serialized_hash": ""
          },
          "lawful_basis": "",
          "data_use": "",
          "dpia": "",
          "signature": {
            "id": "",
            "payload": "",
            "signature": "",
            "verification_method": "",
            "verification_payload": "",
            "verification_payload_hash": "",
            "verification_artifact": "",
            "verification_signed_by": "",
            "verification_signed_as": "",
            "verification_jws_header": "",
            "timestamp": "",
            "signed_without_object_reference": "",
            "object_type": "",
            "object_reference": ""
          },
          "active": "",
          "forgettable": "",
          "compatible_with_version": {
            "id": "",
            "version": "",
            "controller": {
              "id": "",
              "name": "",
              "url": ""
            },
            "policy": {
              "id": "",
              "name": "",
              "version": "",
              "url": "",
              "jurisdiction": "",
              "industry_sector": "",
              "data_retention_period_days": "",
              "geographic_restriction": "",
              "storage_location": ""
            },
            "purpose": {
              "id": "",
              "name": "",
              "description": "",
              "serialized_hash": ""
            },
            "lawful_basis": "",
            "data_use": "",
            "dpia": "",
            "signature": {
              "id": "",
              "payload": "",
              "signature": "",
              "verification_method": "",
              "verification_payload": "",
              "verification_payload_hash": "",
              "verification_artifact": "",
              "verification_signed_by": "",
              "verification_signed_as": "",
              "verification_jws_header": "",
              "timestamp": "",
              "signed_without_object_reference": "",
              "object_type": "",
              "object_reference": ""
            },
            "active": "",
            "forgettable": "",
            "compatible_with_version": "[Circular Reference]",
            "lifecycle": {
              "id": "",
              "name": ""
            }
          },
          "lifecycle": {
            "id": "",
            "name": ""
          }
        },
        "lifecycle": {
          "id": "",
          "name": ""
        }
      },
      "lifecycle": {
        "id": "",
        "name": ""
      }
    },
    "lifecycle": {
      "id": "",
      "name": ""
    }
  },
  "agreement_revision": {
    "id": "",
    "schema_name": "",
    "object_id": "",
    "signed_without_object_id": "",
    "serialized_snapshot": "",
    "serialized_hash": "",
    "timestamp": "",
    "authorized_by_individual": {
      "id": "",
      "external_id": "",
      "external_id_type": "",
      "identity_provider_id": ""
    },
    "authorized_by_other": "",
    "successor": {
      "id": "",
      "schema_name": "",
      "object_id": "",
      "signed_without_object_id": "",
      "serialized_snapshot": "",
      "serialized_hash": "",
      "timestamp": "",
      "authorized_by_individual": {
        "id": "",
        "external_id": "",
        "external_id_type": "",
        "identity_provider_id": ""
      },
      "authorized_by_other": "",
      "successor": {
        "id": "",
        "schema_name": "",
        "object_id": "",
        "signed_without_object_id": "",
        "serialized_snapshot": "",
        "serialized_hash": "",
        "timestamp": "",
        "authorized_by_individual": {
          "id": "",
          "external_id": "",
          "external_id_type": "",
          "identity_provider_id": ""
        },
        "authorized_by_other": "",
        "successor": {
          "id": "",
          "schema_name": "",
          "object_id": "",
          "signed_without_object_id": "",
          "serialized_snapshot": "",
          "serialized_hash": "",
          "timestamp": "",
          "authorized_by_individual": {
            "id": "",
            "external_id": "",
            "external_id_type": "",
            "identity_provider_id": ""
          },
          "authorized_by_other": "",
          "successor": {
            "id": "",
            "schema_name": "",
            "object_id": "",
            "signed_without_object_id": "",
            "serialized_snapshot": "",
            "serialized_hash": "",
            "timestamp": "",
            "authorized_by_individual": {
              "id": "",
              "external_id": "",
              "external_id_type": "",
              "identity_provider_id": ""
            },
            "authorized_by_other": "",
            "successor": "[Circular Reference]",
            "predecessor_hash": "",
            "predecessor_signature": ""
          },
          "predecessor_hash": "",
          "predecessor_signature": ""
        },
        "predecessor_hash": "",
        "predecessor_signature": ""
      },
      "predecessor_hash": "",
      "predecessor_signature": ""
    },
    "predecessor_hash": "",
    "predecessor_signature": ""
  },
  "agreement_revision_hash": "",
  "individual": {
    "id": "",
    "external_id": "",
    "external_id_type": "",
    "identity_provider_id": ""
  },
  "opt_in": "",
  "state": "",
  "signature": {
    "id": "",
    "payload": "",
    "signature": "",
    "verification_method": "",
    "verification_payload": "",
    "verification_payload_hash": "",
    "verification_artifact": "",
    "verification_signed_by": "",
    "verification_signed_as": "",
    "verification_jws_header": "",
    "timestamp": "",
    "signed_without_object_reference": "",
    "object_type": "",
    "object_reference": ""
  }
}
  • 8 Service APIs
  • 8.1 API specification
  • 8.1.1 Config APIs
  • POSTCREATE - Creates a new Policy object and returns the new object and a PolicyRevision
  • GETREAD - get a Policy object + latest Revision. If a PolicyFilter is supplied and contains a revision_id, then this specific revision is returned.
  • PUTUPDATE - Updates an existing Policy object, returning the updated version and a new revision. Updating a Policy does not affect existing references in Agreement, the new revision should be specified for Agreement.
  • DELETEDELETE - Deletes an existing Policy object, returning the updated version and a new revision. Deleting a Policy is not possible if it's associated with active Agreement.
  • GETLIST - returns the current Policy
  • GETReturns a list of readable Policy objects
  • 8.1.2 Service APIs
  • POSTCREATE - Creates an Individual in the Consent system
  • GETREAD - Fetch an Individual in the Consent system
  • PUTUPDATE - Updates an Individual in the Consent system
  • GETLIST - lists individuals in the system
  • GETREAD - fetches the latest version of a Policy and the presented revisionId of an associated Agreement
  • DELETEDELETE - Cascading delete operation for Right To Be Forgotten, deletes all Consent Records that shall not be retained and have a "forgettable" Agreement. May also delete an unsigned Consent Record, for instance in cases where the user exits the signing process. Individual ID supplied as HTTP header.
  • 8.1.3 Audit APIs
  • GETREAD
GovStack non-functional requirements document
this GitHub repository
OpenAPI YAML specification

CREATE - Creates a new Policy object and returns the new object and a PolicyRevision

post

CREATE - Creates a new Policy object and returns the new object and a PolicyRevision

Authorizations
Body
Responses
200
A set consisting of the new Policy object created, together with the initial Revision object.
application/json
400
bad input parameter
post
POST /apis/GovStack/consent-management-bb//config/policy/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 173

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
}
[
  {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
]

UPDATE - Updates an existing Policy object, returning the updated version and a new revision. Updating a Policy does not affect existing references in Agreement, the new revision should be specified for Agreement.

put

UPDATE - Updates an existing Policy object, returning the updated version and a new revision. Updating a Policy does not affect existing references in Agreement, the new revision should be specified for Agreement.

Authorizations
Path parameters
policyIdstringRequired

Unique ID of an object

Body
Responses
200Success
application/json
400
bad input parameter
put
PUT /apis/GovStack/consent-management-bb//config/policy/{policyId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 173

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
}
[
  {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industry_sector": "",
    "data_retention_period_days": "",
    "geographic_restriction": "",
    "storage_location": ""
  }
]

CREATE - Creates an Individual in the Consent system

post

CREATE - Creates an Individual in the Consent system

Authorizations
Body
Responses
200Success
application/json
400
bad input parameter
post
POST /apis/GovStack/consent-management-bb//service/individual/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "individual": {
    "id": "",
    "external_id": "",
    "external_id_type": "",
    "identity_provider_id": ""
  }
}
{
  "id": "",
  "external_id": "",
  "external_id_type": "",
  "identity_provider_id": ""
}

UPDATE - Updates an Individual in the Consent system

put

UPDATE - Updates an Individual in the Consent system

Authorizations
Path parameters
individualIdstringRequired

Unique ID of an object

Body
Responses
200Success
application/json
400
bad input parameter
put
PUT /apis/GovStack/consent-management-bb//service/individual/{individualId}/ HTTP/1.1
Host: app.swaggerhub.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "individual": {
    "id": "",
    "external_id": "",
    "external_id_type": "",
    "identity_provider_id": ""
  }
}
{
  "id": "",
  "external_id": "",
  "external_id_type": "",
  "identity_provider_id": ""
}