1 of 1

8 Service APIs

This section provides a reference for APIs that should be implemented by 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 Information Mediator Building Block can be found in this GitHub repository.

The majority of functions provided by the Information Mediator Building Block are either defined in the “service access flow” or configured by the administrator via the web User Interface. There is, however, a “Directory Service” which can provide listings of clients, methods, and available API specifications for services on the Information Mediator. The directory is managed by admins of members. The directory service centralizes and offers knowledge of all enrolled members and their services along with the information necessary to bind a third-party application as a consumer of that service. These services are described here:

API metadata

and changes to the API definitions can be made by submitting a pull request on this repository. 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 services can be accessed via the following Service APIs:

8.1 Service Access

The full API definition of all available services is the set of all available OpenAPI descriptions.

One can take any of the available OpenAPI descriptions and call service according to that description.

This call must be forwarded to IM local Security Server and path part of the called URL must begin with the address of service in the form /r1/{instanceId}/{memberClass}/{member}/{application}/{service}/ followed by the service path with possible query parameters. The address of the service may be already listed in the OpenAPI description or must be added to the path if not provided by OpenAPI.

8.2 Directory Services

8.2.1 Member Discovery

At development time, to see which organizations are available on GovStack, an administrator of application A sends a GET request to the security server: url-of-local-information-mediator-security-server/r1/listClients

The response is an array of organizations with descriptions. API MAY implement paging of output.

8.2.2 Service Discovery

At development time, an administrator at application A sends a GET request to the security server: url-of-local-information-mediator-security-server/r1/INDIA/GOV/MEMBER/APPLICATION/{listMethods || allowedMethods}

The response is an array of services (either all services or services that the requester is authorized to access via “allowedMethods”). API MAY implement paging of output.

At development time, to learn about an available service, an administrator at application A sends a GET request to the security server: url-of-local-information-mediator-security-server/r1/INDIA/GOV/MEMBER/APPLICATION/getOpenApi?serviceCode=SERVICE

The response is an OpenAPI specification, detailing the endpoints and requirements for that service/API of the requested Service of Application.

8.3 Pub/Sub Service

To broadcast a message to a Room, the service access API must be followed and the service requested must be the service implementing event type.

8.3.1 Subscriber API

8.3.2 PULL delivery mode API

8.3.3 Publisher API

8.3.4 Event Type API

8.4 Logging Services

To get info from system log, an administrator may send a request to the logging API.

8.5 Monitoring Services

At the debugging time, to learn about system performance or retrieve an audit log, an administrator may send a request to the reporting API.

The response is <audit trail>, <metrics>, etc.

8.6 Management API

8.6.1 Configuration Management

8.6.2 Management of Access Rights

8 Service APIs

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

The tests for the Information Mediator Building Block can be found in this GitHub repository.

API metadata

The services can be accessed via the following Service APIs:

8.1 Service Access

The full API definition of all available services is the set of all available OpenAPI descriptions.

One can take any of the available OpenAPI descriptions and call service according to that description.

8.2 Directory Services

8.2.1 Member Discovery

The response is an array of organizations with descriptions. API MAY implement paging of output.

List clients defined in the instance

Clients of the security server have the capability to obtain a list of potential service providers within a GovStack instance, including both members and applications. To do so, they should initiate an HTTP GET request to the security server. The specific request URL will be either http://SECURITYSERVER/listClients or https://SECURITYSERVER/listClients, depending on whether HTTPS protocol usage is enabled for interaction.

When submitting this request, the placeholder SECURITYSERVER must be replased with the actual address of the security server. One can also retrieve a list of clients from other federated GovStack instances by adding an additional HTTP parameter:

instanceId - a code of the instance.

For instance, if you wish to fetch the list of clients associated with the instance labeled as ABC, your request URL should take the form of http://SECURITYSERVER/listClients?instanceId=ABC.

GET/listClients

Query parameters

instanceIdstring

Response

List of Clients of GovStack

Body

memberarray of restClientDetailsType (object)

namestring

idobject

objectTypeenum

MEMBERAPPLICATIONSERVICE

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

Request

Response

