8 Service APIs

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

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 GovStack non-functional requirements document 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 this GitHub repository.

8.1 API specification

The following is an automated rendition of our latest OpenAPI YAML specification.

8.1.1 Config APIs

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

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

POSThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/

Authorization

OAuth2

Body

application/json

policy*Policy (object)

A policy governs data and Agreement in the realm of an organisation that is refered to as "data controller" (GDPR) and owner of referencing Agreements.

Response

200400

A set consisting of the new Policy object created, together with the initial Revision object.

Body

application/json

itemsone of

Policy (object)Revision (object)

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "policy": {
        "id": "",
        "name": "",
        "version": "",
        "url": ""
      }
    }),
});
const data = await response.json();

Response

200

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

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

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

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/

Authorization

OAuth2

Path parameters

policyId*string

Unique ID of an object

Query parameters

Response

200400

Body

application/json

itemsone of

Policy (object)Revision (object)

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "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.

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.

PUThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/

Authorization

OAuth2

Path parameters

policyId*string

Unique ID of an object

Body

application/json

policy*Policy (object)

A policy governs data and Agreement in the realm of an organisation that is refered to as "data controller" (GDPR) and owner of referencing Agreements.

Response

200400

Body

application/json

itemsone of

Policy (object)Revision (object)

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "policy": {
        "id": "",
        "name": "",
        "version": "",
        "url": ""
      }
    }),
});
const data = await response.json();

Response

200

[
  {
    "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 - 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.

DELETEhttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/

Authorization

OAuth2

Path parameters

policyId*string

Unique ID of an object

Response

200400

Body

application/json

id*string

Example: ""

schema_name*string

This was previously called "schema" but for technical reasons should be called "schema_name"

Example: ""

object_id*string

The PK of the object that was serialized.

Example: ""

signed_without_object_idboolean

Indicates that object_id was left blank in serialized_snapshot when calculating serialized_hash. object_id may be subsequently filled in.

Example: ""

serialized_snapshot*string

Revisioned data (serialized as JSON) as a dict {object_data: {...}, schema_name: ..., object_id: ..., signed_without_object_id: ..., timestamp: ..., authorized_by_individual: ..., authorized_by_other: ...}. It contains all the fields of the schema except id, successor, predessor_hash and predecessor_signature.

Example: ""

serialized_hash*string

Hash of serialized_snapshot (SHA-1)

Example: ""

timestamp*string

Timestamp of when revisioning happened

Example: ""

authorized_by_individualIndividual (object)

Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.

authorized_by_otherstring

Reference to an admin user that has created this revision

Example: ""

successorRevision (object)

A generic revision model captures the serialized contents of any shema's single row. This is then subject to 1) cryptographic signature and 2) auditing.

Aside from "successor" column, a revision should be considered locked.

predecessor_hashstring

Tamper-resistent artifact from previous record, copied from serialized_hash

Example: ""

predecessor_signaturestring

Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)

Example: ""

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200

{
  "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": "",
  "predecessor_hash": "",
  "predecessor_signature": ""
}

LIST - returns the current Policy

LIST - returns the current Policy

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/revisions/

Authorization

OAuth2

Path parameters

policyId*string

Unique ID of an object

Query parameters

Response

200400

Body

application/json

id*string

Example: ""

name*string

Name of the policy

Example: ""

version*string

Version of the policy

Example: ""

url*string

Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.

Example: ""

jurisdictionstring

Example: ""

industry_sectorstring

Example: ""

data_retention_period_daysinteger

Example: ""

geographic_restrictionstring

Example: ""

storage_locationstring

Example: ""

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/revisions/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Returns a list of readable Policy objects

LIST - Fetches list of readable Policy objects

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policies/

Authorization

OAuth2

Query parameters

Response

200400

A list of Policy objects readable for the current session's credentials.

Body

application/json

itemsone of

Policy (object)

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policies/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

8.1.2 Service APIs

CREATE - Creates an Individual in the Consent system

CREATE - Creates an Individual in the Consent system

POSThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/

Authorization

OAuth2

Body

application/json

individual*Individual (object)

Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.

Response

200400

Body

application/json

id*string

The unique ID of an Individual row.

Example: ""

external_idstring

Reference to another foundational/functional ID, which is likely PII

Example: ""

external_id_typestring

External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.

Example: ""

identity_provider_idstring

This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.

Example: ""

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "individual": {
        "id": ""
      }
    }),
});
const data = await response.json();

Response

200

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

READ - Fetch an Individual in the Consent system

READ - Fetch an Individual in the Consent system

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/

Authorization

OAuth2

Path parameters

individualId*string

Unique ID of an object

Response

200400

Body

application/json

id*string

The unique ID of an Individual row.

Example: ""

external_idstring

Reference to another foundational/functional ID, which is likely PII

Example: ""

external_id_typestring

External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.

Example: ""

identity_provider_idstring

This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.

Example: ""

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

UPDATE - Updates an Individual in the Consent system

UPDATE - Updates an Individual in the Consent system

PUThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/

Authorization

OAuth2

Path parameters

individualId*string

Unique ID of an object

Body

application/json

individual*Individual (object)

Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.

Response

200400

Body

application/json

id*string

The unique ID of an Individual row.

Example: ""

external_idstring

Reference to another foundational/functional ID, which is likely PII

Example: ""

external_id_typestring

External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.

Example: ""

identity_provider_idstring

This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.

Example: ""

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "individual": {
        "id": ""
      }
    }),
});
const data = await response.json();

Response

200

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

LIST - lists individuals in the system

LIST - lists individuals in the system

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individuals/

Authorization

OAuth2

Query parameters

Response

200400

Body

application/json

itemsone of

Individual (object)

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individuals/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "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

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

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/policy/{policyId}/

Authorization

OAuth2

Path parameters

policyId*string

Unique ID of an object

Query parameters

Response

200400

Body

application/json

itemsone of

Policy (object)Revision (object)

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/policy/{policyId}/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "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 - 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.

DELETEhttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/

Authorization

OAuth2

Response

200400

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

8.1.3 Audit APIs

READ

READ

GEThttps://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/consentrecord/{consentRecordId}/

Authorization

OAuth2

Path parameters

consentRecordId*string

Unique ID of an object

Response

200400

Body

application/json

id*string

Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a ConsentRecord that is not yet stored in the database and only exist in transit. Draft ConsentRecords do not have a Revision, but if paired up with a Signature, a valid Revision should be generated.

Example: ""

agreementAgreement (object)

An agreement contains the specification of a single purpose that can be consented to. An Agreement is universal and can be consented to by many individuals through a ConsentRecord

agreement_revisionRevision (object)

A generic revision model captures the serialized contents of any shema's single row. This is then subject to 1) cryptographic signature and 2) auditing.

Aside from "successor" column, a revision should be considered locked.

agreement_revision_hash*string

Copy of the revision hash. The hash is the included in the signature and ensures against tampering with the original agreement.

Example: ""

individualIndividual (object)

Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.

opt_inboolean

True: The individual has positively opted in. False: The individual has explicitly said no (or withdrawn a previous consent).

Example: ""

state*string

The state field is used to record state changes after-the-fact. It is maintained by the Consent BB itself. Valid states: unsigned/pending more signatures/signed

Example: ""

signatureSignature (object)

A generic signature contains a cryptographic hash of some value, together with a signature created by some private key in another system. Required signing methods: Revision object or another Signature object.

Request

JavaScriptCurlPython

const response = await fetch('https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/consentrecord/{consentRecordId}/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "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": "",
    "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": "",
    "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": ""
  }
}

None