# 8 Service APIs The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) 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](https://github.com/GovStackWorkingGroup/bb-information-mediator/tree/main/test/openAPI). 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](https://github.com/GovStackWorkingGroup/bb-information-mediator/blob/main/api/GovStack_IM_Directory_Services_API.yaml) 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. ## 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 \` > or \`, 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\ > \`.
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Service Metadata API","version":"1.0"},"paths":{"/listClients":{"get":{"tags":["metaservices"],"summary":"List clients defined in the instance","description":"Clients of the security server have the capability to obtain a list\nof potential service providers within a GovStack instance, including\nboth members and applications.\nTo do so, they should initiate an HTTP GET request to the security\nserver.\nThe specific request URL will be either `http://SECURITYSERVER/listClients`\nor `https://SECURITYSERVER/listClients`, depending on whether HTTPS\nprotocol usage is enabled for interaction.\n\nWhen submitting this request, the placeholder `SECURITYSERVER` must be\nreplased with the actual address of the security server. One can also\nretrieve a list of clients from other federated GovStack instances\nby adding an additional HTTP parameter:\n\n `instanceId` - a code of the instance.\n\nFor instance, if you wish to fetch the list of clients associated with the\ninstance labeled as `ABC`, your request URL should take the form of\n`http://SECURITYSERVER/listClients?instanceId=ABC`.\n","operationId":"listClients","parameters":[{"name":"instanceId","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of Clients of GovStack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/restClientDetailsListType"}}}},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}},"components":{"schemas":{"restClientDetailsListType":{"type":"object","properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/restClientDetailsType"}}}},"restClientDetailsType":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"object","properties":{"objectType":{"type":"string","enum":["MEMBER","APPLICATION","SERVICE"]},"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}}}}}}} ``` ### 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. ## 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.
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Service Metadata API","version":"1.0"},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/listMethods":{"get":{"tags":["metaservices"],"summary":"List REST services and endpoints for a service provider","description":"This function provides a list of all REST services and service endpoints\noffered by a service provider.\n","operationId":"listMethods","parameters":[{"name":"serviceId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of REST services and endpoints for a service provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/restServiceDetailsListType"}}}},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}},"components":{"schemas":{"restServiceDetailsListType":{"type":"object","properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/restServiceDetailsType"}}}},"restServiceDetailsType":{"type":"object","properties":{"objectType":{"type":"string","enum":["MEMBER","APPLICATION","SERVICE"]},"serviceType":{"type":"string"},"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"},"serviceCode":{"type":"string"},"serviceVersion":{"type":"string"},"endpointList":{"type":"object","properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/endpoint"}}}}}},"endpoint":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}}}} ``` ## 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.
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Service Metadata API","version":"1.0"},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/allowedMethods":{"get":{"tags":["metaservices"],"summary":"List of allowed REST services and endpoints for a service provider","description":"This function provides a list of REST services and service endpoints\noffered by a service provider that the caller has permission to invoke.\n","operationId":"allowedMethods","parameters":[{"name":"serviceId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of allowed REST services and endpoints for a service provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/restServiceDetailsListType"}}}},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}},"components":{"schemas":{"restServiceDetailsListType":{"type":"object","properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/restServiceDetailsType"}}}},"restServiceDetailsType":{"type":"object","properties":{"objectType":{"type":"string","enum":["MEMBER","APPLICATION","SERVICE"]},"serviceType":{"type":"string"},"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"},"serviceCode":{"type":"string"},"serviceVersion":{"type":"string"},"endpointList":{"type":"object","properties":{"member":{"type":"array","items":{"$ref":"#/components/schemas/endpoint"}}}}}},"endpoint":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}}}} ``` 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. ## 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.
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Service Metadata API","version":"1.0"},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI":{"get":{"tags":["metaservices"],"summary":"Returns OpenAPI service description for a REST service","description":"This metaservice is designed to retrieve service descriptions for\nREST services.\nIt provides the OpenAPI service description for a specific REST service.\nTo use this service, the query parameters should include `serviceCode=xxx`,\nwhere `xxx` corresponds to the service code of the particular REST service\nfor which you desire to obtain the service description.\n","operationId":"getOpenAPI","parameters":[{"name":"serviceCode","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OpenAPI description of the specified REST service","content":{"application/json":{"schema":{"type":"string"}},"text/yaml":{"schema":{"type":"string"}}}},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}}} ``` ## 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}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"SubscriptionItem":{"type":"object","required":["eventType"],"properties":{"id":{"type":"string","format":"uuid"},"subscriberId":{"type":"object","properties":{"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}},"eventType":{"type":"string"},"delivery":{"type":"string","enum":["PUSH","PULL"],"default":"PUSH"},"options":{"type":"object","properties":{"TTL":{"type":"integer","default":3600},"FIFO":{"type":"boolean","default":false}}}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs":{"get":{"tags":["sub"],"summary":"list my subscriptions","operationId":"listSub","description":"Return list of my subscriptions in the room {applicationCode}\n","responses":{"200":{"description":"List of my subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionItem"}}}}},"404":{"description":"Subscription missing"},"500":{"description":"Internal error"}}}}}} ``` ## add subscription > Subscribe caller to {eventType} in the room {applicationCode} ```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"SubscriptionItem":{"type":"object","required":["eventType"],"properties":{"id":{"type":"string","format":"uuid"},"subscriberId":{"type":"object","properties":{"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}},"eventType":{"type":"string"},"delivery":{"type":"string","enum":["PUSH","PULL"],"default":"PUSH"},"options":{"type":"object","properties":{"TTL":{"type":"integer","default":3600},"FIFO":{"type":"boolean","default":false}}}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}":{"post":{"tags":["sub"],"summary":"add subscription","operationId":"addSub","description":"Subscribe caller to {eventType} in the room {applicationCode}","responses":{"200":{"description":"Subscription created"},"400":{"description":"Invalid request"},"409":{"description":"Subscription already exists"},"500":{"description":"Internal error"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionItem"}}},"description":"Subscription item to add"}}}}} ``` ## get subscription details > Return details of subscription to {eventType}\ > in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"SubscriptionItem":{"type":"object","required":["eventType"],"properties":{"id":{"type":"string","format":"uuid"},"subscriberId":{"type":"object","properties":{"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}},"eventType":{"type":"string"},"delivery":{"type":"string","enum":["PUSH","PULL"],"default":"PUSH"},"options":{"type":"object","properties":{"TTL":{"type":"integer","default":3600},"FIFO":{"type":"boolean","default":false}}}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}":{"get":{"tags":["sub"],"summary":"get subscription details","operationId":"getSub","description":"Return details of subscription to {eventType}\nin the room {applicationCode}\n","responses":{"200":{"description":"Subscription details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionItem"}}}},"404":{"description":"Subscription missing"},"500":{"description":"Internal error"}}}}}} ``` ## update subscription details > Update details of subscription to {eventType}\ > in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"SubscriptionItem":{"type":"object","required":["eventType"],"properties":{"id":{"type":"string","format":"uuid"},"subscriberId":{"type":"object","properties":{"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}},"eventType":{"type":"string"},"delivery":{"type":"string","enum":["PUSH","PULL"],"default":"PUSH"},"options":{"type":"object","properties":{"TTL":{"type":"integer","default":3600},"FIFO":{"type":"boolean","default":false}}}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}":{"patch":{"tags":["sub"],"summary":"update subscription details","operationId":"patchSub","description":"Update details of subscription to {eventType}\nin the room {applicationCode}\n","responses":{"201":{"description":"Subscription details"},"400":{"description":"Invalid request"},"404":{"description":"Subscription missing"},"500":{"description":"Internal error"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionItem"}}},"description":"New details of subscription"}}}}} ``` ## cancel subscription > Unsubscribe ```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}":{"delete":{"tags":["sub"],"summary":"cancel subscription","operationId":"deleteSub","description":"Unsubscribe","responses":{"204":{"description":"Subscription deleted"},"404":{"description":"Subscription missing"},"500":{"description":"Internal error"}}}}}} ``` ### 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}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"EventItem":{"required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"publisherId":{"type":"object","properties":{"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}},"eventType":{"type":"string"},"event":{"type":"object"}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}":{"get":{"tags":["sub"],"summary":"get next unacknowledged event","operationId":"pullEvent","description":"Return next unacknowledged event of type defined by\n{eventType} and located in the room {applicationCode}\n","responses":{"200":{"description":"Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventItem"}}}},"404":{"description":"No event available"},"409":{"description":"Invalid request"},"500":{"description":"Internal error"}}}}}} ``` ## confirm event > Acknowledge receiving of event from the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"sub","description":"Operations available to Subscribers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}/{eventId}":{"delete":{"tags":["sub"],"summary":"confirm event","operationId":"confirmEvent","description":"Acknowledge receiving of event from the room {applicationCode}\n","responses":{"204":{"description":"Event acknowledged"},"404":{"description":"no event available"},"409":{"description":"invalid request"}}}}}} ``` ### 8.3.3 Publisher API ## publish event > Publish event in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"pub","description":"Operations available to Publishers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"PublishEvent":{"required":["eventType","event"],"properties":{"eventType":{"type":"string"},"event":{"type":"object"}}},"PublishEventResult":{"required":["id"],"properties":{"id":{"type":"string","format":"uuid"}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}":{"post":{"tags":["pub"],"summary":"publish event","operationId":"publishEvent","description":"Publish event in the room {applicationCode}\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishEvent"}}}},"responses":{"201":{"description":"Event accepted for publishing. Returning event id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishEventResult"}}}},"400":{"description":"Invalid request"},"404":{"description":"Unknown event type"},"500":{"description":"Internal error"}}}}}} ``` ## get published event status > Return event status info.\ > Event is located in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"pub","description":"Operations available to Publishers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"EventItem":{"required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"publisherId":{"type":"object","properties":{"instanceId":{"type":"string"},"memberClass":{"type":"string"},"memberCode":{"type":"string"},"applicationCode":{"type":"string"}}},"eventType":{"type":"string"},"event":{"type":"object"}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}":{"get":{"tags":["pub"],"summary":"get published event status","operationId":"getStatus","description":"Return event status info.\nEvent is located in the room {applicationCode}\n","responses":{"200":{"description":"Event status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventItem"}}}},"404":{"description":"Event missing"},"500":{"description":"Internal error"}}}}}} ``` ## delete event publication > Stop processing of the event.\ > Event is located in the room {applicationId}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"pub","description":"Operations available to Publishers"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}":{"delete":{"tags":["pub"],"summary":"delete event publication","operationId":"deleteEvent","description":"Stop processing of the event.\nEvent is located in the room {applicationId}\n","responses":{"204":{"description":"Event processing stopped"},"404":{"description":"Event missing"},"500":{"description":"Internal error"}}}}}} ``` ### 8.3.4 Event Type API ## create event type > Create new event type in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"admin","description":"Operations available to a room manager"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"EventType":{"required":["eventType","schema"],"properties":{"eventType":{"type":"string"},"schema":{"type":"object"}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType":{"post":{"tags":["admin"],"summary":"create event type","operationId":"createEventType","description":"Create new event type in the room {applicationCode}\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventType"}}}},"responses":{"200":{"description":"Event type created"},"400":{"description":"Invalid request"},"409":{"description":"Event type already exists"},"500":{"description":"Internal error"}}}}}} ``` ## get list of event types > Return list of event types located in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"admin","description":"Operations available to a room manager"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType":{"get":{"tags":["admin"],"summary":"get list of event types","operationId":"getEventTypeList","description":"Return list of event types located in the room {applicationCode}\n","responses":{"200":{"description":"Event type list","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"204":{"description":"Event types does not defined"},"500":{"description":"Internal error"}}}}}} ``` ## get event type details > Return event type description.\ > Event type is located in the room {applicationCode}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"admin","description":"Operations available to a room manager"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}},"schemas":{"EventType":{"required":["eventType","schema"],"properties":{"eventType":{"type":"string"},"schema":{"type":"object"}}}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}":{"get":{"tags":["admin"],"summary":"get event type details","operationId":"getEventType","description":"Return event type description.\nEvent type is located in the room {applicationCode}\n","responses":{"200":{"description":"Event type details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventType"}}}},"204":{"description":"Event type does not defined"},"500":{"description":"Internal error"}}}}}} ``` ## delete event type > Delete event type in the room {applicationId}
```json {"openapi":"3.1.0","info":{"title":"GovStack IM PubSub","version":"2.0.0"},"tags":[{"name":"admin","description":"Operations available to a room manager"}],"security":[{"certs":[]}],"components":{"securitySchemes":{"certs":{"type":"mutualTLS","description":"Certs are exchanged between parties and stored in configuration\nto have fixed one-to-one connection\n"}}},"paths":{"/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}":{"delete":{"tags":["admin"],"summary":"delete event type","operationId":"deleteEventType","description":"Delete event type in the room {applicationId}\n","responses":{"204":{"description":"Event type deleted"},"404":{"description":"Event type missing"},"500":{"description":"Internal error"}}}}}} ``` ## 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 \, \, etc. ## 8.6 Management API ### 8.6.1 Configuration Management ## List IM configuration > Configuration description of IM is returned in form of file
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"conf","description":"Configuration management"}],"security":[{"auth":["read:conf"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"IMconf":{"type":"object","required":["domain","instance"],"properties":{"domain":{"description":"Subdomain for GovStack instance to run in","type":"string"},"instance":{"description":"Name of GovStack instance","type":"string"},"members":{"description":"List of Member organisations","type":"array","items":{"type":"object","required":["name","class","code"],"properties":{"name":{"description":"Organisation (Member) name","type":"string"},"class":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"code":{"description":"Registration number (or identifier) of the organisation in {class} namespace","type":"string"},"applications":{"description":"List of applications of Member organisation","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Name of application"},"connection":{"type":"string","description":"Connection protocol of application","default":"https"},"services":{"description":"List of services","type":"array","items":{"type":"object","required":["id","specUrl","serviceUrl"],"properties":{"id":{"description":"Name of service/API","type":"string"},"specUrl":{"description":"Location of OpenAPI spec file","type":"string","format":"uri"},"serviceUrl":{"description":"Location of service endpoints","type":"string","format":"uri"},"rights":{"description":"List of allowed consumers/clients","type":"array","items":{"type":"object","required":["member","application"],"properties":{"member":{"description":"Name of Member","type":"string"},"application":{"description":"Name of application","type":"string"}}}}}}}}}}}}}}}}},"paths":{"/api/v1/config":{"get":{"tags":["conf"],"summary":"List IM configuration","description":"Configuration description of IM is returned in form of file\n","operationId":"listIMconf","responses":{"200":{"description":"List of IM configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconf"}}}},"500":{"description":"Internal error"}}}}}} ``` ## Initialize IM instance > Create new instance of IM
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"conf","description":"Configuration management"}],"security":[{"auth":["write:conf"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"IMconf":{"type":"object","required":["domain","instance"],"properties":{"domain":{"description":"Subdomain for GovStack instance to run in","type":"string"},"instance":{"description":"Name of GovStack instance","type":"string"},"members":{"description":"List of Member organisations","type":"array","items":{"type":"object","required":["name","class","code"],"properties":{"name":{"description":"Organisation (Member) name","type":"string"},"class":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"code":{"description":"Registration number (or identifier) of the organisation in {class} namespace","type":"string"},"applications":{"description":"List of applications of Member organisation","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Name of application"},"connection":{"type":"string","description":"Connection protocol of application","default":"https"},"services":{"description":"List of services","type":"array","items":{"type":"object","required":["id","specUrl","serviceUrl"],"properties":{"id":{"description":"Name of service/API","type":"string"},"specUrl":{"description":"Location of OpenAPI spec file","type":"string","format":"uri"},"serviceUrl":{"description":"Location of service endpoints","type":"string","format":"uri"},"rights":{"description":"List of allowed consumers/clients","type":"array","items":{"type":"object","required":["member","application"],"properties":{"member":{"description":"Name of Member","type":"string"},"application":{"description":"Name of application","type":"string"}}}}}}}}}}}}}}},"IMconfResponse":{"type":"string"}}},"paths":{"/api/v1/config":{"post":{"tags":["conf"],"summary":"Initialize IM instance","description":"Create new instance of IM\n","operationId":"createIMconf","parameters":[{"name":"init","description":"Creates Central Servers if init=true","schema":{"type":"boolean","default":false},"in":"query"}],"requestBody":{"description":"configuration description file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconf"}},"text/yaml":{"schema":{"$ref":"#/components/schemas/IMconf"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconfResponse"}}},"description":"IM starts configuration creation"},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}}} ``` ## Update IM configuration > Update IM configuration. Not described parts are not changed
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"conf","description":"Configuration management"}],"security":[{"auth":["write:conf"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"IMconf":{"type":"object","required":["domain","instance"],"properties":{"domain":{"description":"Subdomain for GovStack instance to run in","type":"string"},"instance":{"description":"Name of GovStack instance","type":"string"},"members":{"description":"List of Member organisations","type":"array","items":{"type":"object","required":["name","class","code"],"properties":{"name":{"description":"Organisation (Member) name","type":"string"},"class":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"code":{"description":"Registration number (or identifier) of the organisation in {class} namespace","type":"string"},"applications":{"description":"List of applications of Member organisation","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Name of application"},"connection":{"type":"string","description":"Connection protocol of application","default":"https"},"services":{"description":"List of services","type":"array","items":{"type":"object","required":["id","specUrl","serviceUrl"],"properties":{"id":{"description":"Name of service/API","type":"string"},"specUrl":{"description":"Location of OpenAPI spec file","type":"string","format":"uri"},"serviceUrl":{"description":"Location of service endpoints","type":"string","format":"uri"},"rights":{"description":"List of allowed consumers/clients","type":"array","items":{"type":"object","required":["member","application"],"properties":{"member":{"description":"Name of Member","type":"string"},"application":{"description":"Name of application","type":"string"}}}}}}}}}}}}}}},"IMconfResponse":{"type":"string"}}},"paths":{"/api/v1/config":{"patch":{"tags":["conf"],"summary":"Update IM configuration","description":"Update IM configuration. Not described parts are not changed\n","operationId":"updateIMconf","requestBody":{"description":"configuration description file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconf"}},"text/yaml":{"schema":{"$ref":"#/components/schemas/IMconf"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconfResponse"}}},"description":"IM starts configuration update"},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}}} ``` ## Replace IM configuration > Replace IM configuration. Not described parts are deleted
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"conf","description":"Configuration management"}],"security":[{"auth":["create:conf"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"IMconf":{"type":"object","required":["domain","instance"],"properties":{"domain":{"description":"Subdomain for GovStack instance to run in","type":"string"},"instance":{"description":"Name of GovStack instance","type":"string"},"members":{"description":"List of Member organisations","type":"array","items":{"type":"object","required":["name","class","code"],"properties":{"name":{"description":"Organisation (Member) name","type":"string"},"class":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"code":{"description":"Registration number (or identifier) of the organisation in {class} namespace","type":"string"},"applications":{"description":"List of applications of Member organisation","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Name of application"},"connection":{"type":"string","description":"Connection protocol of application","default":"https"},"services":{"description":"List of services","type":"array","items":{"type":"object","required":["id","specUrl","serviceUrl"],"properties":{"id":{"description":"Name of service/API","type":"string"},"specUrl":{"description":"Location of OpenAPI spec file","type":"string","format":"uri"},"serviceUrl":{"description":"Location of service endpoints","type":"string","format":"uri"},"rights":{"description":"List of allowed consumers/clients","type":"array","items":{"type":"object","required":["member","application"],"properties":{"member":{"description":"Name of Member","type":"string"},"application":{"description":"Name of application","type":"string"}}}}}}}}}}}}}}},"IMconfResponse":{"type":"string"}}},"paths":{"/api/v1/config":{"put":{"tags":["conf"],"summary":"Replace IM configuration","description":"Replace IM configuration. Not described parts are deleted\n","operationId":"replaceIMconf","requestBody":{"description":"configuration description file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconf"}},"text/yaml":{"schema":{"$ref":"#/components/schemas/IMconf"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IMconfResponse"}}},"description":"IM starts configuration creation"},"400":{"description":"Error in request"},"500":{"description":"Internal error"}}}}}} ``` ## Check status > Is IM configured. up and running?
```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"conf","description":"Configuration management"}],"security":[{"auth":["read:conf"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}}},"paths":{"/api/v1/status":{"get":{"tags":["conf"],"summary":"Check status","description":"Is IM configured. up and running?\n","operationId":"checkIMconf","responses":{"200":{"description":"IM is OK"},"500":{"description":"Internal error"}}}}}} ``` #### 8.6.2 Management of Access Rights ## Retrieve configured access permissions (allow list) > \

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. \

```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"rights","description":"Access rights management"}],"security":[{"auth":["read:rights"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"PaginatedResult":{"type":"object","properties":{"nextPageToken":{"type":"string"}}},"ServiceAccessRights":{"type":"array","items":{"type":"object","required":["memberClass","memberCode","applicationId","serviceId","rights"],"properties":{"memberClass":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"memberCode":{"description":"Registration number (or identifier) of the organisation in {memberClass} namespace","type":"string"},"applicationId":{"type":"string","description":"Name of application"},"serviceId":{"description":"Name of service/API","type":"string"},"rights":{"description":"Applications that are allowed or denied access","type":"array","items":{"$ref":"#/components/schemas/AllowedApplication"}}}}},"AllowedApplication":{"description":"An identified member application that has the permission to access a service.","type":"object","required":["member","application"],"properties":{"memberClass":{"description":"Member or member group identifier to whom access is granted","type":"string"},"memberCode":{"description":"Member or member group identifier to whom access is granted","type":"string"},"applicationId":{"description":"Application of the member that to whom access is granted","type":"string"}}}}},"paths":{"/api/v1/rights/allow":{"get":{"tags":["rights"],"summary":"Retrieve configured access permissions (allow list)","description":"

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.

","operationId":"getAllowed","parameters":[{"in":"query","name":"memberClass","description":"Filter by member class","schema":{"type":"string"},"required":false},{"in":"query","name":"memberCode","schema":{"type":"string"},"description":"Filter by member code","required":false},{"in":"query","name":"applicationId","schema":{"type":"string"},"description":"Filter by application ID","required":false},{"in":"query","name":"serviceId","schema":{"type":"string"},"description":"Filter by service ID","required":false},{"in":"query","name":"pageSize","description":"Number of access rights returned on one page","schema":{"type":"number","default":100},"required":false},{"in":"query","name":"nextPageToken","description":"Handle for the next page, if the result spans multiple pages. If not specified, there are no more results.","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResult"},{"type":"object","properties":{"allowList":{"$ref":"#/components/schemas/ServiceAccessRights"}}}]}}}},"401":{"description":"Caller does not have permissions to view access rights"}}}}}} ``` ## PATCH /api/v1/rights/allow > Allow access to services ```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"rights","description":"Access rights management"}],"security":[{"auth":["write:rights"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"ServiceAccessRights":{"type":"array","items":{"type":"object","required":["memberClass","memberCode","applicationId","serviceId","rights"],"properties":{"memberClass":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"memberCode":{"description":"Registration number (or identifier) of the organisation in {memberClass} namespace","type":"string"},"applicationId":{"type":"string","description":"Name of application"},"serviceId":{"description":"Name of service/API","type":"string"},"rights":{"description":"Applications that are allowed or denied access","type":"array","items":{"$ref":"#/components/schemas/AllowedApplication"}}}}},"AllowedApplication":{"description":"An identified member application that has the permission to access a service.","type":"object","required":["member","application"],"properties":{"memberClass":{"description":"Member or member group identifier to whom access is granted","type":"string"},"memberCode":{"description":"Member or member group identifier to whom access is granted","type":"string"},"applicationId":{"description":"Application of the member that to whom access is granted","type":"string"}}}}},"paths":{"/api/v1/rights/allow":{"patch":{"tags":["rights"],"summary":"Allow access to services","operationId":"setAllowed","requestBody":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccessRights"}}},"required":false},"responses":{"200":{"description":"OK"},"401":{"description":"Caller does not have the necessary permissions to update access rights"}}}}}} ``` ## PATCH /api/v1/rights/deny > Deny access to services ```json {"openapi":"3.0.0","info":{"title":"GovStack IM Configuration Management API","version":"1.0.1"},"tags":[{"name":"rights","description":"Access rights management"}],"security":[{"auth":["write:rights"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token","scopes":{"read:conf":"Grants read access to IM configuration","create:conf":"Grants permission to create IM configuration","write:conf":"Grants write access to IM configuration","read:rights":"Grants permission to see what services are allowed","write:rights":"Grants permission to allow/deny IM services"}}}}},"schemas":{"ServiceAccessRights":{"type":"array","items":{"type":"object","required":["memberClass","memberCode","applicationId","serviceId","rights"],"properties":{"memberClass":{"description":"Kind of organisation. Namespace for organisation {code}","type":"string"},"memberCode":{"description":"Registration number (or identifier) of the organisation in {memberClass} namespace","type":"string"},"applicationId":{"type":"string","description":"Name of application"},"serviceId":{"description":"Name of service/API","type":"string"},"rights":{"description":"Applications that are allowed or denied access","type":"array","items":{"$ref":"#/components/schemas/AllowedApplication"}}}}},"AllowedApplication":{"description":"An identified member application that has the permission to access a service.","type":"object","required":["member","application"],"properties":{"memberClass":{"description":"Member or member group identifier to whom access is granted","type":"string"},"memberCode":{"description":"Member or member group identifier to whom access is granted","type":"string"},"applicationId":{"description":"Application of the member that to whom access is granted","type":"string"}}}}},"paths":{"/api/v1/rights/deny":{"patch":{"tags":["rights"],"summary":"Deny access to services","operationId":"setDenied","requestBody":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccessRights"}}},"required":false},"responses":{"200":{"description":"OK"},"401":{"description":"Caller does not have the necessary permissions to update access rights"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://mediator.govstack.global/8-service-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.