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.

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/listClients'

200

400

500

200

{
  "member": [
    {
      "name": "text",
      "id": {
        "instanceId": "text",
        "memberClass": "text",
        "memberCode": "text",
        "applicationCode": "text",
        "objectType": "MEMBER"
      }
    }
  ]
}

List of Clients of GovStack

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.

get

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

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

Query parameters

serviceIdstring

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/listMethods' \
  --header 'X-GovStack-Client: text'

200

400

500

200

{
  "member": [
    {
      "serviceType": "text",
      "instanceId": "text",
      "memberClass": "text",
      "memberCode": "text",
      "applicationCode": "text",
      "serviceCode": "text",
      "serviceVersion": "text",
      "objectType": "MEMBER",
      "endpointList": {
        "member": [
          {
            "method": "text",
            "path": "text"
          }
        ]
      }
    }
  ]
}

List of REST services and endpoints for a service provider

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

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

Query parameters

serviceIdstring

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/allowedMethods' \
  --header 'X-GovStack-Client: text'

200

400

500

200

{
  "member": [
    {
      "serviceType": "text",
      "instanceId": "text",
      "memberClass": "text",
      "memberCode": "text",
      "applicationCode": "text",
      "serviceCode": "text",
      "serviceVersion": "text",
      "objectType": "MEMBER",
      "endpointList": {
        "member": [
          {
            "method": "text",
            "path": "text"
          }
        ]
      }
    }
  ]
}

List of allowed REST services and endpoints for a service provider

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.

get

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

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

Query parameters

serviceCodestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

application/jsontext/yaml

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI?serviceCode=text' \
  --header 'X-GovStack-Client: text'

200

400

500

200

application/json

text/yaml

application/json

text

OpenAPI description of the specified REST service

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs' \
  --header 'X-GovStack-Client: text'

200

404

500

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "eventType": "newBirth",
    "delivery": "PUSH",
    "options": {
      "TTL": 3600,
      "FIFO": false
    },
    "subscriberId": {
      "instanceId": "neverland",
      "memberClass": "GOV",
      "memberCode": "capitalCity",
      "applicationCode": "police"
    }
  }
]

List of my subscriptions

add subscription

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

post

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Body

idstring · uuid

eventTypestringrequired

deliverystring · enum · default: PUSH

Options: PUSH, PULL

optionsobject

subscriberIdobject

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}' \
  --header 'X-GovStack-Client: text' \
  --header 'Content-Type: application/json' \
  --data '{"eventType":"newBirth","delivery":"PUSH","options":{"TTL":3600,"FIFO":false},"subscriberId":{"instanceId":"neverland","memberClass":"GOV","memberCode":"capitalCity","applicationCode":"police"}}'

200

400

409

500

200

No body

Subscription created

get subscription details

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

get

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}' \
  --header 'X-GovStack-Client: text'

200

404

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "eventType": "newBirth",
  "delivery": "PUSH",
  "options": {
    "TTL": 3600,
    "FIFO": false
  },
  "subscriberId": {
    "instanceId": "neverland",
    "memberClass": "GOV",
    "memberCode": "capitalCity",
    "applicationCode": "police"
  }
}

Subscription details

update subscription details

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

patch

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Body

idstring · uuid

eventTypestringrequired

deliverystring · enum · default: PUSH

Options: PUSH, PULL

optionsobject

subscriberIdobject

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}' \
  --header 'X-GovStack-Client: text' \
  --header 'Content-Type: application/json' \
  --data '{"eventType":"newBirth","delivery":"PUSH","options":{"TTL":3600,"FIFO":false},"subscriberId":{"instanceId":"neverland","memberClass":"GOV","memberCode":"capitalCity","applicationCode":"police"}}'

201

400

404

500

201

No body

Subscription details

cancel subscription

Unsubscribe

delete

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType}' \
  --header 'X-GovStack-Client: text'

204

404

500

204

No body

Subscription deleted

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}

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

eventTypestringrequired

event type

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}' \
  --header 'X-GovStack-Client: text'

200

404

409

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sequence": 42,
  "eventType": "newBirth",
  "publisherId": {
    "instanceId": "neverland",
    "memberClass": "GOV",
    "memberCode": "capital-city",
    "applicationCode": "police"
  },
  "event": {
    "dateTime": "2023-05-01T11:25:00+02:00",
    "gender": "M",
    "mother": "Jane Doe",
    "place": "City Hospital",
    "details": {
      "weight": 3200,
      "length": 49,
      "eyesColor": "brown"
    }
  }
}

Event

confirm event

Acknowledge receiving of event from the room {applicationCode}

delete

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

eventIdstringrequired

event id

Header parameters

X-GovStack-Clientstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}/{eventId}' \
  --header 'X-GovStack-Client: text'

204

404

409

204

No body

Event acknowledged

8.3.3 Publisher API

publish event

Publish event in the room {applicationCode}

post

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Body

eventTypestringrequired

eventobjectrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}' \
  --header 'X-GovStack-Client: text' \
  --header 'Content-Type: application/json'

201

400

404

500

201

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

Event accepted for publishing. Returning event id

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}

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

eventIdstringrequired

event id of event

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}' \
  --header 'X-GovStack-Client: text'

200

