LogoLogo
Give FeedbackGovStack Home
Development
Development
  • Information Mediator
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF

8 Service APIs

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

Last updated 1 year ago

Was this helpful?

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

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

and changes to the API definitions can be made by submitting a pull request on this repository. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

The services can be accessed via the following Service APIs:

8.1 Service Access

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

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

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

8.2 Directory Services

8.2.1 Member Discovery

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

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

8.2.2 Service Discovery

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

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

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

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

8.3 Pub/Sub Service

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

8.3.1 Subscriber API

8.3.2 PULL delivery mode API

8.3.3 Publisher API

8.3.4 Event Type API

8.4 Logging Services

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

8.5 Monitoring Services

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

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

8.6 Management API

8.6.1 Configuration Management

8.6.2 Management of Access Rights

GovStack non-functional requirements document
this GitHub repository
API metadata

List clients defined in the instance

get

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.

Query parameters
instanceIdstringOptional
Responses
200
List of Clients of GovStack
application/json
400
Error in request
500
Internal error
get
GET /listClients HTTP/1.1
Host: 
Accept: */*
{
  "member": [
    {
      "name": "text",
      "id": {
        "objectType": "MEMBER",
        "instanceId": "text",
        "memberClass": "text",
        "memberCode": "text",
        "applicationCode": "text"
      }
    }
  ]
}

List REST services and endpoints for a service provider

get

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

Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
Query parameters
serviceIdstringOptional
Header parameters
X-GovStack-ClientstringRequired
Responses
200
List of REST services and endpoints for a service provider
application/json
400
Error in request
500
Internal error
get
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/listMethods HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
{
  "member": [
    {
      "objectType": "MEMBER",
      "serviceType": "text",
      "instanceId": "text",
      "memberClass": "text",
      "memberCode": "text",
      "applicationCode": "text",
      "serviceCode": "text",
      "serviceVersion": "text",
      "endpointList": {
        "member": [
          {
            "method": "text",
            "path": "text"
          }
        ]
      }
    }
  ]
}

List of allowed REST services and endpoints for a service provider

get

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

Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
Query parameters
serviceIdstringOptional
Header parameters
X-GovStack-ClientstringRequired
Responses
200
List of allowed REST services and endpoints for a service provider
application/json
400
Error in request
500
Internal error
get
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/allowedMethods HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
{
  "member": [
    {
      "objectType": "MEMBER",
      "serviceType": "text",
      "instanceId": "text",
      "memberClass": "text",
      "memberCode": "text",
      "applicationCode": "text",
      "serviceCode": "text",
      "serviceVersion": "text",
      "endpointList": {
        "member": [
          {
            "method": "text",
            "path": "text"
          }
        ]
      }
    }
  ]
}

Returns OpenAPI service description for a REST service

get

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.

Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
Query parameters
serviceCodestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
200
OpenAPI description of the specified REST service
Responsestring
400
Error in request
500
Internal error
get
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI?serviceCode=text HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
text
  • 8.1 Service Access
  • 8.2 Directory Services
  • GETList clients defined in the instance
  • GETList REST services and endpoints for a service provider
  • GETList of allowed REST services and endpoints for a service provider
  • GETReturns OpenAPI service description for a REST service
  • 8.3 Pub/Sub Service
  • GETlist my subscriptions
  • POSTadd subscription
  • GETget subscription details
  • PATCHupdate subscription details
  • DELETEcancel subscription
  • GETget next unacknowledged event
  • DELETEconfirm event
  • POSTpublish event
  • GETget published event status
  • DELETEdelete event publication
  • POSTcreate event type
  • GETget list of event types
  • GETget event type details
  • DELETEdelete event type
  • 8.4 Logging Services
  • 8.5 Monitoring Services
  • 8.6 Management API
  • GETList IM configuration
  • POSTInitialize IM instance
  • PATCHUpdate IM configuration
  • PUTReplace IM configuration
  • GETCheck status
  • GETRetrieve configured access permissions (allow list)
  • PATCHAllow access to services
  • PATCHDeny access to services

list my subscriptions

get

Return list of my subscriptions in the room {applicationCode}

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
200
List of my subscriptions
application/json
404
Subscription missing
500
Internal error
get

get subscription details

get

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
200
Subscription details
application/json
404
Subscription missing
500
Internal error
get

cancel subscription

delete

Unsubscribe

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
204
Subscription deleted
404
Subscription missing
500
Internal error
delete

No content

get next unacknowledged event

get

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
eventTypestringRequired

event type

Header parameters
X-GovStack-ClientstringRequired
Responses
200
Event
application/json
404
No event available
409
Invalid request
500
Internal error
get

confirm event

delete

Acknowledge receiving of event from the room {applicationCode}

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
eventIdstringRequired

event id

Header parameters
X-GovStack-ClientstringRequired
Responses
204
Event acknowledged
404
no event available
409
invalid request
delete

No content

get published event status

get

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
eventIdstringRequired

event id of event

Header parameters
X-GovStack-ClientstringRequired
Responses
200
Event status
application/json
404
Event missing
500
Internal error
get

delete event publication

delete

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
eventIdstringRequired

event id of event

Header parameters
X-GovStack-ClientstringRequired
Responses
204
Event processing stopped
404
Event missing
500
Internal error
delete

No content

get list of event types

get

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
200
Event type list
application/json
Responsestring[]
204
Event types does not defined
500
Internal error
get

get event type details

get

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
200
Event type details
application/json
204
Event type does not defined
500
Internal error
get

delete event type

delete

Delete event type in the room {applicationId}

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Responses
204
Event type deleted
404
Event type missing
500
Internal error
delete

No content

List IM configuration

get

Configuration description of IM is returned in form of file

Authorizations
Responses
200
List of IM configuration
application/json
500
Internal error
get

Check status

get

Is IM configured. up and running?

Authorizations
Responses
200
IM is OK
500
Internal error
get

No content

Retrieve configured access permissions (allow list)

get
Authorizations
Query parameters
memberClassstringOptional

Filter by member class

memberCodestringOptional

Filter by member code

applicationIdstringOptional

Filter by application ID

serviceIdstringOptional

Filter by service ID

pageSizenumberOptional

Number of access rights returned on one page

Default: 100
nextPageTokenstringOptional

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

Responses
200
OK
application/json
Responseall of
401
Caller does not have permissions to view access rights
get
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscriberId": {
      "instanceId": "neverland",
      "memberClass": "GOV",
      "memberCode": "capitalCity",
      "applicationCode": "police"
    },
    "eventType": "newBirth",
    "delivery": "PUSH",
    "options": {
      "TTL": 1,
      "FIFO": true
    }
  }
]

add subscription

post

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Body
idstring · uuidOptional
eventTypestringRequiredExample: newBirth
deliverystring · enumOptionalDefault: PUSHPossible values:
Responses
200
Subscription created
400
Invalid request
409
Subscription already exists
500
Internal error
post
POST /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 234

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

No content

GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "subscriberId": {
    "instanceId": "neverland",
    "memberClass": "GOV",
    "memberCode": "capitalCity",
    "applicationCode": "police"
  },
  "eventType": "newBirth",
  "delivery": "PUSH",
  "options": {
    "TTL": 1,
    "FIFO": true
  }
}

update subscription details

patch

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

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Body
idstring · uuidOptional
eventTypestringRequiredExample: newBirth
deliverystring · enumOptionalDefault: PUSHPossible values:
Responses
201
Subscription details
400
Invalid request
404
Subscription missing
500
Internal error
patch
PATCH /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 234

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

No content

DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/subs/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sequence": 42,
  "publisherId": {
    "instanceId": "neverland",
    "memberClass": "GOV",
    "memberCode": "capital-city",
    "applicationCode": "police"
  },
  "eventType": "newBirth",
  "event": {
    "dateTime": "2023-05-01T11:25:00+02:00",
    "gender": "M",
    "mother": "Jane Doe",
    "place": "City Hospital",
    "details": {
      "weight": 3200,
      "length": 49,
      "eyesColor": "brown"
    }
  }
}
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pull/v1/{eventType}/{eventId} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*

publish event

post

Publish event in the room {applicationCode}

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
eventTypestringRequired
Header parameters
X-GovStack-ClientstringRequired
Body
eventTypestringRequiredExample: newBirth
eventobjectRequiredExample: {"dateTime":"2023-05-01T11:25:00+02:00","gender":"M","mother":"Jane Doe","place":"City Hospital","details":{"weight":3200,"length":49,"eyesColor":"brown"}}
Responses
201
Event accepted for publishing. Returning event id
application/json
400
Invalid request
404
Unknown event type
500
Internal error
post
POST /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "eventType": "newBirth",
  "event": {
    "dateTime": "2023-05-01T11:25:00+02:00",
    "gender": "M",
    "mother": "Jane Doe",
    "place": "City Hospital",
    "details": {
      "weight": 3200,
      "length": 49,
      "eyesColor": "brown"
    }
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sequence": 42,
  "publisherId": {
    "instanceId": "neverland",
    "memberClass": "GOV",
    "memberCode": "capital-city",
    "applicationCode": "police"
  },
  "eventType": "newBirth",
  "event": {
    "dateTime": "2023-05-01T11:25:00+02:00",
    "gender": "M",
    "mother": "Jane Doe",
    "place": "City Hospital",
    "details": {
      "weight": 3200,
      "length": 49,
      "eyesColor": "brown"
    }
  }
}
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/pub/v1/{eventType}/{eventId} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*

create event type

post

Create new event type in the room {applicationCode}

Authorizations
Path parameters
instanceIdstringRequired
memberClassstringRequired
memberCodestringRequired
applicationCodestringRequired
Header parameters
X-GovStack-ClientstringRequired
Body
eventTypestringRequiredExample: newBirth
schemaobjectRequiredExample: { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "dateTime": { "type": "string", "format": "date-time" }, "gender": { "type": "string", "enum": ["M", "F"] }, "mother": { "type": "string" }, "place": { "type": "string" }, "id": { "type": "integer" }, "details": { "type": "object", "properties": { "weight": { "type": "number" }, "length": { "type": "number" }, "eyesColor": { "type": "string" } }, "required": ["weight", "length", "eyesColor"] } }, "required": ["dateTime", "gender", "mother", "place"] }
Responses
200
Event type created
400
Invalid request
409
Event type already exists
500
Internal error
post
POST /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType HTTP/1.1
Host: 
X-GovStack-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 864

{
  "eventType": "newBirth",
  "schema": "{ \"$schema\": \"http://json-schema.org/draft-07/schema#\", \"type\": \"object\", \"properties\": {\n  \"dateTime\": {\n     \"type\": \"string\",\n     \"format\": \"date-time\"\n   },\n   \"gender\": {\n     \"type\": \"string\",\n     \"enum\": [\"M\", \"F\"]\n   },\n   \"mother\": {\n     \"type\": \"string\"\n   },\n   \"place\": {\n     \"type\": \"string\"\n   },\n   \"id\": {\n     \"type\": \"integer\"\n   },\n   \"details\": {\n     \"type\": \"object\",\n     \"properties\": {\n       \"weight\": {\n         \"type\": \"number\"\n       },\n       \"length\": {\n         \"type\": \"number\"\n       },\n       \"eyesColor\": {\n         \"type\": \"string\"\n       }\n    },\n    \"required\": [\"weight\", \"length\", \"eyesColor\"]\n  }\n}, \"required\": [\"dateTime\", \"gender\", \"mother\", \"place\"] }"
}

No content

GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
[
  "newBirth"
]
GET /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
{
  "eventType": "newBirth",
  "schema": "{ \"$schema\": \"http://json-schema.org/draft-07/schema#\", \"type\": \"object\", \"properties\": {\n  \"dateTime\": {\n     \"type\": \"string\",\n     \"format\": \"date-time\"\n   },\n   \"gender\": {\n     \"type\": \"string\",\n     \"enum\": [\"M\", \"F\"]\n   },\n   \"mother\": {\n     \"type\": \"string\"\n   },\n   \"place\": {\n     \"type\": \"string\"\n   },\n   \"id\": {\n     \"type\": \"integer\"\n   },\n   \"details\": {\n     \"type\": \"object\",\n     \"properties\": {\n       \"weight\": {\n         \"type\": \"number\"\n       },\n       \"length\": {\n         \"type\": \"number\"\n       },\n       \"eyesColor\": {\n         \"type\": \"string\"\n       }\n    },\n    \"required\": [\"weight\", \"length\", \"eyesColor\"]\n  }\n}, \"required\": [\"dateTime\", \"gender\", \"mother\", \"place\"] }"
}
DELETE /r1/{instanceId}/{memberClass}/{memberCode}/{applicationCode}/api/v1/eventType/{eventType} HTTP/1.1
Host: 
X-GovStack-Client: text
Accept: */*
GET /api/v1/config HTTP/1.1
Host: 
Accept: */*
{
  "domain": "sample.sandbox.govstack.global",
  "instance": "nowhereland",
  "members": [
    {
      "name": "Ministry of Interior",
      "class": "GOV",
      "code": "7001",
      "applications": [
        {
          "id": "CitizensRegistry",
          "connection": "http",
          "services": [
            {
              "id": "registration",
              "specUrl": "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json",
              "serviceUrl": "http://hostname.internal/api/v1/registration",
              "rights": [
                {
                  "member": "LocalMunicipality",
                  "application": "RegistrationPortal"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Initialize IM instance

post

Create new instance of IM

Authorizations
Query parameters
initbooleanOptional

Creates Central Servers if init=true

Default: false
Body
domainstringRequired

Subdomain for GovStack instance to run in

Example: sample.sandbox.govstack.global
instancestringRequired

Name of GovStack instance

Example: nowhereland
Responses
201
IM starts configuration creation
application/json
Responsestring
400
Error in request
500
Internal error
post
POST /api/v1/config HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 475

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

Update IM configuration

patch

Update IM configuration. Not described parts are not changed

Authorizations
Body
domainstringRequired

Subdomain for GovStack instance to run in

Example: sample.sandbox.govstack.global
instancestringRequired

Name of GovStack instance

Example: nowhereland
Responses
201
IM starts configuration update
application/json
Responsestring
400
Error in request
500
Internal error
patch
PATCH /api/v1/config HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 475

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

Replace IM configuration

put

Replace IM configuration. Not described parts are deleted

Authorizations
Body
domainstringRequired

Subdomain for GovStack instance to run in

Example: sample.sandbox.govstack.global
instancestringRequired

Name of GovStack instance

Example: nowhereland
Responses
201
IM starts configuration creation
application/json
Responsestring
400
Error in request
500
Internal error
put
PUT /api/v1/config HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 475

{
  "domain": "sample.sandbox.govstack.global",
  "instance": "nowhereland",
  "members": [
    {
      "name": "Ministry of Interior",
      "class": "GOV",
      "code": "7001",
      "applications": [
        {
          "id": "CitizensRegistry",
          "connection": "http",
          "services": [
            {
              "id": "registration",
              "specUrl": "https://raw.githubusercontent.com/GovStackWorkingGroup/bb-example/api/registration.json",
              "serviceUrl": "http://hostname.internal/api/v1/registration",
              "rights": [
                {
                  "member": "LocalMunicipality",
                  "application": "RegistrationPortal"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
text
GET /api/v1/status HTTP/1.1
Host: 
Accept: */*
GET /api/v1/rights/allow HTTP/1.1
Host: 
Accept: */*
{
  "nextPageToken": "text",
  "allowList": [
    {
      "memberClass": "GOV",
      "memberCode": "7001",
      "applicationId": "CitizensRegistry",
      "serviceId": "registration",
      "rights": [
        {
          "memberClass": "text",
          "memberCode": "text",
          "applicationId": "text"
        }
      ]
    }
  ]
}

Allow access to services

patch
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
Responses
200
OK
401
Caller does not have the necessary permissions to update access rights
patch
PATCH /api/v1/rights/allow HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 182

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

No content

Deny access to services

patch
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
Responses
200
OK
401
Caller does not have the necessary permissions to update access rights
patch
PATCH /api/v1/rights/deny HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 182

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

No content