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 Registration Building Block can be found in this GitHub repository.

8.1 Online Registration e-services

The available services (i.e. registration processes) and form definitions within such a service can be accessed:

returns a list of services (Services available to use)

Listing of all services with basic information

GET/services

Query parameters

Response

200500

list of services or an empty array if none are available

Body

application/json

id*string (uuid)

unique identifier (serviceId)

Example: "f7d33db0-2809-484e-a780-76b7ccd4ecbf"

name*string

name of a service

Example: "Mother and Child Registration"

version*string

service version number

Example: "123"

type*enum

NonePrivatePublic

isExecutableboolean

Specifies whether the service is executable

isClosedboolean

whether Messages and Events, not modeled in Service, can occur when the service is executed or performed

descriptionstring

serviceBodyListOfProperties (array of object)

Request

JavaScriptCurlPython

const response = await fetch('/services', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200500

[
  {
    "id": "f7d33db0-2809-484e-a780-76b7ccd4ecbf",
    "name": "Mother and Child Registration",
    "version": "123",
    "type": "None",
    "isExecutable": false,
    "isClosed": false,
    "description": "text",
    "serviceBody": [
      {
        "code": "text",
        "value": "text"
      }
    ]
  }
]

returns detailed information about a service

Pass in the ID of the service and it will return all information about that service

GET/services/{serviceId}

Path parameters

serviceId*string (uuid)

The id for a defined service in the registration BB workflow engine.

Example: "f7d33db0-2809-484e-a780-76b7ccd4ecbf"

Response

200404500

Service found and representation returned

Body

application/json

id*string (uuid)

unique identifier (serviceId)

Example: "f7d33db0-2809-484e-a780-76b7ccd4ecbf"

name*string

name of a service

Example: "Mother and Child Registration"

version*string

service version number

Example: "123"

type*enum

NonePrivatePublic

isExecutableboolean

Specifies whether the service is executable

isClosedboolean

whether Messages and Events, not modeled in Service, can occur when the service is executed or performed

descriptionstring

serviceBodyListOfProperties (array of object)

Request

JavaScriptCurlPython

const response = await fetch('/services/{serviceId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200500

{
  "id": "f7d33db0-2809-484e-a780-76b7ccd4ecbf",
  "name": "Mother and Child Registration",
  "version": "123",
  "type": "None",
  "isExecutable": false,
  "isClosed": false,
  "description": "text",
  "serviceBody": [
    {
      "code": "text",
      "value": "text"
    }
  ]
}

Retrieve all available e-forms

Get the list of all e-service forms with schema related to the given service

GET/services/{serviceId}/eForms

Path parameters

serviceId*string (uuid)

The id for a defined service in the registration BB workflow engine.

Example: "f7d33db0-2809-484e-a780-76b7ccd4ecbf"

Response

200

list of eForms or an empty array if none are available

Body

application/json

eFormIdstring

The unique identifier of the e-form

Example: "d98a205a-679b-485b-823d-7a32a391e744"

namestring

The name of the e-form

Example: "FORM"

descriptionstring

A description of the e-form

versionstring

Version of the e-form

Example: "1"

latestboolean

True if the last version

Request

JavaScriptCurlPython

const response = await fetch('/services/{serviceId}/eForms', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "eFormId": "d98a205a-679b-485b-823d-7a32a391e744",
    "name": "FORM",
    "description": "text",
    "version": "1",
    "latest": false
  }
]

Retrieve a specific e-form by ID

GET/eForms/{eFormId}

Path parameters

eFormId*string

The ID of the e-form to retrieve

Response

200404

OK

Body

application/json

eFormIdstring

The unique identifier of the e-form

Example: "d98a205a-679b-485b-823d-7a32a391e744"

namestring

The name of the e-form

Example: "A1"

descriptionstring

A description of the e-form

versionstring

Version of the e-form

Example: "1"

latestboolean

True if the last version

schemaEFormSchema (object)

The JSON schema of the e-form

Request

JavaScriptCurlPython

const response = await fetch('/eForms/{eFormId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "eFormId": "d98a205a-679b-485b-823d-7a32a391e744",
  "name": "A1",
  "description": "text",
  "version": "1",
  "latest": false
}

8.1.2 Generic Registration Steps

Going through the registration process as an applicant requires multiple steps available via API endpoints:

Submit an application file as an applicant

Send an application file including all documents and form data to submit a registration request to be processed by operators.

POST/services/{serviceId}/applications

Path parameters

serviceId*string (uuid)

The id for a defined service in the registration BB workflow engine.

Example: "f7d33db0-2809-484e-a780-76b7ccd4ecbf"

Header parameters

Body

application/json

Create a new application file in the system

applicationNamestring

Free text application name

Example: "Amya Yuko"

applicantId*string

Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

createdstring (date-time)

Time when the application file was created by the user- Draft

Example: "2000-10-23T00:00:00.000Z"

formDataformData (object)

documentUrlsdocumentUrls (array of string)

Response

200404500

Returns started application file ID

Body

*/*

fileIdstring

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: "81c4445c-bff6-11ed-afa1-0242ac120002"

registeredstring (date-time)

Time when the application file was registered in the Registration BB system

Example: "2000-10-23T00:00:00.000Z"

serviceId*string (uuid)

id of the service this application relates to

serviceNamestring

Example: "Post partum registration service"

statusstatusModel (object)

endedboolean

True, if application file processing has ended

Example: "false"

applicationDataapplicationFileSubmit (object)

Request

JavaScriptCurlPython

const response = await fetch('/services/{serviceId}/applications', {
    method: 'POST',
    headers: {
      "Information-Mediator-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004"
    }),
});
const data = await response.json();

Response

200500

{
  "fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
  "registered": "2000-10-23T00:00:00.000Z",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "Post partum registration service",
  "status": {
    "code": "PENDING",
    "title": "Pending"
  },
  "ended": "false",
  "applicationData": {
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
    },
    "documentUrls": [
      "text"
    ]
  }
}

Upload a required document

Upload a document/attachment to receive a documentId that can be linked to applications when submitting a new registration

POST/documents

Query parameters

Body

multipart/form-data

filearray of string (base64)

Response

200400500

File successfully uploaded

Body

*/*

codeinteger (int32)

typestring

messagestring

urlstring

Request

JavaScriptCurlPython

const response = await fetch('/documents', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400500

{
  "type": "text",
  "message": "text",
  "url": "text"
}

8.2 Processing of Registrations

Operators can access and process existing application files:

Retrieve all application files

Returns a list of application files the user has permission to access (i.e. either only the applicant's own applications or all applications for an operator to process)

GET/applications

Query parameters

Header parameters

Response

200

list of applications or an empty array if none are available

Body

*/*

fileIdstring

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: "81c4445c-bff6-11ed-afa1-0242ac120002"

mainTaskIdstring

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

taskTitlestring

Example: "Application xyz"

roleIdstring

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

roleNamestring

Example: "Registrar"

assigneeIdstring

operator ID who is processing the applicant file

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

operatorNamestring

operator ID who has the task of processing the application file

Example: "John Smith"

statusstatusModel (object)

applicantIdstring

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

createdstring (date-time)

Time when the application file was created by the user- Draft

Example: "2000-10-23T00:00:00.000Z"

registeredstring (date-time)

Time when the application file was registered in the Registration BB system

Example: "2000-10-23T00:00:00.000Z"

descriptionstring

Example: "Any text."

serviceNamestring

Example: "Post partum registration service"

serviceIdstring (uuid)

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

eformIdstring

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

documentUrlsdocumentUrls (array of string)

additionalMetaadditionalData (object)

Request

JavaScriptCurlPython

const response = await fetch('/applications', {
    method: 'GET',
    headers: {
      "Information-Mediator-Client": "text"
    },
});
const data = await response.json();

Response

200

[
  {
    "fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
    "mainTaskId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "taskTitle": "Application xyz",
    "roleId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "roleName": "Registrar",
    "assigneeId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "operatorName": "John Smith",
    "status": {
      "code": "PENDING",
      "title": "Pending"
    },
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "registered": "2000-10-23T00:00:00.000Z",
    "description": "Any text.",
    "serviceName": "Post partum registration service",
    "serviceId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "eformId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "documentUrls": [
      "text"
    ],
    "additionalMeta": {}
  }
]

Get application file by ID

Returns application file

GET/applications/{fileId}

Path parameters

fileId*string

Example: "8a70cd6d-bdb2-11ed-9397-0242ac120004"

Header parameters

Response

200404

Returns application file by id

Body

*/*

fileIdstring

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: "81c4445c-bff6-11ed-afa1-0242ac120002"

registeredstring (date-time)

Time when the application file was registered in the Registration BB system

Example: "2000-10-23T00:00:00.000Z"

serviceId*string (uuid)

id of the service this application relates to

serviceNamestring

Example: "Post partum registration service"

statusstatusModel (object)

endedboolean

True, if application file processing has ended

Example: "false"

applicationDataapplicationFileSubmit (object)

Request

JavaScriptCurlPython

const response = await fetch('/applications/{fileId}', {
    method: 'GET',
    headers: {
      "Information-Mediator-Client": "text"
    },
});
const data = await response.json();

Response

200

{
  "fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
  "registered": "2000-10-23T00:00:00.000Z",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "Post partum registration service",
  "status": {
    "code": "PENDING",
    "title": "Pending"
  },
  "ended": "false",
  "applicationData": {
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
    },
    "documentUrls": [
      "text"
    ]
  }
}

Update service application file with operator's form data

Returns updated service application file ID

PUT/applications/{fileId}

Path parameters

fileId*string

Header parameters

Body

application/json

Update application file data with operators input

applicationNamestring

Free text application name

Example: "Amya Yuko"

applicantId*string

Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

createdstring (date-time)

Time when the application file was created by the user- Draft

Example: "2000-10-23T00:00:00.000Z"

formDataformData (object)

documentUrlsdocumentUrls (array of string)

Response

200404500

Returns updated application file

Body

*/*

fileIdstring

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: "81c4445c-bff6-11ed-afa1-0242ac120002"

registeredstring (date-time)

Time when the application file was registered in the Registration BB system

Example: "2000-10-23T00:00:00.000Z"

serviceId*string (uuid)

id of the service this application relates to

serviceNamestring

Example: "Post partum registration service"

statusstatusModel (object)

endedboolean

True, if application file processing has ended

Example: "false"

applicationDataapplicationFileSubmit (object)

Request

JavaScriptCurlPython

const response = await fetch('/applications/{fileId}', {
    method: 'PUT',
    headers: {
      "Information-Mediator-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004"
    }),
});
const data = await response.json();

Response

200500

{
  "fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
  "registered": "2000-10-23T00:00:00.000Z",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "Post partum registration service",
  "status": {
    "code": "PENDING",
    "title": "Pending"
  },
  "ended": "false",
  "applicationData": {
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
    },
    "documentUrls": [
      "text"
    ]
  }
}

Retrieve all tasks

Returns task list

GET/tasks

Query parameters

Response

200

list of tasks or an empty array if none are available

Body

*/*

taskIdstring

mainTaskIdstring

namestring

assigneeIdstring

roleIdstring

createdstring (date-time)

descriptionstring

serviceIdstring (uuid)

serviceNamestring

fileIdstring

eFormIdstring

statusstatusModel (object)

Request

JavaScriptCurlPython

const response = await fetch('/tasks', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "taskId": "text",
    "mainTaskId": "text",
    "name": "text",
    "assigneeId": "text",
    "roleId": "text",
    "created": "2024-11-05T13:57:58.168Z",
    "description": "text",
    "serviceId": "123e4567-e89b-12d3-a456-426614174000",
    "serviceName": "text",
    "fileId": "text",
    "eFormId": "text",
    "status": {
      "code": "PENDING",
      "title": "Pending"
    }
  }
]

Get task by id

Returns task by id

GET/tasks/{taskId}

Path parameters

taskId*string

Response

200404

Returns task by id

Body

*/*

taskIdstring

taskNamestring

assigneeIdstring

roleIdstring

Example: "42962de0-bdb2-11ed-9397-0242ac120004"

createdstring (date-time)

descriptionstring

fileIdstring

serviceIdstring (uuid)

serviceNamestring

eFormIdstring

formVariablesobject

statusstatusModel (object)

dataobject

Request

JavaScriptCurlPython

const response = await fetch('/tasks/{taskId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "taskId": "text",
  "taskName": "text",
  "assigneeId": "text",
  "roleId": "42962de0-bdb2-11ed-9397-0242ac120004",
  "created": "2024-11-05T13:57:58.168Z",
  "description": "text",
  "fileId": "text",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "text",
  "eFormId": "text",
  "status": {
    "code": "PENDING",
    "title": "Pending"
  }
}

Complete task by id

POST/tasks/{taskId}/complete

Path parameters

taskId*string

Body

application/json

dataobject

Response

200404500

Task successfully completed

Body

*/*

taskIdstring

fileIdstring

serviceIdstring (uuid)

statusstatusModel (object)

variablesobject

Request

JavaScriptCurlPython

const response = await fetch('/tasks/{taskId}/complete', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200500

{
  "taskId": "text",
  "fileId": "text",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "status": {
    "code": "PENDING",
    "title": "Pending"
  }
}

8.3 Development Platform

Currently there are no specifications for API endpoints to manage and design services and workflows.

Statistics

The statistics API gives Building Block operational statistics, that reference the number of processed applications (per operator, registration, service, date):

API endpoint that allows anyone to see service statistics

GET/data/statistics

Query parameters

Header parameters

Response

200400404

Success Response

Body

application/json

processedinteger

How many applications was processed

Example: 100

approvedinteger

How many applications was approved

Example: 90

sentBackinteger

How many applications was sent back

Example: 3

rejectedinteger

How many applications was rejected

Example: 7

referencesdatastatistics1.0_references (object)

Data that was requested

Request

JavaScriptCurlPython

const response = await fetch('/data/statistics', {
    method: 'GET',
    headers: {
      "Information-Mediator-Client": "text"
    },
});
const data = await response.json();

Response

200

[
  {
    "processed": 100,
    "approved": 90,
    "sentBack": 3,
    "rejected": 7,
    "references": {
      "startDate": "2021-01-30",
      "endDate": "2021-01-30",
      "registrationName": "MCTS",
      "operator": "Ingmar Vali",
      "role": "Handler",
      "timeframeDay": true,
      "timeframeWeek": false,
      "timeframeMonth": false,
      "timeframeYear": false
    }
  }
]