404

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sequence": 42,
  "eventType": "newBirth",
  "publisherId": {
    "instanceId": "neverland",
    "memberClass": "GOV",
    "memberCode": "capital-city",
    "applicationCode": "police"
  },
  "event": {
    "dateTime": "2023-05-01T11:25:00+02:00",
    "gender": "M",
    "mother": "Jane Doe",
    "place": "City Hospital",
    "details": {
      "weight": 3200,
      "length": 49,
      "eyesColor": "brown"
    }
  }
}

Event status

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}

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

eventIdstringrequired

event id of event

Header parameters

X-GovStack-Clientstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId}' \
  --header 'X-GovStack-Client: text'

204

404

500

204

No body

Event processing stopped

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

Header parameters

X-GovStack-Clientstringrequired

Body

eventTypestringrequired

schemaobjectrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType' \
  --header 'X-GovStack-Client: text' \
  --header 'Content-Type: application/json'

200

400

409

500

200

No body

Event type created

get list of event types

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

get

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType' \
  --header 'X-GovStack-Client: text'

200

204

500

200

[
  "newBirth"
]

Event type list

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}

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}' \
  --header 'X-GovStack-Client: text'

200

204

500

200

{
  "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\"] }"
}

Event type details

delete event type

Delete event type in the room {applicationId}

delete

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

Authorizations

Path parameters

instanceIdstringrequired

memberClassstringrequired

memberCodestringrequired

applicationCodestringrequired

eventTypestringrequired

Header parameters

X-GovStack-Clientstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType}' \
  --header 'X-GovStack-Client: text'

204

404

500

204

No body

Event type deleted

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

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/config'

200

500

200

{
  "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"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

List of IM configuration

Initialize IM instance

Create new instance of IM

post

/api/v1/config

Authorizations

Query parameters

initboolean

Creates Central Servers if init=true

Body

application/jsontext/yaml

domainstringrequired

Subdomain for GovStack instance to run in

Example: sample.sandbox.govstack.global

instancestringrequired

Name of GovStack instance

Example: nowhereland

membersobject[]

List of Member organisations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v1/config' \
  --header 'Content-Type: application/json' \
  --data '{"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"}]}]}]}]}'

201

400

500

201

text

IM starts configuration creation

Update IM configuration

Update IM configuration. Not described parts are not changed

patch

/api/v1/config

Authorizations

Body

application/jsontext/yaml

domainstringrequired

Subdomain for GovStack instance to run in

Example: sample.sandbox.govstack.global

instancestringrequired

Name of GovStack instance

Example: nowhereland

membersobject[]

List of Member organisations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '/api/v1/config' \
  --header 'Content-Type: application/json' \
  --data '{"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"}]}]}]}]}'

201

400

500

201

text

IM starts configuration update

Replace IM configuration

Replace IM configuration. Not described parts are deleted

put

/api/v1/config

Authorizations

Body

application/jsontext/yaml

domainstringrequired

Subdomain for GovStack instance to run in

Example: sample.sandbox.govstack.global

instancestringrequired

Name of GovStack instance

Example: nowhereland

membersobject[]

List of Member organisations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/api/v1/config' \
  --header 'Content-Type: application/json' \
  --data '{"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"}]}]}]}]}'

201

400

500

201

text

IM starts configuration creation

Check status

Is IM configured. up and running?

get

/api/v1/status

Authorizations

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/status'

200

500

200

No body

IM is OK

8.6.2 Management of Access Rights

Retrieve configured access permissions (allow list)

<p>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.</p> <p>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:<br/><br/> Page 1: Service A, with all of its 8 allowed applications, Service B with 2 allowed applications.<br/> Page 2: Service B, with 6 allowed applications left over, Service C with 4 applications.<br/> Page 3: Service C, with 4 applications.<br/> <p> 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. </p>

get

/api/v1/rights/allow

Authorizations

Query parameters

memberClassstring

Filter by member class

memberCodestring

Filter by member code

applicationIdstring

Filter by application ID

serviceIdstring

Filter by service ID

pageSizenumber · default: 100

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/rights/allow'

200

401

200

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

OK

Allow access to services

patch

/api/v1/rights/allow

Authorizations

Body

memberClassstringrequired

Kind of organisation. Namespace for organisation {code}

Example: GOV

memberCodestringrequired

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

Example: 7001

applicationIdstringrequired

Name of application

Example: CitizensRegistry

serviceIdstringrequired

Name of service/API

Example: registration

rightsobject[]required

Applications that are allowed or denied access

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '/api/v1/rights/allow' \
  --header 'Content-Type: application/json' \
  --data '[{"memberClass":"GOV","memberCode":"7001","applicationId":"CitizensRegistry","serviceId":"registration","rights":[{"memberClass":"text","memberCode":"text","applicationId":"text"}]}]'

200

401

200

No body

OK

Deny access to services

patch

/api/v1/rights/deny

Authorizations

Body

memberClassstringrequired

Kind of organisation. Namespace for organisation {code}

Example: GOV

memberCodestringrequired

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

Example: 7001

applicationIdstringrequired

Name of application

Example: CitizensRegistry

serviceIdstringrequired

Name of service/API

Example: registration

rightsobject[]required

Applications that are allowed or denied access

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '/api/v1/rights/deny' \
  --header 'Content-Type: application/json' \
  --data '[{"memberClass":"GOV","memberCode":"7001","applicationId":"CitizensRegistry","serviceId":"registration","rights":[{"memberClass":"text","memberCode":"text","applicationId":"text"}]}]'

200

401

200

No body

OK