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:
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.
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.
List of Clients of GovStack
Error in request
Internal error
GET /listClients HTTP/1.1
Host:
Accept: */*
{
"member": [
{
"name": "text",
"id": {
"objectType": "MEMBER",
"instanceId": "text",
"memberClass": "text",
"memberCode": "text",
"applicationCode": "text"
}
}
]
}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.
This function provides a list of all REST services and service endpoints offered by a service provider.
List of REST services and endpoints for a service provider
Error in request
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/listMethods HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
{
"member": [
{
"objectType": "MEMBER",
"serviceType": "text",
"instanceId": "text",
"memberClass": "text",
"memberCode": "text",
"applicationCode": "text",
"serviceCode": "text",
"serviceVersion": "text",
"endpointList": {
"member": [
{
"method": "text",
"path": "text"
}
]
}
}
]
}This function provides a list of REST services and service endpoints offered by a service provider that the caller has permission to invoke.
List of allowed REST services and endpoints for a service provider
Error in request
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/allowedMethods HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
{
"member": [
{
"objectType": "MEMBER",
"serviceType": "text",
"instanceId": "text",
"memberClass": "text",
"memberCode": "text",
"applicationCode": "text",
"serviceCode": "text",
"serviceVersion": "text",
"endpointList": {
"member": [
{
"method": "text",
"path": "text"
}
]
}
}
]
}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.
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.
OpenAPI description of the specified REST service
Error in request
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI?serviceCode=text HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
text8.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
Return list of my subscriptions in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
List of my subscriptions
Subscription missing
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
[
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"subscriberId": {
"instanceId": "neverland",
"memberClass": "GOV",
"memberCode": "capitalCity",
"applicationCode": "police"
},
"eventType": "newBirth",
"delivery": "PUSH",
"options": {
"TTL": 3600,
"FIFO": false
}
}
]Subscribe caller to {eventType} in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
newBirthPUSHPossible values: Subscription created
No content
Invalid request
Subscription already exists
Internal error
POST /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 238
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"subscriberId": {
"instanceId": "neverland",
"memberClass": "GOV",
"memberCode": "capitalCity",
"applicationCode": "police"
},
"eventType": "newBirth",
"delivery": "PUSH",
"options": {
"TTL": 3600,
"FIFO": false
}
}No content
Return details of subscription to {eventType} in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
Subscription details
Subscription missing
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"subscriberId": {
"instanceId": "neverland",
"memberClass": "GOV",
"memberCode": "capitalCity",
"applicationCode": "police"
},
"eventType": "newBirth",
"delivery": "PUSH",
"options": {
"TTL": 3600,
"FIFO": false
}
}Update details of subscription to {eventType} in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
newBirthPUSHPossible values: Subscription details
Invalid request
Subscription missing
Internal error
PATCH /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 238
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"subscriberId": {
"instanceId": "neverland",
"memberClass": "GOV",
"memberCode": "capitalCity",
"applicationCode": "police"
},
"eventType": "newBirth",
"delivery": "PUSH",
"options": {
"TTL": 3600,
"FIFO": false
}
}No content
Unsubscribe
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
Subscription deleted
Subscription missing
Internal error
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
No content
8.3.2 PULL delivery mode API
Return next unacknowledged event of type defined by {eventType} and located in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
Event
No event available
Invalid request
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"sequence": 42,
"publisherId": {
"instanceId": "neverland",
"memberClass": "GOV",
"memberCode": "capital-city",
"applicationCode": "police"
},
"eventType": "newBirth",
"event": {
"dateTime": "2023-05-01T11:25:00+02:00",
"gender": "M",
"mother": "Jane Doe",
"place": "City Hospital",
"details": {
"weight": 3200,
"length": 49,
"eyesColor": "brown"
}
}
}Acknowledge receiving of event from the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
event id
Event acknowledged
no event available
invalid request
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}/{eventId} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
No content
8.3.3 Publisher API
Publish event in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
newBirth{"dateTime":"2023-05-01T11:25:00+02:00","gender":"M","mother":"Jane Doe","place":"City Hospital","details":{"weight":3200,"length":49,"eyesColor":"brown"}}Event accepted for publishing. Returning event id
Invalid request
Unknown event type
Internal error
POST /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 188
{
"eventType": "newBirth",
"event": {
"dateTime": "2023-05-01T11:25:00+02:00",
"gender": "M",
"mother": "Jane Doe",
"place": "City Hospital",
"details": {
"weight": 3200,
"length": 49,
"eyesColor": "brown"
}
}
}{
"id": "123e4567-e89b-12d3-a456-426614174000"
}Return event status info. Event is located in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
event id of event
Event status
Event missing
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"sequence": 42,
"publisherId": {
"instanceId": "neverland",
"memberClass": "GOV",
"memberCode": "capital-city",
"applicationCode": "police"
},
"eventType": "newBirth",
"event": {
"dateTime": "2023-05-01T11:25:00+02:00",
"gender": "M",
"mother": "Jane Doe",
"place": "City Hospital",
"details": {
"weight": 3200,
"length": 49,
"eyesColor": "brown"
}
}
}Stop processing of the event. Event is located in the room {applicationId}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
event id of event
Event processing stopped
Event missing
Internal error
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
No content
8.3.4 Event Type API
Create new event type in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
newBirth{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "dateTime": { "type": "string", "format": "date-time" }, "gender": { "type": "string", "enum": ["M", "F"] }, "mother": { "type": "string" }, "place": { "type": "string" }, "id": { "type": "integer" }, "details": { "type": "object", "properties": { "weight": { "type": "number" }, "length": { "type": "number" }, "eyesColor": { "type": "string" } }, "required": ["weight", "length", "eyesColor"] } }, "required": ["dateTime", "gender", "mother", "place"] }Event type created
No content
Invalid request
Event type already exists
Internal error
POST /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType HTTP/1.1
Host:
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 864
{
"eventType": "newBirth",
"schema": "{ \"$schema\": \"http://json-schema.org/draft-07/schema#\", \"type\": \"object\", \"properties\": {\n \"dateTime\": {\n \"type\": \"string\",\n \"format\": \"date-time\"\n },\n \"gender\": {\n \"type\": \"string\",\n \"enum\": [\"M\", \"F\"]\n },\n \"mother\": {\n \"type\": \"string\"\n },\n \"place\": {\n \"type\": \"string\"\n },\n \"id\": {\n \"type\": \"integer\"\n },\n \"details\": {\n \"type\": \"object\",\n \"properties\": {\n \"weight\": {\n \"type\": \"number\"\n },\n \"length\": {\n \"type\": \"number\"\n },\n \"eyesColor\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\"weight\", \"length\", \"eyesColor\"]\n }\n}, \"required\": [\"dateTime\", \"gender\", \"mother\", \"place\"] }"
}No content
Return list of event types located in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
Event type list
Event types does not defined
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
[
"newBirth"
]Return event type description. Event type is located in the room {applicationCode}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
Event type details
Event type does not defined
Internal error
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
{
"eventType": "newBirth",
"schema": "{ \"$schema\": \"http://json-schema.org/draft-07/schema#\", \"type\": \"object\", \"properties\": {\n \"dateTime\": {\n \"type\": \"string\",\n \"format\": \"date-time\"\n },\n \"gender\": {\n \"type\": \"string\",\n \"enum\": [\"M\", \"F\"]\n },\n \"mother\": {\n \"type\": \"string\"\n },\n \"place\": {\n \"type\": \"string\"\n },\n \"id\": {\n \"type\": \"integer\"\n },\n \"details\": {\n \"type\": \"object\",\n \"properties\": {\n \"weight\": {\n \"type\": \"number\"\n },\n \"length\": {\n \"type\": \"number\"\n },\n \"eyesColor\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\"weight\", \"length\", \"eyesColor\"]\n }\n}, \"required\": [\"dateTime\", \"gender\", \"mother\", \"place\"] }"
}Delete event type in the room {applicationId}
Certs are exchanged between parties and stored in configuration to have fixed one-to-one connection
Event type deleted
Event type missing
Internal error
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType} HTTP/1.1
Host:
X-GovStack-Client: text
Accept: */*
No content
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
Configuration description of IM is returned in form of file
- : Grants read access to IM configuration
List of IM configuration
Internal error
GET /api/v1/config HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"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"
}
]
}
]
}
]
}
]
}Create new instance of IM
- : Grants write access to IM configuration
Creates Central Servers if init=true
falseSubdomain for GovStack instance to run in
sample.sandbox.govstack.globalName of GovStack instance
nowherelandIM starts configuration creation
Error in request
Internal error
POST /api/v1/config HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 475
{
"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"
}
]
}
]
}
]
}
]
}textUpdate IM configuration. Not described parts are not changed
- : Grants write access to IM configuration
Subdomain for GovStack instance to run in
sample.sandbox.govstack.globalName of GovStack instance
nowherelandIM starts configuration update
Error in request
Internal error
PATCH /api/v1/config HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 475
{
"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"
}
]
}
]
}
]
}
]
}textReplace IM configuration. Not described parts are deleted
- : Grants permission to create IM configuration
Subdomain for GovStack instance to run in
sample.sandbox.govstack.globalName of GovStack instance
nowherelandIM starts configuration creation
Error in request
Internal error
PUT /api/v1/config HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 475
{
"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"
}
]
}
]
}
]
}
]
}textIs IM configured. up and running?
- : Grants read access to IM configuration
IM is OK
No content
Internal error
GET /api/v1/status HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
No content
8.6.2 Management of Access Rights
This API takes provided filters from query parameters and returns a subset of access policies configured on the IM building block, based on the filters.
The result is paged, with page size based on the number of service and allowed application pairs. For example, when pageSize = 10 and the IM BB defines three services: A, B and C, each of which has 8 clients, the result will be split over 3 pages: Page 1: Service A, with all of its 8 allowed applications, Service B with 2 allowed applications. Page 2: Service B, with 6 allowed applications left over, Service C with 4 applications. Page 3: Service C, with 4 applications.
Implementations can define additional query parameters for result display (such as ordering) and how next page tokens are implemented. It is expected that the next page token is not readable by API users and will be provided verbatim when querying the next page of results.
- : Grants permission to see what services are allowed
Filter by member class
Filter by member code
Filter by application ID
Filter by service ID
Number of access rights returned on one page
100Handle for the next page, if the result spans multiple pages. If not specified, there are no more results.
OK
Caller does not have permissions to view access rights
GET /api/v1/rights/allow HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"nextPageToken": "text",
"allowList": [
{
"memberClass": "GOV",
"memberCode": "7001",
"applicationId": "CitizensRegistry",
"serviceId": "registration",
"rights": [
{
"memberClass": "text",
"memberCode": "text",
"applicationId": "text"
}
]
}
]
}- : Grants permission to allow/deny IM services
Kind of organisation. Namespace for organisation {code}
GOVRegistration number (or identifier) of the organisation in {memberClass} namespace
7001Name of application
CitizensRegistryName of service/API
registrationOK
No content
Caller does not have the necessary permissions to update access rights
PATCH /api/v1/rights/allow HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 182
[
{
"memberClass": "GOV",
"memberCode": "7001",
"applicationId": "CitizensRegistry",
"serviceId": "registration",
"rights": [
{
"memberClass": "text",
"memberCode": "text",
"applicationId": "text"
}
]
}
]No content
- : Grants permission to allow/deny IM services
Kind of organisation. Namespace for organisation {code}
GOVRegistration number (or identifier) of the organisation in {memberClass} namespace
7001Name of application
CitizensRegistryName of service/API
registrationOK
No content
Caller does not have the necessary permissions to update access rights
PATCH /api/v1/rights/deny HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 182
[
{
"memberClass": "GOV",
"memberCode": "7001",
"applicationId": "CitizensRegistry",
"serviceId": "registration",
"rights": [
{
"memberClass": "text",
"memberCode": "text",
"applicationId": "text"
}
]
}
]No content
Was this helpful?