8.2.2 Service Discovery

The response is an array of services (either all services or services that the requester is authorized to access via “allowedMethods”). API MAY implement paging of output.

List REST services and endpoints for a service provider

This function provides a list of all REST services and service endpoints offered by a service provider.

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/listMethods

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Query parameters

serviceIdstring

Header parameters

X-GovStack-Client*string

Response

List of REST services and endpoints for a service provider

Body

memberarray of restServiceDetailsType (object)

objectTypeenum

MEMBERAPPLICATIONSERVICE

serviceTypestring

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

serviceCodestring

serviceVersionstring

endpointListobject

memberarray of endpoint (object)

methodstring

pathstring

Request

Response

List of allowed REST services and endpoints for a service provider

This function provides a list of REST services and service endpoints offered by a service provider that the caller has permission to invoke.

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/allowedMethods

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Query parameters

serviceIdstring

Header parameters

X-GovStack-Client*string

Response

List of allowed REST services and endpoints for a service provider

Body

memberarray of restServiceDetailsType (object)

objectTypeenum

MEMBERAPPLICATIONSERVICE

serviceTypestring

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

serviceCodestring

serviceVersionstring

endpointListobject

memberarray of endpoint (object)

methodstring

pathstring

Request

Response

The response is an OpenAPI specification, detailing the endpoints and requirements for that service/API of the requested Service of Application.

Returns OpenAPI service description for a REST service

This metaservice is designed to retrieve service descriptions for REST services. It provides the OpenAPI service description for a specific REST service. To use this service, the query parameters should include serviceCode=xxx, where xxx corresponds to the service code of the particular REST service for which you desire to obtain the service description.

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Query parameters

serviceCode*string

Header parameters

X-GovStack-Client*string

Response

OpenAPI description of the specified REST service

Body

string

Request

Response

8.3 Pub/Sub Service

To broadcast a message to a Room, the service access API must be followed and the service requested must be the service implementing event type.

8.3.1 Subscriber API

list my subscriptions

Return list of my subscriptions in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Header parameters

X-GovStack-Client*string

Response

List of my subscriptions

Body

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscriberId": {
      "instanceId": "text",
      "memberClass": "text",
      "memberCode": "text",
      "applicationCode": "text"
    },
    "eventType": "text",
    "delivery": "PUSH",
    "options": {
      "FIFO": false
    }
  }
]

add subscription

Subscribe caller to {eventType} in the room {applicationCode}

POST/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Body

Subscription item to add

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Response

Subscription created

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'POST',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

get subscription details

Return details of subscription to {eventType} in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Response

Subscription details

Body

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "subscriberId": {
    "instanceId": "text",
    "memberClass": "text",
    "memberCode": "text",
    "applicationCode": "text"
  },
  "eventType": "text",
  "delivery": "PUSH",
  "options": {
    "FIFO": false
  }
}

update subscription details

Update details of subscription to {eventType} in the room {applicationCode}

PATCH/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Body

New details of subscription

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Response

Subscription details

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'PATCH',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

cancel subscription

Unsubscribe

DELETE/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Response

Subscription deleted

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'DELETE',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

8.3.2 PULL delivery mode API

get next unacknowledged event

Return next unacknowledged event of type defined by {eventType} and located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

event type

Header parameters

X-GovStack-Client*string

Response

Event

Body

id*string (uuid)

sequenceinteger

publisherIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventTypestring

eventobject

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "publisherId": {
    "instanceId": "text",
    "memberClass": "text",
    "memberCode": "text",
    "applicationCode": "text"
  },
  "eventType": "text"
}

confirm event

Acknowledge receiving of event from the room {applicationCode}

DELETE/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}/{eventId}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

eventId*string

event id

Header parameters

X-GovStack-Client*string

Response

Event acknowledged

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}/{eventId}', {
    method: 'DELETE',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

8.3.3 Publisher API

publish event

Publish event in the room {applicationCode}

POST/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Body

eventType*string

event*object

Response

Event accepted for publishing. Returning event id

Body

id*string (uuid)

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}', {
    method: 'POST',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

get published event status

