8 Service APIs

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

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.

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

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

HTTPcURLJavaScriptPython

POST /apis/GovStack/consent-management-bb//config/policy/ HTTP/1.1
Host: app.swaggerhub.com
Content-Type: application/json
Accept: */*
Content-Length: 167

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industrySector": "",
    "dataRetentionPeriodDays": "",
    "geographicRestriction": "",
    "storageLocation": ""
  }
}

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industrySector": "",
    "dataRetentionPeriodDays": "",
    "geographicRestriction": "",
    "storageLocation": ""
  },
  "revision": {
    "id": "",
    "schemaName": "",
    "objectId": "",
    "signedWithoutObjectId": "",
    "serializedSnapshot": "",
    "serializedHash": "",
    "timestamp": "",
    "authorizedByIndividual": {
      "id": "",
      "externalId": "",
      "externalIdType": "",
      "identityProviderId": ""
    },
    "authorizedByOther": "",
    "successor": {
      "id": "",
      "schemaName": "",
      "objectId": "",
      "signedWithoutObjectId": "",
      "serializedSnapshot": "",
      "serializedHash": "",
      "timestamp": "",
      "authorizedByIndividual": {
        "id": "",
        "externalId": "",
        "externalIdType": "",
        "identityProviderId": ""
      },
      "authorizedByOther": "",
      "successor": {
        "id": "",
        "schemaName": "",
        "objectId": "",
        "signedWithoutObjectId": "",
        "serializedSnapshot": "",
        "serializedHash": "",
        "timestamp": "",
        "authorizedByIndividual": {
          "id": "",
          "externalId": "",
          "externalIdType": "",
          "identityProviderId": ""
        },
        "authorizedByOther": "",
        "successor": {
          "id": "",
          "schemaName": "",
          "objectId": "",
          "signedWithoutObjectId": "",
          "serializedSnapshot": "",
          "serializedHash": "",
          "timestamp": "",
          "authorizedByIndividual": {
            "id": "",
            "externalId": "",
            "externalIdType": "",
            "identityProviderId": ""
          },
          "authorizedByOther": "",
          "successor": {
            "id": "",
            "schemaName": "",
            "objectId": "",
            "signedWithoutObjectId": "",
            "serializedSnapshot": "",
            "serializedHash": "",
            "timestamp": "",
            "authorizedByIndividual": {
              "id": "",
              "externalId": "",
              "externalIdType": "",
              "identityProviderId": ""
            },
            "authorizedByOther": "",
            "successor": "[Circular Reference]",
            "predecessorHash": "",
            "predecessorSignature": ""
          },
          "predecessorHash": "",
          "predecessorSignature": ""
        },
        "predecessorHash": "",
        "predecessorSignature": ""
      },
      "predecessorHash": "",
      "predecessorSignature": ""
    },
    "predecessorHash": "",
    "predecessorSignature": ""
  }
}

READ - get a Policy object + latest Revisio

get

READ - get a Policy object + latest Revisio

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

HTTPcURLJavaScriptPython

GET /apis/GovStack/consent-management-bb//config/policy/{policyId}/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industrySector": "",
    "dataRetentionPeriodDays": "",
    "geographicRestriction": "",
    "storageLocation": ""
  },
  "revision": {
    "id": "",
    "schemaName": "",
    "objectId": "",
    "signedWithoutObjectId": "",
    "serializedSnapshot": "",
    "serializedHash": "",
    "timestamp": "",
    "authorizedByIndividual": {
      "id": "",
      "externalId": "",
      "externalIdType": "",
      "identityProviderId": ""
    },
    "authorizedByOther": "",
    "successor": {
      "id": "",
      "schemaName": "",
      "objectId": "",
      "signedWithoutObjectId": "",
      "serializedSnapshot": "",
      "serializedHash": "",
      "timestamp": "",
      "authorizedByIndividual": {
        "id": "",
        "externalId": "",
        "externalIdType": "",
        "identityProviderId": ""
      },
      "authorizedByOther": "",
      "successor": {
        "id": "",
        "schemaName": "",
        "objectId": "",
        "signedWithoutObjectId": "",
        "serializedSnapshot": "",
        "serializedHash": "",
        "timestamp": "",
        "authorizedByIndividual": {
          "id": "",
          "externalId": "",
          "externalIdType": "",
          "identityProviderId": ""
        },
        "authorizedByOther": "",
        "successor": {
          "id": "",
          "schemaName": "",
          "objectId": "",
          "signedWithoutObjectId": "",
          "serializedSnapshot": "",
          "serializedHash": "",
          "timestamp": "",
          "authorizedByIndividual": {
            "id": "",
            "externalId": "",
            "externalIdType": "",
            "identityProviderId": ""
          },
          "authorizedByOther": "",
          "successor": {
            "id": "",
            "schemaName": "",
            "objectId": "",
            "signedWithoutObjectId": "",
            "serializedSnapshot": "",
            "serializedHash": "",
            "timestamp": "",
            "authorizedByIndividual": {
              "id": "",
              "externalId": "",
              "externalIdType": "",
              "identityProviderId": ""
            },
            "authorizedByOther": "",
            "successor": "[Circular Reference]",
            "predecessorHash": "",
            "predecessorSignature": ""
          },
          "predecessorHash": "",
          "predecessorSignature": ""
        },
        "predecessorHash": "",
        "predecessorSignature": ""
      },
      "predecessorHash": "",
      "predecessorSignature": ""
    },
    "predecessorHash": "",
    "predecessorSignature": ""
  }
}

LIST - returns the current Policy

get

LIST - returns the current Policy

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

HTTPcURLJavaScriptPython

GET /apis/GovStack/consent-management-bb//config/policy/{policyId}/revisions/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industrySector": "",
    "dataRetentionPeriodDays": "",
    "geographicRestriction": "",
    "storageLocation": ""
  }
}

Returns a list of readable Policy objects

get

LIST - Fetches list of readable Policy objects

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

HTTPcURLJavaScriptPython

GET /apis/GovStack/consent-management-bb//config/policies/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

{
  "policies": [
    {
      "id": "",
      "name": "",
      "version": "",
      "url": "",
      "jurisdiction": "",
      "industrySector": "",
      "dataRetentionPeriodDays": "",
      "geographicRestriction": "",
      "storageLocation": ""
    }
  ]
}

8.2 Service APIs

CREATE - Creates an Individual in the Consent system

post

CREATE - Creates an Individual in the Consent system

Body

Responses

200Success

application/json

400

bad input parameter

post

HTTPcURLJavaScriptPython

POST /apis/GovStack/consent-management-bb//service/individual/ HTTP/1.1
Host: app.swaggerhub.com
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "individual": {
    "id": "",
    "externalId": "",
    "externalIdType": "",
    "identityProviderId": ""
  }
}

{
  "individual": {
    "id": "",
    "externalId": "",
    "externalIdType": "",
    "identityProviderId": ""
  }
}

READ - Fetch an Individual in the Consent system

get

READ - Fetch an Individual in the Consent system

Path parameters

individualIdstringRequired

Unique ID of an object

Responses

200Success

application/json

400

bad input parameter

get

HTTPcURLJavaScriptPython

GET /apis/GovStack/consent-management-bb//service/individual/{individualId}/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

{
  "individual": {
    "id": "",
    "externalId": "",
    "externalIdType": "",
    "identityProviderId": ""
  }
}

UPDATE - Updates an Individual in the Consent system

put

UPDATE - Updates an Individual in the Consent system

Path parameters

individualIdstringRequired

Unique ID of an object

Body

Responses

200Success

application/json

400

bad input parameter

put

HTTPcURLJavaScriptPython

PUT /apis/GovStack/consent-management-bb//service/individual/{individualId}/ HTTP/1.1
Host: app.swaggerhub.com
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "individual": {
    "id": "",
    "externalId": "",
    "externalIdType": "",
    "identityProviderId": ""
  }
}

{
  "individual": {
    "id": "",
    "externalId": "",
    "externalIdType": "",
    "identityProviderId": ""
  }
}

LIST - lists individuals in the system

get

LIST - lists individuals in the system

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

HTTPcURLJavaScriptPython

GET /apis/GovStack/consent-management-bb//service/individuals/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

{
  "individuals": [
    {
      "id": "",
      "externalId": "",
      "externalIdType": "",
      "identityProviderId": ""
    }
  ]
}

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

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

HTTPcURLJavaScriptPython

GET /apis/GovStack/consent-management-bb//service/policy/{policyId}/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

{
  "policy": {
    "id": "",
    "name": "",
    "version": "",
    "url": "",
    "jurisdiction": "",
    "industrySector": "",
    "dataRetentionPeriodDays": "",
    "geographicRestriction": "",
    "storageLocation": ""
  },
  "revision": {
    "id": "",
    "schemaName": "",
    "objectId": "",
    "signedWithoutObjectId": "",
    "serializedSnapshot": "",
    "serializedHash": "",
    "timestamp": "",
    "authorizedByIndividual": {
      "id": "",
      "externalId": "",
      "externalIdType": "",
      "identityProviderId": ""
    },
    "authorizedByOther": "",
    "successor": {
      "id": "",
      "schemaName": "",
      "objectId": "",
      "signedWithoutObjectId": "",
      "serializedSnapshot": "",
      "serializedHash": "",
      "timestamp": "",
      "authorizedByIndividual": {
        "id": "",
        "externalId": "",
        "externalIdType": "",
        "identityProviderId": ""
      },
      "authorizedByOther": "",
      "successor": {
        "id": "",
        "schemaName": "",
        "objectId": "",
        "signedWithoutObjectId": "",
        "serializedSnapshot": "",
        "serializedHash": "",
        "timestamp": "",
        "authorizedByIndividual": {
          "id": "",
          "externalId": "",
          "externalIdType": "",
          "identityProviderId": ""
        },
        "authorizedByOther": "",
        "successor": {
          "id": "",
          "schemaName": "",
          "objectId": "",
          "signedWithoutObjectId": "",
          "serializedSnapshot": "",
          "serializedHash": "",
          "timestamp": "",
          "authorizedByIndividual": {
            "id": "",
            "externalId": "",
            "externalIdType": "",
            "identityProviderId": ""
          },
          "authorizedByOther": "",
          "successor": {
            "id": "",
            "schemaName": "",
            "objectId": "",
            "signedWithoutObjectId": "",
            "serializedSnapshot": "",
            "serializedHash": "",
            "timestamp": "",
            "authorizedByIndividual": {
              "id": "",
              "externalId": "",
              "externalIdType": "",
              "identityProviderId": ""
            },
            "authorizedByOther": "",
            "successor": "[Circular Reference]",
            "predecessorHash": "",
            "predecessorSignature": ""
          },
          "predecessorHash": "",
          "predecessorSignature": ""
        },
        "predecessorHash": "",
        "predecessorSignature": ""
      },
      "predecessorHash": "",
      "predecessorSignature": ""
    },
    "predecessorHash": "",
    "predecessorSignature": ""
  }
}

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.

Responses

200Success

400

bad input parameter

delete

HTTPcURLJavaScriptPython

DELETE /apis/GovStack/consent-management-bb//service/individual/record/ HTTP/1.1
Host: app.swaggerhub.com
Accept: */*

No content

8.3 Audit APIs