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:
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.
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.
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.
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.
To get info from system log, an administrator may send a request to the logging API.
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.
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
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
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
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
Unsubscribe
Subscription deleted
Acknowledge receiving of event from the room {applicationCode}
event id
Event acknowledged
Stop processing of the event. Event is located in the room {applicationId}
event id of event
Event processing stopped
Delete event type in the room {applicationId}
Event type deleted
Return list of event types located in the room {applicationCode}
Event type list
Return event type description. Event type is located in the room {applicationCode}
Event type details
Create new event type in the room {applicationCode}
Event type created
Publish event in the room {applicationCode}
Event accepted for publishing. Returning event id
Return details of subscription to {eventType} in the room {applicationCode}
Subscription details
Return list of my subscriptions in the room {applicationCode}
List of my subscriptions
Subscribe caller to {eventType} in the room {applicationCode}
Subscription item to add
Subscription created
Update details of subscription to {eventType} in the room {applicationCode}
New details of subscription
Subscription details
Return event status info. Event is located in the room {applicationCode}
event id of event
Event status
Return next unacknowledged event of type defined by {eventType} and located in the room {applicationCode}
event type
Event
Is IM configured. up and running?
IM is OK
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {memberClass} namespace
"7001"
Name of application
"CitizensRegistry"
Name of service/API
"registration"
Applications that are allowed or denied access
Member or member group identifier to whom access is granted
Member or member group identifier to whom access is granted
Application of the member that to whom access is granted
OK
Filter by member class
Filter by member code
Filter by application ID
Filter by service ID
Number of access rights returned on one page
Handle for the next page, if the result spans multiple pages. If not specified, there are no more results.
OK
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {memberClass} namespace
"7001"
Name of application
"CitizensRegistry"
Name of service/API
"registration"
Applications that are allowed or denied access
Member or member group identifier to whom access is granted
Member or member group identifier to whom access is granted
Application of the member that to whom access is granted
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {memberClass} namespace
"7001"
Name of application
"CitizensRegistry"
Name of service/API
"registration"
Applications that are allowed or denied access
Member or member group identifier to whom access is granted
Member or member group identifier to whom access is granted
Application of the member that to whom access is granted
OK
Configuration description of IM is returned in form of file
List of IM configuration
Subdomain for GovStack instance to run in
"sample.sandbox.govstack.global"
Name of GovStack instance
"nowhereland"
List of Member organisations
Organisation (Member) name
"Ministry of Interior"
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {class} namespace
"7001"
List of applications of Member organisation
Name of application
"CitizensRegistry"
Connection protocol of application
"http"
List of services
Name of service/API
"registration"
Location of OpenAPI spec file
"https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"
Location of service endpoints
"http://hostname.internal/api/v1/registration"
List of allowed consumers/clients
Name of Member
"LocalMunicipality"
Name of application
"RegistrationPortal"
Update IM configuration. Not described parts are not changed
configuration description file
Subdomain for GovStack instance to run in
"sample.sandbox.govstack.global"
Name of GovStack instance
"nowhereland"
List of Member organisations
Organisation (Member) name
"Ministry of Interior"
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {class} namespace
"7001"
List of applications of Member organisation
Name of application
"CitizensRegistry"
Connection protocol of application
"http"
List of services
Name of service/API
"registration"
Location of OpenAPI spec file
"https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"
Location of service endpoints
"http://hostname.internal/api/v1/registration"
List of allowed consumers/clients
Name of Member
"LocalMunicipality"
Name of application
"RegistrationPortal"
IM starts configuration update
Replace IM configuration. Not described parts are deleted
configuration description file
Subdomain for GovStack instance to run in
"sample.sandbox.govstack.global"
Name of GovStack instance
"nowhereland"
List of Member organisations
Organisation (Member) name
"Ministry of Interior"
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {class} namespace
"7001"
List of applications of Member organisation
Name of application
"CitizensRegistry"
Connection protocol of application
"http"
List of services
Name of service/API
"registration"
Location of OpenAPI spec file
"https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"
Location of service endpoints
"http://hostname.internal/api/v1/registration"
List of allowed consumers/clients
Name of Member
"LocalMunicipality"
Name of application
"RegistrationPortal"
IM starts configuration creation
Create new instance of IM
Creates Central Servers if init=true
configuration description file
Subdomain for GovStack instance to run in
"sample.sandbox.govstack.global"
Name of GovStack instance
"nowhereland"
List of Member organisations
Organisation (Member) name
"Ministry of Interior"
Kind of organisation. Namespace for organisation {code}
"GOV"
Registration number (or identifier) of the organisation in {class} namespace
"7001"
List of applications of Member organisation
Name of application
"CitizensRegistry"
Connection protocol of application
"http"
List of services
Name of service/API
"registration"
Location of OpenAPI spec file
"https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json"
Location of service endpoints
"http://hostname.internal/api/v1/registration"
List of allowed consumers/clients
Name of Member
"LocalMunicipality"
Name of application
"RegistrationPortal"
IM starts configuration creation