Return event status info. Event is located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

eventId*string

event id of event

Header parameters

X-GovStack-Client*string

Response

Event status

Body

id*string (uuid)

sequenceinteger

publisherIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventTypestring

eventobject

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "publisherId": {
    "instanceId": "text",
    "memberClass": "text",
    "memberCode": "text",
    "applicationCode": "text"
  },
  "eventType": "text"
}

delete event publication

Stop processing of the event. Event is located in the room {applicationId}

DELETE/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

eventId*string

event id of event

Header parameters

X-GovStack-Client*string

Response

Event processing stopped

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}', {
    method: 'DELETE',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

8.3.4 Event Type API

create event type

Create new event type in the room {applicationCode}

POST/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Header parameters

X-GovStack-Client*string

Body

eventType*string

schema*object

Response

Event type created

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType', {
    method: 'POST',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

get list of event types

Return list of event types located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Header parameters

X-GovStack-Client*string

Response

Event type list

Body

itemsstring

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

[
  "text"
]

get event type details

Return event type description. Event type is located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Response

Event type details

Body

eventType*string

schema*object

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "eventType": "text"
}

delete event type

Delete event type in the room {applicationId}

DELETE/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Response

Event type deleted

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}', {
    method: 'DELETE',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

8.4 Logging Services

To get info from system log, an administrator may send a request to the logging API.

8.5 Monitoring Services

At the debugging time, to learn about system performance or retrieve an audit log, an administrator may send a request to the reporting API.

The response is <audit trail>, <metrics>, etc.

8.6 Management API

8.6.1 Configuration Management

List IM configuration

Configuration description of IM is returned in form of file

GET/api/v1/config

Authorization

Response

List of IM configuration

Body

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Request

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

Response

{
  "domain": "sample.sandbox.govstack.global",
  "instance": "nowhereland",
  "members": [
    {
      "name": "Ministry of Interior",
      "class": "GOV",
      "code": "7001",
      "applications": [
        {
          "id": "CitizensRegistry",
          "connection": "http",
          "services": [
            {
              "id": "registration",
              "specUrl": "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json",
              "serviceUrl": "http://hostname.internal/api/v1/registration",
              "rights": [
                {
                  "member": "LocalMunicipality",
                  "application": "RegistrationPortal"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Initialize IM instance

Create new instance of IM

POST/api/v1/config

Authorization

Query parameters

initboolean

Creates Central Servers if init=true

Body

configuration description file

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Response

IM starts configuration creation

Body

IMconfResponse (string)

Request

const response = await fetch('/api/v1/config', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "domain": "sample.sandbox.govstack.global",
      "instance": "nowhereland"
    }),
});
const data = await response.json();

Response

text

Update IM configuration

Update IM configuration. Not described parts are not changed

PATCH/api/v1/config

Authorization

Body

configuration description file

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Response

IM starts configuration update

Body

IMconfResponse (string)

Request

const response = await fetch('/api/v1/config', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "domain": "sample.sandbox.govstack.global",
      "instance": "nowhereland"
    }),
});
const data = await response.json();

Response

text

Replace IM configuration

Replace IM configuration. Not described parts are deleted

PUT/api/v1/config

Authorization

Body

configuration description file

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Response

IM starts configuration creation

Body

IMconfResponse (string)

Request

const response = await fetch('/api/v1/config', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "domain": "sample.sandbox.govstack.global",
      "instance": "nowhereland"
    }),
});
const data = await response.json();

Response

text

Check status

Is IM configured. up and running?

GET/api/v1/status

Authorization

Response

IM is OK

Request

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

8.6.2 Management of Access Rights

Retrieve configured access permissions (allow list)

GET/api/v1/rights/allow

Authorization

Query parameters

memberClassstring

Filter by member class

memberCodestring

Filter by member code

applicationIdstring

Filter by application ID

serviceIdstring

Filter by service ID

pageSizenumber

Number of access rights returned on one page

nextPageTokenstring

Handle for the next page, if the result spans multiple pages. If not specified, there are no more results.

Response

Body

nextPageTokenstring

allowListServiceAccessRights (array of object)

memberClass*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

memberCode*string

Registration number (or identifier) of the organisation in {memberClass} namespace

Example: "7001"

applicationId*string

Name of application

Example: "CitizensRegistry"

serviceId*string

Name of service/API

Example: "registration"

rights*array of AllowedApplication (object)

Applications that are allowed or denied access

memberClassstring

Member or member group identifier to whom access is granted

memberCodestring

Member or member group identifier to whom access is granted

applicationIdstring

Application of the member that to whom access is granted

Request

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

Response

{
  "nextPageToken": "text",
  "allowList": [
    {
      "memberClass": "GOV",
      "memberCode": "7001",
      "applicationId": "CitizensRegistry",
      "serviceId": "registration",
      "rights": [
        {
          "memberClass": "text",
          "memberCode": "text",
          "applicationId": "text"
        }
      ]
    }
  ]
}

Allow access to services

PATCH/api/v1/rights/allow

Authorization

Body

memberClass*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

memberCode*string

Registration number (or identifier) of the organisation in {memberClass} namespace

Example: "7001"

applicationId*string

Name of application

Example: "CitizensRegistry"

serviceId*string

Name of service/API

Example: "registration"

rights*array of AllowedApplication (object)

Applications that are allowed or denied access

memberClassstring

Member or member group identifier to whom access is granted

memberCodestring

Member or member group identifier to whom access is granted

applicationIdstring

Application of the member that to whom access is granted

Response

Request

const response = await fetch('/api/v1/rights/allow', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "memberClass": "GOV",
        "memberCode": "7001",
        "applicationId": "CitizensRegistry",
        "serviceId": "registration",
        "rights": [
          {}
        ]
      }
    ]),
});
const data = await response.json();

Deny access to services

PATCH/api/v1/rights/deny

Authorization

Body

memberClass*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

memberCode*string

Registration number (or identifier) of the organisation in {memberClass} namespace

Example: "7001"

applicationId*string

Name of application

Example: "CitizensRegistry"

serviceId*string

Name of service/API

Example: "registration"

rights*array of AllowedApplication (object)

Applications that are allowed or denied access

memberClassstring

Member or member group identifier to whom access is granted

memberCodestring

Member or member group identifier to whom access is granted

applicationIdstring

Application of the member that to whom access is granted

Response

Request

const response = await fetch('/api/v1/rights/deny', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "memberClass": "GOV",
        "memberCode": "7001",
        "applicationId": "CitizensRegistry",
        "serviceId": "registration",
        "rights": [
          {}
        ]
      }
    ]),
});
const data = await response.json();

Returns OpenAPI service description for a REST service

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Query parameters

serviceCode*string

Header parameters

X-GovStack-Client*string

Response

OpenAPI description of the specified REST service

Body

string

Request

Response

List clients defined in the instance

instanceId - a code of the instance.

For instance, if you wish to fetch the list of clients associated with the instance labeled as ABC, your request URL should take the form of http://SECURITYSERVER/listClients?instanceId=ABC.

GET/listClients

Query parameters

instanceIdstring

Response

List of Clients of GovStack

Body

memberarray of restClientDetailsType (object)

namestring

idobject

objectTypeenum

MEMBERAPPLICATIONSERVICE

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

Request

Response

Deny access to services

PATCH/api/v1/rights/deny

Authorization

Body

memberClass*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

memberCode*string

Registration number (or identifier) of the organisation in {memberClass} namespace

Example: "7001"

applicationId*string

Name of application

Example: "CitizensRegistry"

serviceId*string

Name of service/API

Example: "registration"

rights*array of AllowedApplication (object)

Applications that are allowed or denied access

memberClassstring

Member or member group identifier to whom access is granted

memberCodestring

Member or member group identifier to whom access is granted

applicationIdstring

Application of the member that to whom access is granted

Response

Request

const response = await fetch('/api/v1/rights/deny', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "memberClass": "GOV",
        "memberCode": "7001",
        "applicationId": "CitizensRegistry",
        "serviceId": "registration",
        "rights": [
          {}
        ]
      }
    ]),
});
const data = await response.json();

Retrieve configured access permissions (allow list)

GET/api/v1/rights/allow

Authorization

Query parameters

memberClassstring

Filter by member class

memberCodestring

Filter by member code

applicationIdstring

Filter by application ID

serviceIdstring

Filter by service ID

pageSizenumber

Number of access rights returned on one page

nextPageTokenstring

Handle for the next page, if the result spans multiple pages. If not specified, there are no more results.

Response

Body

nextPageTokenstring

allowListServiceAccessRights (array of object)

memberClass*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

memberCode*string

Registration number (or identifier) of the organisation in {memberClass} namespace

Example: "7001"

applicationId*string

Name of application

Example: "CitizensRegistry"

serviceId*string

Name of service/API

Example: "registration"

rights*array of AllowedApplication (object)

Applications that are allowed or denied access

memberClassstring

Member or member group identifier to whom access is granted

memberCodestring

Member or member group identifier to whom access is granted

applicationIdstring

Application of the member that to whom access is granted

Request

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

Response

{
  "nextPageToken": "text",
  "allowList": [
    {
      "memberClass": "GOV",
      "memberCode": "7001",
      "applicationId": "CitizensRegistry",
      "serviceId": "registration",
      "rights": [
        {
          "memberClass": "text",
          "memberCode": "text",
          "applicationId": "text"
        }
      ]
    }
  ]
}

Allow access to services

PATCH/api/v1/rights/allow

Authorization

Body

memberClass*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

memberCode*string

Registration number (or identifier) of the organisation in {memberClass} namespace

Example: "7001"

applicationId*string

Name of application

Example: "CitizensRegistry"

serviceId*string

Name of service/API

Example: "registration"

rights*array of AllowedApplication (object)

Applications that are allowed or denied access

memberClassstring

Member or member group identifier to whom access is granted

memberCodestring

Member or member group identifier to whom access is granted

applicationIdstring

Application of the member that to whom access is granted

Response

Request

const response = await fetch('/api/v1/rights/allow', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "memberClass": "GOV",
        "memberCode": "7001",
        "applicationId": "CitizensRegistry",
        "serviceId": "registration",
        "rights": [
          {}
        ]
      }
    ]),
});
const data = await response.json();

List IM configuration

Configuration description of IM is returned in form of file

GET/api/v1/config

Authorization

Response

List of IM configuration

Body

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Request

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

Response

{
  "domain": "sample.sandbox.govstack.global",
  "instance": "nowhereland",
  "members": [
    {
      "name": "Ministry of Interior",
      "class": "GOV",
      "code": "7001",
      "applications": [
        {
          "id": "CitizensRegistry",
          "connection": "http",
          "services": [
            {
              "id": "registration",
              "specUrl": "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json",
              "serviceUrl": "http://hostname.internal/api/v1/registration",
              "rights": [
                {
                  "member": "LocalMunicipality",
                  "application": "RegistrationPortal"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Update IM configuration

Update IM configuration. Not described parts are not changed

PATCH/api/v1/config

Authorization

Body

configuration description file

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Response

IM starts configuration update

Body

IMconfResponse (string)

Request

const response = await fetch('/api/v1/config', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "domain": "sample.sandbox.govstack.global",
      "instance": "nowhereland"
    }),
});
const data = await response.json();

Response

text

Replace IM configuration

Replace IM configuration. Not described parts are deleted

PUT/api/v1/config

Authorization

Body

configuration description file

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Response

IM starts configuration creation

Body

IMconfResponse (string)

Request

const response = await fetch('/api/v1/config', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "domain": "sample.sandbox.govstack.global",
      "instance": "nowhereland"
    }),
});
const data = await response.json();

Response

text

Initialize IM instance

Create new instance of IM

POST/api/v1/config

Authorization

Query parameters

initboolean

Creates Central Servers if init=true

Body

configuration description file

domain*string

Subdomain for GovStack instance to run in

Example: "sample.sandbox.govstack.global"

instance*string

Name of GovStack instance

Example: "nowhereland"

membersarray of object

List of Member organisations

name*string

Organisation (Member) name

Example: "Ministry of Interior"

class*string

Kind of organisation. Namespace for organisation {code}

Example: "GOV"

code*string

Registration number (or identifier) of the organisation in {class} namespace

Example: "7001"

applicationsarray of object

List of applications of Member organisation

id*string

Name of application

Example: "CitizensRegistry"

connectionstring

Connection protocol of application

Example: "http"

servicesarray of object

List of services

id*string

Name of service/API

Example: "registration"

specUrl*string (uri)

Location of OpenAPI spec file

Example: "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"

serviceUrl*string (uri)

Location of service endpoints

Example: "http://hostname.internal/api/v1/registration"

rightsarray of object

List of allowed consumers/clients

member*string

Name of Member

Example: "LocalMunicipality"

application*string

Name of application

Example: "RegistrationPortal"

Response

IM starts configuration creation

Body

IMconfResponse (string)

Request

const response = await fetch('/api/v1/config', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "domain": "sample.sandbox.govstack.global",
      "instance": "nowhereland"
    }),
});
const data = await response.json();

Response

text

get list of event types

Return list of event types located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Header parameters

X-GovStack-Client*string

Response

Event type list

Body

itemsstring

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

[
  "text"
]

get event type details

Return event type description. Event type is located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Response

Event type details

Body

eventType*string

schema*object

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "eventType": "text"
}

publish event

Publish event in the room {applicationCode}

POST/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Body

eventType*string

event*object

Response

Event accepted for publishing. Returning event id

Body

id*string (uuid)

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}', {
    method: 'POST',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

get subscription details

Return details of subscription to {eventType} in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Response

Subscription details

Body

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "subscriberId": {
    "instanceId": "text",
    "memberClass": "text",
    "memberCode": "text",
    "applicationCode": "text"
  },
  "eventType": "text",
  "delivery": "PUSH",
  "options": {
    "FIFO": false
  }
}

list my subscriptions

Return list of my subscriptions in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

Header parameters

X-GovStack-Client*string

Response

List of my subscriptions

Body

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscriberId": {
      "instanceId": "text",
      "memberClass": "text",
      "memberCode": "text",
      "applicationCode": "text"
    },
    "eventType": "text",
    "delivery": "PUSH",
    "options": {
      "FIFO": false
    }
  }
]

add subscription

Subscribe caller to {eventType} in the room {applicationCode}

POST/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Body

Subscription item to add

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Response

Subscription created

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'POST',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

update subscription details

Update details of subscription to {eventType} in the room {applicationCode}

PATCH/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

Header parameters

X-GovStack-Client*string

Body

New details of subscription

idstring (uuid)

subscriberIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventType*string

deliveryenum

PUSHPULL

optionsobject

TTLinteger

FIFOboolean

Response

Subscription details

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}', {
    method: 'PATCH',
    headers: {
      "X-GovStack-Client": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "eventType": "text"
    }),
});
const data = await response.json();

get published event status

Return event status info. Event is located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

eventId*string

event id of event

Header parameters

X-GovStack-Client*string

Response

Event status

Body

id*string (uuid)

sequenceinteger

publisherIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventTypestring

eventobject

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "publisherId": {
    "instanceId": "text",
    "memberClass": "text",
    "memberCode": "text",
    "applicationCode": "text"
  },
  "eventType": "text"
}

get next unacknowledged event

Return next unacknowledged event of type defined by {eventType} and located in the room {applicationCode}

GET/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}

Path parameters

instanceId*string

memberClass*string

memberCode*string

applicationCode*string

eventType*string

event type

Header parameters

X-GovStack-Client*string

Response

Event

Body

id*string (uuid)

sequenceinteger

publisherIdobject

instanceIdstring

memberClassstring

memberCodestring

applicationCodestring

eventTypestring

eventobject

Request

const response = await fetch('/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}', {
    method: 'GET',
    headers: {
      "X-GovStack-Client": "text"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "publisherId": {
    "instanceId": "text",
    "memberClass": "text",
    "memberCode": "text",
    "applicationCode": "text"
  },
  "eventType": "text"
}