Skip to content

Latest commit

 

History

History
5752 lines (4826 loc) · 179 KB

README.md

File metadata and controls

5752 lines (4826 loc) · 179 KB
Raw

Arrowhead Framework 4.1.3

Arrowhead (and its continuation, Productive4.0) is an ambitious holistic innovation project, meant to open the doors to the potentials of Digital Industry and to maintain a leadership position of the industries in Europe. All partners involved will work on creating the capability to efficiently design and integrate hardware and software of Internet of Things (IoT) devices. Linking the real with the digital world takes more than just adding software to the hardware.

Disclaimer

Please be aware, that 4.1.3 is NOT backwards compatible with 4.1.2. If you have older systems please refer to the Migration Guide

Table of Contents

  1. Quick Start Guide
    1. Docker
    2. Debian Installer
    3. Compile Code
  2. Migration Guide 4.1.2 -> 4.1.3
  3. Certificates
  4. Gatekeeper and Gateway Setup with ActiveMQ Relay
  5. How to Contribute
  6. Documentation
    1. Service Registry
    2. Authorization
    3. Orchestrator
    4. EventHandler
    5. Gatekeeper
    6. Gateway

Quick Start Guide

Docker

Requirements

Note: A system with 4GB of RAM is advised.

Don't forget to create a volume for mysql: docker volume create --name=mysql
Don't forget to copy the initSQL.sh script next to the docker-compose file and execute it! On the first run it initializes the Database!
Example copy command which does this for you, execute from the project root directory.

cp scripts/initSQL.sh docker/
cd docker
./initSQL.sh

Inside the docker folder an example is provided.

Core System Config

Example Core System Configuration files are available in this folder.

Note: Don't forget to set domain.name and domain.port properties!

Docker Compose

Example Docker Compose file is located here. The interesting part is the volumes section. Format is /path/on/your/local/machine:/path/inside/docker/container

You may want to copy the config files elsewhere with the compose file too. If you copy them, please don't forget to change the volume mounting point, but DON'T change the volume mounting point inside the container, otherwise it will start up with default config.

To update the images: execute docker-compose pull command in the directory where the compose file is.

To start the containers: execute docker-compose up -d command in the directory where the compose file is.

Don't forget to check, are all containers up and running?

docker ps -a

If all of their is Up, you are all set. If they die, please check their logs.

If you change your config you have to restart the appropriate container

docker restart <containerName>

Handy Docker Commands
Command Description
docker ps -a List all containers
docker images List all images
docker-compose up -d Starts the Docker containers
docker-compose down Destroys the Docker containers
docker logs <containerName> Shows logs for the container
docker volume create --name=<volumeName> Creates a named volume
docker volume rm <volumeName> Removes the specified named volume
Troubleshooting

Q: MySQL won't start. What did went wrong?
A: Probably you missed to copy the init SQL script next to the compose file, or you have a typo in its name. Solution: https://github.com/arrowhead-f/core-java-spring/issues/105

Debian Installers

The Debian installer files are located in the deb-installer/package/arrowhead-installers-4.1.3 folder. Please follow this guide to install them: Debian Installer Guide

Note: Preferred installation mode for Raspberry Pi.

Compile source code and manually install MySQL and Maven.

Requirements

Note: A system with 2GB of RAM is advised.

The project has the following dependencies:

Verify that you have Java (java -version), Maven (mvn -version), MySQL installed properly!

Pull this code and enter the directory. git clone https://github.com/arrowhead-f/core-java-spring.git

Got to the scripts folder, execute mysql -u root -p < create_empty_arrowhead_db.sql MySQL script. If you won't run this script first, the project won't build.

cd core-java-spring

Execute mvn install -DskipTests command. Wait until the build succeeds. This command builds all available projects.

After the build is complete, the jars with the appropriate application.properites will be available in their directory.

Starting the core systems manually:

Change directory to:

  • serviceregistry/target directory. cd serviceregistry/target
    and execute: java -jar arrowhead-serviceregistry-4.1.3.jar
  • authorization/target directory. cd authorization/target
    and execute: java -jar arrowhead-authorization-4.1.3.jar
  • orchestrator/target directory. orchestrator/target
    and execute: java -jar arrowhead-orchestrator-4.1.3.jar

Starting the core system automatically:

After successful build enter the scripts folder and execute start_core_systems.sh or start_core_systems.bat depending on your operating system.

Wait until servers start...

Note: By default servers start in SECURE mode. To access them, you need to use an example certificate, provided in the certificate directory.

Note: If you wish to change the the configuration, do it by by modifying the application.properties file in the target directory! Don't forget to change all of them!

Service Registry will be available on https://localhost:8443
Authorization will be available on https://localhost:8445
Orchestrator will be available on https://localhost:8441
Event Handler will be available on https://localhost:8455
Gatekeeper will be available on https://localhost:8449
Gateway will be available on https://localhost:8453

Swagger with API documentation is available in the root route.

Insecure Mode - (not recommended)

To start in insecure mode, you have to change the server.ssl.enabled property to false. You'll have to do it for each core system, under the path target/application.properties. Note that if you recompile after the changes, the target/application.properties file will be overwritten by the default ones in the src/main/resources/application.properties.

The Gatekeeper and Gateway use encryption based on the certificates, hence there is no way to start the Gatekeeper and Gateway in insecure mode. But you can use the local cloud without these core systems. All you have to do is to set gatekeeper_is_present=false in the application.properties of the ochestrator, and start the script start_coresystems_local.bat or start_coresystems_local.sh depending on your operating system.

Migration Guide 4.1.2 -> 4.1.3

4.1.3 is NOT backwards compatible with 4.1.2! Earlier it was redundant and contained gaps. Now the database and the endpoints are redesigned, they are clean, more logical and easier to use.

You can migrate your existing database manually. See the Quick Start Guide, how to deploy the Core Systems.

Major endpoint changes:

Service Registry Core System:

The following endpoints no longer exist, instead use the ones on the right:

  • PUT /mgmt/services -> POST /serviceregistry/mgmt/services

  • PUT /mgmt/systems -> POST /serviceregistry/mgmt/systems

  • GET /serviceregistry/mgmt/systemId/{systemId} -> GET /serviceregistry/mgmt/systems/{id}

  • GET /serviceregistry/mgmt/serviceId/{serviceId}/providers

  • PUT /serviceregistry/mgmt/query -> POST /serviceregistry/query

  • PUT /serviceregistry/mgmt/subscriptions/{id}

  • PUT /serviceregistry/support/remove -> DELETE /serviceregistry/unregister

  • DELETE /serviceregistry/mgmt/all

  • serviceregistry/register - data structure changed

Description for this endpoint is available here: Register

Old payload, which is no longer usable

{
 "providedService" : {
   "serviceDefinition" : "IndoorTemperature",
   "interfaces" : [ "JSON", "XML" ],
   "serviceMetadata" : {
     "unit" : "celsius"
   }
 },
 "provider" : {
   "systemName" : "InsecureTemperatureSensor",
   "address" : "192.168.0.2",
   "port" : 8080
 },
 "serviceURI" : "temperature",
 "version" : 1,
 "udp" : false,
 "ttl" : 0
}

New payload - you can easily map the old fields to the new ones.

{
 "serviceDefinition": "IndoorTemperature",
 "providerSystem": {
   "systemName": "InsecureTemperatureSensor",
   "address": "192.168.0.2",
   "port": 8080,
 "authenticationInfo": "eyJhbGciOiJIUzI1Ni..."
},
 "serviceUri": "temperature",
 "endOfValidity": "2019-12-05T12:00:00",
 "secure": "TOKEN",
 "metadata": {
   "unit": "celsius"
},
 "version": 1,
 "interfaces": [
   "HTTP-SECURE-JSON"
 ]
}

Authorization Core System:

  • /mgmt/intracloud - data structure changed
  • /mgmt/intercloud - data structure changed

How to Add Intracloud rules
How to Add Intercloud rules

Orchestration Core System:

  • /mgmt/store - data structure changed
  • /orchestrator/orchestration - data structure changed

Description for this endpoint is available here: Orchestration

Old payload, which is no longer usable

{
 "requesterSystem" : {
   "systemName" : "client1",
   "address" : "localhost",
   "port" : 0,
   "authenticationInfo" : "null"
 },
 "requestedService" : {
   "serviceDefinition" : "IndoorTemperature",
   "interfaces" : [ "json" ],
   "serviceMetadata" : {
     "unit" : "celsius"
   }
 },
 "orchestrationFlags" : {
   "onlyPreferred" : false,
   "overrideStore" : true,
   "externalServiceRequest" : false,
   "enableInterCloud" : true,
   "enableQoS" : false,
   "matchmaking" : false,
   "metadataSearch" : true,
   "triggerInterCloud" : false,
   "pingProviders" : false
 },
 "preferredProviders" : [ ],
 "requestedQoS" : { },
 "commands" : { }
}

New payload - you can easily map the old fields to the new ones.

{
  "requesterSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "requestedService": {
    "serviceDefinitionRequirement": "string",
    "interfaceRequirements": [
      "string"
    ],
    "securityRequirements": [
      "NOT_SECURE", "CERTIFICATE", "TOKEN"
    ],
    "metadataRequirements": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "versionRequirement": 0,
    "maxVersionRequirement": 0,
   "minVersionRequirement": 0
  },
  "preferredProviders": [
    {
      "providerCloud": {
        "operator": "string",
        "name": "string"
      },
      "providerSystem": {
        "systemName": "string",
        "address": "string",
        "port": 0
      }
    }
  ],
  "orchestrationFlags": {
    "additionalProp1": true,
    "additionalProp2": true,
    "additionalProp3": true
  }
}

Certificates

Arrowhead Framework's security is relying on SSL Certificate Trust Chains. The Arrowhead trust chain consists of three level:

  1. Master certificate: arrowhead.eu
  2. Cloud certificate: my_cloud.my_company.arrowhead.eu
  3. Client certificate: my_client.my_cloud.my_company.arrowhead.eu The certificate naming convention have strict rules:
  • The different parts are delimited by dots, therefore parts are not allowed to contain any of them.
  • A cloud certificate name has to consist of four part and the last two part have to be 'arrowhead' and 'eu'.
  • A client certificate name has to consist of five part and the last two part have to be 'arrowhead' and 'eu'.

The trust chain is created by issuing the cloud certificate from the master certificate and the client certificate from the cloud certificate. With other words, the cloud certificate is signed by the master certificate's private key and the client certificate is signed by the cloud certificate's private key which makes the whole chain trustworthy.

The Key-Store

The Key-Store is intended to store the certificates and/or key-pair certificates. Key-pair certificates are contain the certificate chain with some additinal data, such as the private-public keys, which are necessary for the secure operation. Certificates located in this store (without the keys) will be attached to the outcoming HTTPS requests. Arrowhead Framework is designed for handling the p12 type of Key-Stores.

(Note: When you creating a new key-pair certificate, then the key-password and the key-store-password must be the same.)

The Trust-Store

The Trust-Store is containing those certificates, what the web-server considers as trusted ones. Arrowhead Framework is designed for handling the p12 type of Trust-Stores. Typically your Trust-Store should contain only the cloud certificate, which ensures that only those incoming HTTPS requests are authorized to access, which are having this certificate within their certificate chain.

How to create my own certificates?

Currently Arrowhead community have the possibility to create only "self signed" certifications. See the tutorials:

System Operator Certificate

The System Operator Certificate is a special client certificate with the naming convention of sysop.my_cloud.my_company.arrowhead.eu. SysOp certificate allows the client to use the management endpoints of the Arrowhead Core Systems. Typical usage of SysOp certificate is by front end applications running in a web browser.

Include certificate in Docker container

The following guide describes step by step, how to include your own certificates into a Docker container.

Gatekeeper and Gateway Setup with ActiveMQ Relay

Please follow this guide to setup the Arrowhead Gatekeeper and Gateway core systems: Gatekeeper & Gateway Setup Guide with ActiveMQ Relay

How to Contribute

Open Development

All work on Arrowhead repositories happens directly on GitHub. Both core team members and external contributors send pull requests which go through the same review process.

Branch Organization

The latest version of the core systems are available in the master branch. The code for the next release is merged in the development branch. If you would like to contribute, please check out the development branch. Create a new branch from development. Don't forget do write documentation, unit and integration tests. When finished, create a pull request back into development. If accepted, your contribution will be in the next release. :)

Bugs

Where To Find Known Issues

We are using GitHub Issues for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn’t already exist.

Reporting New Issues

The best way to get your bug fixed is to provide a reduced test case.

How to Get in Touch

Join our developer team on Slack. Write an email to [email protected] for an invite.

Documentation

Service Registry

System Design Description Overview

This System provides the database, which stores information related to the currently actively offered Services within the Local Cloud.

The purpose of this System is therefore to allow:

  • Application Systems to register what Services they offer at the moment, making this announcement available to other Application Systems on the network.
  • They are also allowed to remove or update their entries when it is necessary.
  • All Application Systems can utilize the lookup functionality of the Registry to find Public Core System Service offerings in the network, otherwise the Orchestrator has to be used.

However, it is worth noting, that within this generation the lookup functionality of Services is integrated within the “orchestration process”. Therefore, in the primary scenario, when an Application System is looking for a Service to consume, it shall ask the Orchestrator System via the Orchestration Service to locate one or more suitable Service Providers and help establish the connection based on metadata submitted in the request. Direct lookups from Application Systems within the network is not advised in this generation, due to security reasons.

However, the lookup of other Application Systems and Services directly is not within the primary use, since access will not be given without the Authorization JWT (JSON Web Token). The use of the TokenGeneration is restricted to the Orchestrator for general System accountability reasons.

Services and Use Cases

This System only provides one Core Service the Service Discovery

There are two use case scenarios connected to the Service Registry.

  • Service registration, de-registration
  • Service Registry querying (lookup)

The register method is used to register services. The services will contain various metadata as well as a physical endpoint. The various parameters are representing the endpoint information that should be registered.

The unregister method is used to unregister service instances that were previously registered in the Registry. The instance parameter is representing the endpoint information that should be removed.

The query method is used to find and translate a symbolic service name into a physical endpoint, for example an IP address and a port. The query parameter is used to request a subset of all the registered services fulfilling the demand of the user of the service. The returned listing contains service endpoints that have been fulfilling the query.

There is another functionality that does not bound to any Services, just an internal part of the Service Registry. There are two optional cleanup tasks within the Service Registry, which can be used to remove old, inactive service offerings. The first task is based on pinging the service provider and if the provider does not respond to the ping, its offered services will be deleted. The second task is based on a feature, called “Time to Live”. Service providers upon registration can provide a timestamp called “end_of_validity” number, which specifies how long the service will be offered by the provider, making the service de-registrations unnecessary, if this task is active. The task is used to remove expired services. The third task is using a feature called "Heartbeat" (Not yet implemented), where the Service provider periodically signals to the Service Registry that it is still alive. When it misses it will be removed. All of these internal tasks can be configured in the application.properties file.

Security

This System can be secured via the HTTPS protocol. If it is started in secure mode, it verifies whether the Application System possesses a proper X.509 identity certificate and whether that certificate is Arrowhead compliant in its making. This certificate structure and creation guidelines ensure:

  • Application System is properly bootstrapped into the Local Cloud
  • The Application System indeed belongs to this Local Cloud
  • The Application System then automatically has the right to register its Services in the Registry.

If these criteria are met, the Application System’s registration or removal message is processed. An Application System can only delete or alter entries that contain the Application System as the Service Provider in the entry.

Endpoints

The Service Registry offers three types of endpoints. Client, Management and Private.

Swagger API documentation is available on: https://<host>:<port>
The base URL for the requests: http://<host>:<port>/serviceregistry

Client endpoint description

Function URL subpath Method Input Output
Echo /echo GET - OK
Query /query POST ServiceQueryForm ServiceQueryList
Register /register POST ServiceRegistryEntry ServiceRegistryEntry
Unregister /unregister DELETE Address, Port, Service Definition, System Name in query parameters OK

Private endpoint description

These services can only be used by other core services, therefore they are not part of the public API.

Function URL subpath Method Input Output
Query System /query/system POST System System
Query System By ID /query/system/{id} GET ID System

Management endpoint description

There endpoints are mainly used by the Management Tool and Cloud Administrators.

Function URL subpath Method Input Output
Get all entries /mgmt/ GET - ServiceRegistryEntryList
Add an entry /mgmt/ POST ServiceRegistryEntry ServiceRegistryEntry
Get an entry by ID /mgmt/{id} GET ServiceID ServiceRegistryEntry
Replace an entry by ID /mgmt/{id} PUT ServiceRegistryEntry ServiceRegistryEntry
Modify an entry by ID /mgmt/{id} PATCH Key value pairs of ServiceRegistryEntry ServiceRegistryEntry
Delete and entry by ID /mgmt/{id} DELETE ServiceRegistryEntryID -
Get grouped view /mgmt/grouped GET - ServiceRegistryGrouped
Get Service Registry Entries by Service Definition /mgmt/servicedef/
{serviceDefinition}		 GET ServiceDefinition ServiceRegistryEntryList
Get all services /mgmt/services GET - ServiceDefinitionList
Add a service /mgmt/services POST ServiceDefinition ServiceDefinition
Get a service by ID /mgmt/services/{id} GET ServiceID ServiceDefinition
Replace a service by ID /mgmt/services/(id} PUT Service ServiceDefinition
Modify a service by ID /mgmt/services/{id} PATCH Key value pairs of ServiceDefinition ServiceDefinition
Delete a service by ID /mgmt/services/{id} DELETE ServiceID -
Get all systems /mgmt/systems GET - SystemList
Add a system /mgmt/systems POST System System
Get a system by ID /mgmt/systems/{id} GET SystemID System
Replace a system by ID /mgmt/systems/{id} PUT System System
Modify a system by ID /mgmt/systems/{id} PATCH Key value pairs of System System
Delete a system by ID /mgmt/systems/{id} DELETE SystemID -

Removed Endpoints

The following endpoints no longer exist:

  • PUT /mgmt/services
  • PUT /mgmgt/systems
  • GET /serviceregistry/mgmt
  • GET /serviceregistry/mgmt/systemId/{systemId}
  • GET /serviceregistry/mgmt/serviceId/{serviceId}/providers
  • PUT /serviceregistry/mgmt/query
  • PUT /serviceregistry/mgmt/subscriptions/{id}
  • PUT /serviceregistry/support/remove
  • DELETE /serviceregistry/mgmt/all

Echo

GET /serviceregistry/echo

Returns a "Got it" message with the purpose of testing the core service availability.

Note: 4.1.2 version: GET /serviceregistry

Query

POST /serviceregistry/query

Returns ServiceQueryList that fits the input specification. Mainly used by the Orchestrator.

ServiceQueryForm is the input

{
 "serviceDefinitionRequirement": "string",
 "interfaceRequirements": [
   "string"
 ],
 "securityRequirements": [
   "NOT_SECURE"
 ],
 "metadataRequirements": {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
 },
 "versionRequirement": 0,
 "maxVersionRequirement": 0,
 "minVersionRequirement": 0,
 "pingProviders": true
}
Field Description Mandatory
serviceDefinitionRequirement Name of the required Service Definition yes
interfaceRequirements List of required interfaces no
securityRequirements List of required security settings no
metadataRequirements Key value pairs of required metadata no
versionRequirement Required version number no
maxVersionRequirement Maximum version requirement no
minVersionRequirement Minimum version requirement no
pingProviders Return only available providers no

Note: Valid interfaceRequirements name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTPS-SECURE-JSON)

Note: Possible values for securityRequirements are:

  • NOT_SECURE
  • CERTIFICATE
  • TOKEN
  • not defined, if you don't want to filter on security type

Returns a ServiceQueryList

{
 "serviceQueryData": [
   {
     "id": 0,
     "serviceDefinition": {
       "id": 0,
       "serviceDefinition": "string",
       "createdAt": "string",
       "updatedAt": "string"
     },
     "provider": {
       "id": 0,
       "systemName": "string",
       "address": "string",
       "port": 0,
       "authenticationInfo": "string",
       "createdAt": "string",
       "updatedAt": "string"
     },
     "serviceUri": "string",
     "endOfValidity": "string",
     "secure": "NOT_SECURE",
     "metadata": {
       "additionalProp1": "string",
       "additionalProp2": "string",
       "additionalProp3": "string"
     },
     "version": 0,
     "interfaces": [
       {
         "id": 0,
         "interfaceName": "string",
         "createdAt": "string",
         "updatedAt": "string"
       }
     ],
     "createdAt": "string",
     "updatedAt": "string"
    }
 ],
 "unfilteredHits": 0
}
Field Description
serviceQueryData The array of objects containing the data
id ID of the entry, used by the Orchestrator
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp.
secure Security info
metadata Metadata
version Version of the Service
interfaces List of interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated
unfilteredHits Number of hits based on service definition without filters

Note: 4.1.2 version: PUT /serviceregistry /query
This version always returned the records in an array of JSON objects. The response did not contain any information about the unfiltered hits and the objects did not contain any modification related timestamp information. Interfaces and metadata were bound to the service definition and security type was not defined. Service Registry object did contain an "udp" flag beside the interface definition.
Query activity diagram

Alt text

Register

POST /serviceregistry/register

Registers a service. A provider is allowed to register only its own services. It means that provider system name and certificate common name must match for successful registration.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
  ]
}
Field Description Mandatory
serviceDefinition Service Definition yes
providerSystem Provider System yes
serviceUri URI of the service yes
endOfValidity Service is available until this UTC timestamp no
secure Security info no
metadata Metadata no
version Version of the Service no
interfaces List of the interfaces the Service supports yes

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTPS-SECURE-JSON)

Note: authenticationInfo is the public key of the system. In Insecure mode you can omit sending this key.

Note: Possible values for secure are:

  • NOT_SECURE (default value if field is not defined)
  • CERTIFICATE
  • TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}
Field Description
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /serviceregistry/register
In this version interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.
Register activity diagram

Alt text

Unregister

DELETE /serviceregistry/unregister

Removes a registered service. A provider is allowed to unregister only its own services. It means that provider system name and certificate common name must match for successful unregistration.

Query params:

Field Description Mandatory
service_definition Name of the service to be removed yes
system_name Name of the Provider yes
address Address of the Provider yes
port Port of the Provider yes

Note: 4.1.2 version: PUT /serviceregistry/remove
In this version the input was a JSON object with many unnecessary information.

Unregister activity diagram

Alt text

Query System

POST /serviceregistry/query/system

This service can only be used by other core services, therefore is not part of the public API.

Query System by ID

GET /serviceregistry/system/{id}

This service can only be used by other core services, therefore is not part of the public API.

Get all entries

GET /serviceregistry/mgmt

Returns a list of Service Registry records. If page and item_per_page are not defined, returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns a ServiceRegistryEntryList

{
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceUri": "string",
      "endOfValidity": "string",
      "secure": "NOT_SECURE",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "version": 0,
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}
Field Description
data Array of ServiceRegistryEntry
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated
count Number of entries found

Note 4.1.2 version: GET /serviceregistry/mgmt/all
This version always returned the records in an array of JSON objects. The objects did not contain any modification related time stamp information. Interfaces and metadata were bound to the service definition and security type was not defined. Service Registry object did contain an "udp" flag beside the interface definition.

Add an entry

POST /serviceregistry/mgmt

Creates service registry record and returns the newly created record.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
 ]
}
Field Description Mandatory
serviceDefinition Service Definition yes
providerSystem Provider System yes
serviceUri URI of the Service no
endOfValidity Service is available until this UTC timestamp. no
secure Security info no
metadata Metadata no
version Version of the Service no
interfaces List of the interfaces the Service supports yes

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTPS-SECURE-JSON)

Note: Possible values for secure are:

  • NOT_SECURE (default value if field is not defined)
  • CERTIFICATE
  • TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}
Field Description
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /serviceregistry/support/register
It was available for clients as well, not only for the system operator of the local cloud. Interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.

Get an entry by ID

GET /serviceregistry/mgmt/{id}

Returns the Service Registry Entry specified by the ID path parameter.

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}
Field Description
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /serviceregistry/mgmt/id/{id}
In this version interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.

Replace an entry by ID

PUT /serviceregistry/mgmt/{id}

Updates and returns the modified service registry record specified by the id path parameter. Not defined fields are going to be updated to "null" value.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
 ]
}
Field Description Mandatory
serviceDefinition Service Definition yes
providerSystem Provider System yes
serviceUri URI of the Service no
endOfValidity Service is available until this UTC timestamp. no
secure Security info no
metadata Metadata no
version Version of the Service no
interfaces List of the interfaces the Service supports yes

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTPS-SECURE-JSON)

Note: Possible values for secure are:

  • NOT_SECURE (default value if field is not defined)
  • CERTIFICATE
  • TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}
Field Description
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: PUT /serviceregistry/mgmt/update/{id}
In this version interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.

Modify an entry by ID

PATCH /serviceregistry/mgmt/{id}

Updates and returns the modified service registry record specified by the id path parameter. Not defined fields are NOT going to be updated.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
 ]
}
Field Description Mandatory
serviceDefinition Service Definition no
providerSystem Provider System no
serviceUri URI of the Service no
endOfValidity Service is available until this UTC timestamp. no
secure Security info no
metadata Metadata no
version Version of the Service no
interfaces List of the interfaces the Service supports no

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTPS-SECURE-JSON)

Note: Possible values for secure are:

  • NOT_SECURE (default value if field is not defined)
  • CERTIFICATE
  • TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}
Field Description
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: Not existed

Delete an entry by ID

DELETE /serviceregistry/mgmt/{id}

Remove the service registry record specified by the id path parameter.

Note: 4.1.2 version: DELETE /serviceregistry/mgmt/{entryId}
This version did return Http 404 (not found), when record was not found by id.

Get grouped view

GET /serviceregistry/mgmt/grouped

Returns all Service Registry Entries grouped for the purpose of the Management Tools' Service Registry view:

  • autoCompleteData
  • servicesGroupedByServiceDefinition
  • servicesGroupedBySystems

Returns a ServiceRegistryGrouped

{
  "autoCompleteData": {
    "interfaceList": [
      {
        "id": 0,
        "value": "string"
      }
    ],
    "serviceList": [
      {
        "id": 0,
        "value": "string"
      }
    ],
    "systemList": [
      {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
  },
  "servicesGroupedByServiceDefinition": [
    {
      "serviceDefinitionId": 0,
      "serviceDefinition": "string",
      "providerServices": [
        {
          "id": 0,
          "serviceDefinition": {
            "id": 0,
            "serviceDefinition": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "provider": {
            "id": 0,
            "systemName": "string",
            "address": "string",
            "port": 0,
            "authenticationInfo": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "serviceUri": "string",
          "endOfValidity": "string",
          "secure": "NOT_SECURE",
          "metadata": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "version": 0,
          "interfaces": [
            {
              "id": 0,
              "interfaceName": "string",
              "createdAt": "string",
              "updatedAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        }
      ]
    }
  ],
  "servicesGroupedBySystems": [
    {
      "systemId": 0,
      "systemName": "string",
      "address": "string",
      "port": 0,
      "services": [
        {
          "id": 0,
          "serviceDefinition": {
            "id": 0,
            "serviceDefinition": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "provider": {
            "id": 0,
            "systemName": "string",
            "address": "string",
            "port": 0,
            "authenticationInfo": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "serviceUri": "string",
          "endOfValidity": "string",
          "secure": "NOT_SECURE",
          "metadata": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "version": 0,
          "interfaces": [
            {
              "id": 0,
              "interfaceName": "string",
              "createdAt": "string",
              "updatedAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        }
      ]
    }
  ]
}
Field Description
autocompleteData Data for the Management Tools' autocomplete engine
servicesGroupedByServiceDefinitionAndInterface Services Grouped by Service Definition and Interface
servicesGroupedBySystems Services Grouped By Systems

Note: 4.1.2 version: Not existed

Get Service Registry Entries by Service Definition

GET /serviceregistry/mgmt/servicedef/{serviceDefinition}

Returns a list of Service Registry records specified by the serviceDefinition path parameter. If page and item_per_page are not defined, returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns a ServiceRegistryEntryList

{
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceUri": "string",
      "endOfValidity": "string",
      "secure": "NOT_SECURE",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "version": 0,
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}
Field Description
data Array of ServiceRegistryEntry
id ID of the ServiceRegistryEntry
serviceDefinition Service Definition
provider Provider System
serviceUri URI of the Service
endOfValidity Service is available until this UTC timestamp
secure Security info
metadata Metadata
version Version of the Service
interfaces List of the interfaces the Service supports
createdAt Creation date of the entry
updatedAt When the entry was last updated
count Number of entries found

Note: 4.1.2 version: GET /serviceregistry/mgmt/servicedef/{serviceDefinition}
This version always returned the records in an array of JSON objects. The objects did not contain any modification related time stamp information. Interfaces and metadata were bound to the service definition and security type was not defined. Service Registry object did contain an "udp" flag beside the interface definition.

Get all services

GET /serviceregistry/mgmt/services

Returns a list of Service Definition records. If page and item_per_page are not defined, returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns a ServiceDefinitionList

{
  "data": [
    {
      "id": 0,
      "serviceDefinition": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
   ],
  "count": 0
}

Note: 4.1.2 version: GET /mgmt/services
This version always returned the records in an array of JSON objects. The objects did not contain any modification related time stamp information. Interfaces and metadata were part of the service definition entity.

Add a service

POST /serviceregistry/mgmt/services

Creates service definition record and returns the newly created record.

Service Definition is the input

{
  "serviceDefinition": "string"
}
Field Description Mandatory
serviceDefinition Service Definition yes

Returns a Service Definition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
serviceDefinition Service Definition
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /mgmt/services
In this version interfaces and metadata were part of the service definition entity. The response object did not contain any modification related time stamp information.

Get a service by ID

GET /serviceregistry/mgmt/services/{id}

Returns the Service Definition record specified by the id path parameter.

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
serviceDefinition Service Definition
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /mgmt/services/{serviceId} The response object did not contain any modification related time stamp information. Interfaces and metadata were part of the service definition entity.

Replace a service by ID

PUT /serviceregistry/mgmt/services/{id}

Updates and returns the modified Service Definition record specified by the ID path parameter.

ServiceDefinition is the input

{
  "serviceDefinition": "string"
}
Field Description Mandatory
serviceDefinition Service Definition yes

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
serviceDefinition Service Definition
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: PUT /mgmt/services/{serviceId}
The response object did not contain any modification related time stamp information. Interfaces and metadata were part of the service definition entity.

Modify a service by ID

PATCH /serviceregistry/mgmt/services/{id}

Updates and returns the modified Service Definition record specified by the ID path parameter.

ServiceDefinition is the input

{
  "serviceDefinition": "string"
}
Field Description Mandatory
serviceDefinition Service Definition no

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
serviceDefinition Service Definition
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: Not existed

Delete a service by ID

DELETE /serviceregistry/mgmt/services/{id}

Removes the service definition record specified by the id path parameter.

Note: 4.1.2 version: DELETE /mgmt/services/{serviceId} This version did return HTTP 404 (Not Found), when record was not found by ID.

Get all systems

GET /serviceregistry/mgmt/systems

Returns a list of System records. If page and item_per_page are not defined, it returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns a SystemList

{
  "data": [
    {
      "id": 0,
      "systemName": "string",
      "address": "string",
      "port": 0,
      "authenticationInfo": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}
Field Description
id ID of the entry
systemName Name of the System
address Address
port Port
authenticationInfo Authentication Info
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /mgmt/systems This version always returned the records in an array of JSON objects. The objects did not contain any modification related time stamp information.

Add a system

POST /serviceregistry/mgmt/systems

Creates a System record and returns the newly created record.

System is the input

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}
Field Description Mandatory
systemName Name of the System yes
address Address yes
port Port yes
authenticationInfo Authentication Info no

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
systemName Name of the System
address Address
port Port
authenticationInfo Authentication Info
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /mgmt/systems
In this version the response object did not contain any modification related time stamp information.

Get a system by ID

GET /serviceregistry/systems/{id}

Returns the System record specified by the ID path parameter.

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
systemName Name of the System
address Address
port Port
authenticationInfo Authentication Info
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /mgmt/systems/{systemId}
In this version the response object did not contain any modification related time stamp information

Replace a system by ID

PUT /serviceregistry/mgmt/systems/{id}

Updates and returns the modified System record specified by the ID path parameter. Not defined fields are going to be updated to "null" value.

System is the input

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}
Field Description Mandatory
systemName Name of the System yes
address Address yes
port Port yes
authenticationInfo Authentication Info no

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
systemName Name of the System
address Address
port Port
authenticationInfo Authentication Info
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: PUT /mgmt/systems/{systemId}
In this version the response object did not contain any modification related time stamp information.

Modify a system by ID

PATCH /serviceregistry/mgmt/systems/{id}

Updates and returns the modified system record specified by the id path parameter. Not defined fields are going to be NOT updated.

System is the input

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}
Field Description Mandatory
systemName Name of the System no
address Address no
port Port no
authenticationInfo Authentication Info no

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
systemName Name of the System
address Address
port Port
authenticationInfo Authentication Info
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: Not existed

Delete a system by ID

DELETE /serviceregistry/mgmt/systems/{id}

Removes the System record specified by the ID path parameter.

Note: 4.1.2 version: DELETE /mgmt/systems/{systemId}
This version did return HTTP 404 (Not Found), when record was not found by ID.

Authorization

System Design Description Overview

This System has:

  • A database that describes which Application System can consume what Services from which Application Systems (Intra-Cloud access rules)
  • A database that describes which other Local Clouds are allowed to consume what Services from this Cloud (Inter-Cloud authorization rules)

The purpose of this System is therefore to:

  • Provide AuthorizationControl Service (both intra- and inter-Cloud)
  • Provide a TokenGeneration Service for allowing session control within the Local Cloud

The purpose of the TokenGeneration functionality is to create session control functionality through the Core Sytems. The output is JSON Web Token that validates the Service Consumer system when it will try to access the Service from another Application System (Service Provider). This Token shall be primarily generated during the orchestration process and only released to the Service Consumer when all affected Core Systems are notified and agreed to the to-be-established Service connection.

This System (in line with all core Systems) utilizes the X.509 certificate Common Name naming convention in order to work.

Services and Use Cases

This System only provides two Core Services:

  • AuthorizationControl
  • TokenGeneration

There are two use cases connected to the Authorization System:

  • Check access rights (invoke the AuthorizationControl)
  • Generate an access token (the Orchestrator invokes the TokenGeneration)

Authorization Cross check Figure 1. Authorization crosscheck during orchestration process

Service Description Overview

The AuthorizationControl Service provides 2 different interfaces to look up authorization rights:

  • Intra-Cloud authorization: defines an authorization right between a consumer and provider system in the same Local Cloud for a specific Service.
  • Inter-Cloud authorization: defines an authorization right for an external Cloud to consume a specific Service from the Local Cloud.

Endpoints

The Authorization offers three types of endpoints. Client, Management and Private.

Swagger API documentation is available on: https://<host>:<port>
The base URL for the requests: http://<host>:<port>/authorization

Client endpoint description

Function URL subpath Method Input Output
Echo /echo GET - OK
Get Public Key /publickey GET - Public Key

Private endpoint description

These services can only be used by other core services, therefore they are not part of the public API.

Function URL subpath Method Input Output
Check an Intercloud rule /intercloud/check POST InterCloudRule InterCloudResult
Check an Intracloud rule /intracloud/check POST IntraCloudRule IntraCloudResult
Generate Token /token POST TokenRule TokenData

Management Endpoint Description

There endpoints are mainly used by the Management Tool and Cloud Administrators.

Function URL subpath Method Input Output
Get all Intracloud rules /mgmt/intracloud GET - IntracloudRuleList
Add Intracloud rules /mgmt/intracloud POST IntracloudRuleForm IntracloudRuleList
Get an Intracloud rule by ID /mgmt/intracloud/{id} GET IntracloudRuleID IntracloudRule
Delete an Intracloud rule by ID /mgmt/intracloud/{id} DELETE IntracloudRuleID -
Get all Intercloud rules /mgmt/intercloud GET - IntercloudRuleList
Add Intercloud rules /mgmt/intercloud POST IntercloudRuleForm IntercloudRuleList
Get an Intercloud rule by ID /mgmt/intercloud/{id} GET IntercloudRuleID IntercloudRuleList
Delete an Intercloud rule by ID /mgmt/intercloud/{id} DELETE IntercloudRuleID -

Removed Endpoints

The following services no longer exist:

  • GET /authorization/mgmt/intracloud/systemId/{systemId}/services
  • GET /authorization/mgmt/intracloud/systemId/{systemId}
  • GET /authorization/mgmt/intracloud/servicedef/{serviceDefinition}
  • PUT /authorization/mgmt/intracloud
  • DELETE /authorization/mgmt/intracloud/systemId/{systemId}
  • GET /authorization/mgmt/intercloud/operator/{operator}/cloudname/{cloudName}/services
  • GET /authorization/mgmt/intercloud/operator/{operator}/cloudname/{cloudName}
  • GET /authorization/mgmt/intercloud/servicedef/{serviceDefinition}
  • PUT /authorization/mgmt/intercloud
  • DELETE /authorization/mgmt/intercloud/operator/{operator}/cloudname/{cloudName}

Echo

GET /authorization/echo

Returns a "Got it" message with the purpose of testing the core service availability.

Note: 4.1.2 version: GET /authorization/mgmt It was only available for the system operator of the local cloud.

Get Public Key

GET /authorization/publickey

Returns the public key of the Authorization core service as a (Base64 encoded) text. This service is necessary for providers if they want to utilize the token based security.

Note:: 4.1.2 version: GET /authorization/mgmt/publickey It was only available for system operator of the local cloud.

Check an Intercloud rule

POST /authorization/intercloud/check

This service can only be used by other core services, therefore is not part of the public API.

Checks whether a Cloud is authorized to use a Service

InterCloudRule is the input

{
  "cloud": {
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ],
    "name": "string",
    "neighbor": true,
    "operator": "string",
    "secure": true
  },
  "providerIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "serviceDefinition": "string"
}
Field Description Mandatory
cloud Cloud yes
providerIdsWithInterfaceIds Provider IDs with Interface IDs yes

Returns an InterCloudResult

{
  "authorizedProviderIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "cloud": {
    "authenticationInfo": "string",
    "createdAt": "string",
    "id": 0,
    "name": "string",
    "neighbor": true,
    "operator": "string",
    "ownCloud": true,
    "secure": true,
    "updatedAt": "string"
  },
  "serviceDefinition": "string"
}
Field Description
authorizedProviderIdsWithInterfaceIds Authorized Provider IDs with Interface IDs
cloud Cloud

Check an Intracloud rule

POST /authorization/intracloud/check

This service can only be used by other core services, therefore is not part of the public API.

Checks whether the consumer System can use a Service from a list of provider Systems

IntraCloudRule is the input

{
  "consumer": {
    "address": "string",
    "authenticationInfo": "string",
    "port": 0,
    "systemName": "string"
  },
  "providerIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "serviceDefinitionId": 0
}
Field Description Mandatory
consumer Consumer yes
providerIdsWithInterfaceIds Provider IDs with Interface IDs yes
serviceDefinitionId Service Definition ID yes

Returns a IntraCloudResult

{
  "authorizedProviderIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "consumer": {
    "address": "string",
    "authenticationInfo": "string",
    "createdAt": "string",
    "id": 0,
    "port": 0,
    "systemName": "string",
    "updatedAt": "string"
  },
  "serviceDefinitionId": 0
}
Field Description
authorizedProviderIdsWithInterfaceIds Authorized Provider IDs with Interface IDs
consumer Consumer
serviceDefinitionId Service Definition ID

Generate Token

POST /authorization/token

This service can only be used by other core services, therefore is not part of the public API.

Generates a JWT for Authentication

TokenRule is the input

{
  "consumer": {
    "address": "string",
    "authenticationInfo": "string",
    "port": 0,
    "systemName": "string"
  },
  "consumerCloud": {
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ],
    "name": "string",
    "neighbor": true,
    "operator": "string",
    "secure": true
  },
  "duration": 0,
  "providers": [
    {
      "provider": {
        "address": "string",
        "authenticationInfo": "string",
        "port": 0,
        "systemName": "string"
      },
      "serviceInterfaces": [
        "string"
      ]
    }
  ],
  "service": "string"
}
Field Description Mandatory
consumer Consumer yes
consumerCloud Cloud of the Consumer yes
duration Validity duration of the Token yes
providers Providers yes
service Service yes

Returns a TokenData

{
  "tokenData": [
    {
      "providerAddress": "string",
      "providerName": "string",
      "providerPort": 0,
      "tokens": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ]
}
Field Description
tokenData Token Data

###Get all Intracloud rules

GET /authorization/mgmt/intracloud

Returns a list of Intracloud authorization records. If page and item_per_page are not defined, it returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns an IntracloudRuleList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count number of records
data An array containing the data
id ID of the entry
consumerSystem Consumer System
providerSystem Provider System
serviceDefinition Service Definition
interfaces Interfaces
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: Authorization is a little stricter than before: the access now depends on specific interfaces besides provider and service.

Note: 4.1.2 version: GET /authorization/mgmt/intracloud
This version always returned all records in an array of JSON objects. The objects did not contain any time information. Access didn't depend on interface.

Add Intracloud rules

POST /authorization/mgmt/intracloud

Creates Intracloud authorization rules and returns the newly created rules.

IntracloudRuleForm is the input

{
  "consumerId": 0,
  "providerIds": [
    0
  ],
  "interfaceIds": [
    0
  ],
  "serviceDefinitionIds": [
    0
  ]
}

Note: This is a very general stucture, however only two possible combinations are allowed:

  • One provider ID, one interface ID with multiple service definition IDs
  • Multiple provider IDs, multiple interface IDs with one service definition ID.
Field Description Mandatory
consumerId ID of the consumer yes
providerIds IDs of the providers yes
interfaceIds IDs of the interfaces yes
serviceDefinitionIds IDs of the Service Definitions yes

Returns an IntracloudRuleList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count number of records
data An array containing the data
id ID of the entry
consumerSystem Consumer System
providerSystem Provider System
serviceDefinition Service Definition
interfaces Interfaces
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /authorization/mgmt/intracloud
This version required whole JSON objects as consumer, provider and service instead of ids and didn't use interface restrictions.

Get an Intracloud rule by ID

GET /authorization/mgmt/intracloud/{id}

Returns the Intracloud related authorization rule specified by the ID path parameter.

Returns an IntraCloudRule

{
  "id": 0,
  "consumerSystem": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "providerSystem": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the entry
consumerSystem Consumer System
providerSystem Provider System
serviceDefinition Service Definition
interfaces Interfaces
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /authorization/mgmt/intracloud/{id}
The returned structure did not contain time information and interface restrictions

Delete an Intracloud rule by ID

DELETE /authorization/mgmt/intracloud/{id}

Removes the Intracloud related authorization rule specified by the ID path parameter.

Note: 4.1.2 version: DELETE /authorization/mgmt/intracloud/{id} Same the new version.

Get all Intercloud rules

GET authorization/mgmt/intercloud

Returns a list of Intercloud related authorization rules. If page and item_per_page are not defined, it returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns an IntercloudRuleList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "cloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count number of records
data An array containing the data
id ID of the entry
cloud Cloud information
provider Provider System
serviceDefinition Service Definition
interfaces Interfaces
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: Authorization is stricter than before: the access now depends on specific provider and interfaces besides service.

Note: 4.1.2 version: GET /authorization/mgmt/intercloud
This version always returned all records in an array of JSON objects. The objects did not contain any time information. Access didn't depend on provider and interface.

Add Intercloud rules

POST /authorization/mgmt/intercloud

Creates Intercloud authorization rules and returns the newly created rules.

Input is IntercloudRuleForm

{
  "cloudId": 0,
  "providerIdList": [
    0
  ],
  "interfaceIdList": [
    0
  ],
  "serviceDefinitionIdList": [
    0
  ]
}

Note: This is a very general stucture, however only two possible combinations are allowed:

  • One provider ID, one interface ID with multiple service definition IDs
  • Multiple provider IDs, multiple interface IDs with one service definition ID.
Field Description Mandatory
cloudId ID of the Cloud yes
providerIds IDs of the providers yes
interfaceIds IDs of the interfaces yes
serviceDefinitionIds IDs of the Service Definitions yes

Returns an IntercloudRuleList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "cloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count number of records
data An array containing the data
id ID of the entry
cloud Cloud information
provider Provider System
serviceDefinition Service Definition
interfaces Interfaces
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /authorization/mgmt/intercloud
This version required whole JSON objects as consumer cloud and service instead of ids and didn't use provider and interface restrictions.

Get an Intercloud rule by ID

GET /authorization/mgmt/intercloud/{id}

Returns the Intercloud related authorization record specified by the ID path parameter.

Returns an IntercloudRuleList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "cloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count number of records
data An array containing the data
id ID of the entry
cloud Cloud information
provider Provider System
serviceDefinition Service Definition
interfaces Interfaces
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /authorization/mgmt/intercloud/{id}
The returned structure did not contain time information, provider and interface restrictions.

Delete an Intercloud rule by ID

Removes the Intercloud related authorization record specified by the ID path parameter.

Note: 4.1.2 version: DELETE /authorization/mgmt/intercloud/{id} Same as the new version.

Orchestrator

System Design Description Overview

The Orchestrator provides runtime (late) binding between Application Systems.

The primary purpose for the Orchestrator System is to provide Application Systems with orchestration information: where they need to connect to. The outcome of the "Orchestration Service" include rules that will tell the Application System what Service provider System(s) it should connect to and how (acting as a Service Consumer). Such orchestration rules include:

  • Accessibility information details of a Service provider (e.g network address and port),
  • Details of the Service instance within the provider System (e.g. base URL, IDD specification and other metadata),
  • Authorization-related information (e.g. access token and signature),
  • Additional information that is necessary for establishing connection.

This orchestration rule information can reach the given Application System (consumer) in two different ways: the System itself can request it ("pull") or the Orchestrator itself can update the System when it is needed ("push method"). However, in both cases, there shall be an underlying, hidden process ("orchestration process"), which ensures the consistence of state between the various Core Systems.

In G4.0, only the pull method is implemented and the Orchestrator shall negotiate with the other Core Systems while trying to facilitate the new service request (or trying to push a new status). This is necessary for the following cases and requirements (basically, when ad hoc, unsupervised connections are not allowed):

  • When accountability is required for all Systems in the Local Cloud: connections cannot be established without the knowledge, approval and logged orchestration events of the Core Systems ("central governance").
  • QoS and resource management reasons: ad hoc peer-to-peer connections cannot be allowed in certain managed networks and deployment scenarios. Every connection attempt shall be properly authorized and its QoS expectations (resource reservations) handled.
  • Inter-Cloud orchestration can only happen via negotiations between the two Core System sets. Ad hoc inter-cloud connections shall not be allowed in the Arrowhead framework.

In these cases, when the Orchestrator is the sole entry point to establishing new connections within the Local Cloud, Application Systems do not have the possibility to skip any of the control loops with all the appropriate Core Systems. When such security and safety concerns are not present, the orchestration process might be cut back or these interactions between Core Systems might be limited. Within G4.0, this is not the primary use case, but it is allowed. With the proper self-implemented (modified) and a self-compiled Orchestrator can fit the deployment best.

Therefore, the Orchestrator provides two core Services and may consume many other ones, but at least two -- again, depending on its deployment. This figure depicts the mandatory and optional interfaces of this System.

Overview of the Orchestrator

In here, the provided Services are:

  • Orchestration Service
  • OrchestrationStoreManagement Service

Meanwhile the consumed Services can vary, depending on the instantiation/installation of this System. For example, the Orchestrator can utilize the services of:

  • ServiceDiscovery Service from the ServiceRegistry,
  • AuthorizationControl Service from the Authorization System,
  • TokenGeneration Service from the Authorization System,
  • GlobalServiceDiscovery from the Gatekeeper,
  • Inter-CloudNegotiations from the Gatekeeper,
  • QoSVerify from the QoS Manager,
  • QoSReserve from the QoS Manager,
  • Logging services from other supporting Systems, e.g. Historian,
  • and any other service from Core Systems that are necessary to settle during orchestration.

The Orchestrator mainly consumes services from other Core Systems in order to fulfil its primary functionality: provide connection targets for Application Systems in a secure and resource managed manner -- hence build an SoS.

During this orchestration process the Orchestrator either facilitates a service request from an Application System or processes a system-of-systems (SoS) level choreography push from the Plant Description Engine ("Choreographer"). For the latter case, the Orchestrator System consumes the OrchestrationPush from affected Application Systems in order to deliver a renewed set of connection rules to them.

Within the Orchestrator, there is a database which captures design time bindings between Application Systems, the Orchestration Store. Operators of the Cloud and other System-of-Systems designer tools ("SoS Choreographers") are allowed to modify the rules stored in the Orchestration Store, other generic Application Systems are not.

The ServiceDiscovery Service is used to publish the Orchestration Service in the Service Registry. This Service is also used to query the Service Registry and fetch (metadata) information on other Application Systems.

The Services of the Authorization System can be used to verify access control and implement other security-related administration tasks.

The Services of the Gatekeeper can be utilized when inter-Cloud collaboration, servicing is required.

The Services of the QoS management System can be used to manage device, network and service-level Quality of Service agreements and configurations.

Orchestrator can be used in two ways. The first one uses predefined rules (coming from the Orchestrator Store DB) to find the appropriate providers for the consumer. The second option is the dynamic orchestration in which case the core service searches the whole local cloud (and maybe some other clouds) to find matching providers.

Store Orchestration:

  • requester system is mandatory,
  • requested service and all the other parameters are optional,
  • if requested service is not specified, then this service returns the top priority local provider of all services contained by the orchestrator store database for the requester system. if requested service is specified, then you have to define the service definition and exactly one interface (all other service requirements are optional). In this case, it returns all accessible providers from the orchestrator store database that provides the specified service via the specified interface to the specified consumer.

Dynamic Orchestration:

  • requester system is mandatory,
  • requested service is mandatory, but just the service definition part, all other parameters of the requested service are optional,
  • all other parameters are optional

Orchestration flags:

  • matchmaking: the service automatically selects exactly one provider from the appropriate providers (if any),
  • metadataSearch: query in the Service Registry uses metadata filtering,
  • onlyPreferred: the service filters the results with the specified provider list,
  • pingProviders: the service checks whether the returning providers are online and remove the unaccessible ones from the results,
  • overrideStore: Services uses dynamic orchestration if this flag is true, otherwise it uses the orchestration store,
  • enableInterCloud: the service can search another clouds for providers if none of the local cloud providers match the requirements,
  • triggerInterCloud: the service skipped the search in the local cloud and tries to find providers in other clouds instead.

Services and Use Cases

For the Orchestrator System, the primary scenario is to provide Application Systems with orchestration information upon request (Service Request). The outcome (Orchestration Response) include orchestration rules that will tell the Application System what service provider(s) it should connect to and how.

An alternative, secondary version of this scenario involves the same information, however, provided by a connection initialized by the Orchestrator, rather than the Application Service itself ("orchestration push"). This is used to relay changes made in the Orchestration Store to the Application Systems ("changes information exchange setup within the SoS").

Another scenario is when the Orchestration Store (that stores design time orchestration-related information) of the Orchestrator is being configured via an HMI or via the Plant Description Engine (SoS Choreographer) by the operators of the Local Cloud.

Use case 1: Service Request From Application System

Name Description
ID Orchestration Pull
Brief Description An Application System requests a Service
Primary Actors Service Consumer System
Secondary Actors - the other Core System instances of the Local Cloud
- the Core Systems instance of another Local Cloud (in case of inter-Cloud orchestration)
Preconditions -
Main Flow - The Application System requests orchestration.
- The Orchestrator System begins the orchestration process with the other Core Systems.
- The Orchestrator System responds to the Application System based on the request.
Postconditions -

Use case 2: Orchestration information pushed to Application System

Name Description
ID Orchestration Push
Brief Description The Orchestrator pushes new information on Application Systems
Primary Actors Orchestrator
Secondary Actors the other Core Systems instances of the Local Cloud
Preconditions Change in the Orchestration Store.
Main flow - The Orchestrator detects a change in the Orchestration Store.
- The Orchestrator begins the orchestration process with the other Core Systems for every change in the Store.
- The orchestrator pushes new connection rules to the Application Systems based on the new Store entry.
Postconditions -

Use case 3: Orchestration information pushed to Application System

Name Description
ID Orchestration Push
Brief Description The Orchestrator pushes new information on Application Systems
Primary Actors Orchestrator
Secondary Actors the other Core Systems instances of the Local Cloud
Preconditions Change in the Orchestration Store.
Main flow - The Orchestrator detects a change in the Orchestration Store.
- The Orchestrator begins the orchestration process with the other Core Systems for every change in the Store.
- The orchestrator pushes new connection rules to the Application Systems based on the new Store entry.
Postconditions -

Endpoints

The Orchestrator offers three types of endpoints. Client, Management and Private.

Swagger API documentation is available on: https://<host>:<port>
The base URL for the requests: http://<host>:<port>/orchestrator

Client endpoint description

Function URL subpath Method Input Output
Echo /echo GET - OK
Orchestration /orchestration POST ServiceRequestForm Orchestration Response
Start store Orchestration by ID /orchestration/{id} GET StoreEntryID Orchestration Response

Private endpoint description

These services can only be used by other core services, therefore they are not part of the public API.

Function URL subpath Method Input Output

Management Endpoint Description

There endpoints are mainly used by the Management Tool and Cloud Administrators.

Function URL subpath Method Input Output
Get all Store Entries /mgmt/store GET - StoreEntryList
Add Store Entries /mgmt/store POST StoreRules StoreEntryList
Get Store Entry by ID /mgmt/store/{id} GET StoreEntryID StoreEntry
Delete Store Entry by ID /mgmt/store/{id} DELETE StoreEntryID -
Get Entries by Consumer /mgmt/store/
all_by_consumer		 POST ConsumerRule StoreEntryList
Get Top Priority Entries /mgmt/store/
all_top_priority		 GET - StoreEntryList
Modify Priorities /mgmt/store/
modify_priorities		 POST PriorityList -

Removed Endpoints

The following services no longer exist:

  • GET /orchestrator/mgmt/store/default/{id}
  • PUT /orchestrator/mgmt/store/update/{id}
  • DELETE /orchestrator/mgmt/store/consumerId/{systemId}

Echo

GET /orchestrator/echo

Returns a "Got it" message with the purpose of testing the core service availability.

Note: 4.1.2 version: GET /orchestrator/orchestration It was basically the same with a slightly different return message

Orchestration

POST /orchestrator/orchestration

Initializes the orchestration process in which the Orchestrator Core System tries to find providers that match the specified requirements (and the consumer have right to use them).

ServiceRequestForm is the input

{
  "requesterSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "requestedService": {
    "serviceDefinitionRequirement": "string",
    "interfaceRequirements": [
      "string"
    ],
    "securityRequirements": [
      "NOT_SECURE", "CERTIFICATE", "TOKEN"
    ],
    "metadataRequirements": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "versionRequirement": 0,
    "maxVersionRequirement": 0,
   "minVersionRequirement": 0
  },
  "preferredProviders": [
    {
      "providerCloud": {
        "operator": "string",
        "name": "string"
      },
      "providerSystem": {
        "systemName": "string",
        "address": "string",
        "port": 0
      }
    }
  ],
  "orchestrationFlags": {
    "additionalProp1": true,
    "additionalProp2": true,
    "additionalProp3": true
  }
}
Field Description Mandatory
requesterSystem Requester System yes
requestedService Requested Service no
preferredProviders Preferred Providers no
orchestrationFlags Orchestration Flags no

Orchestrator can be used in two ways. The first one uses predefined rules (coming from the Orchestrator Store DB) to find the appropriate providers for the consumer. The second option is the dynamic orchestration in which case the core service searches the whole local cloud (and maybe some other clouds) to find matching providers.

Store Orchestration:

  • requester system is mandatory,
  • requested service and all the other parameters are optional,
  • if requested service is not specified, then this service returns the top priority local provider of all services contained by the orchestrator store database for the requester system. if requested service is specified, then you have to define the service definition and exactly one interface (all other service requirements are optional). In this case, it returns all accessible providers from the orchestrator store database that provides the specified service via the specified interface to the specified consumer.
Field Description Mandatory
requesterSystem Requester System yes
requestedService Requested Service no
preferredProviders Preferred Providers no
orchestrationFlags Orchestration Flags no

Dynamic Orchestration:

  • requester system is mandatory,
  • requested service is mandatory, but just the service definition part, all other parameters of the requested service are optional,
  • all other parameters are optional
Field Description Mandatory
requesterSystem Requester System yes
requestedService Requested Service yes
preferredProviders Preferred Providers no
orchestrationFlags Orchestration Flags no

Orchestration flags:

  • matchmaking: the service automatically selects exactly one provider from the appropriate providers (if any),
  • metadataSearch: query in the Service Registry uses metadata filtering,
  • onlyPreferred: the service filters the results with the specified provider list,
  • pingProviders: the service checks whether the returning providers are online and remove the unaccessible ones from the results,
  • overrideStore: Services uses dynamic orchestration if this flag is true, otherwise it uses the orchestration store,
  • enableInterCloud: the service can search another clouds for providers if none of the local cloud providers match the requirements,
  • triggerInterCloud: the service skipped the search in the local cloud and tries to find providers in other clouds instead.

Returns an Orchestration Response

{
  "response": [
    {
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "service": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceUri": "string",
      "secure": "TOKEN",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },  
      "interfaces": [
        {
          "id": 0,
          "createdAt": "string",
          "interfaceName": "string",
          "updatedAt": "string"
        }
      ],
      "version": 0,
      "authorizationTokens": {
        "interfaceName1": "token1",
        "interfaceName2": "token2"
      },
      "warnings": [
        "FROM_OTHER_CLOUD", "TTL_UNKNOWN"
      ]
    }
  ]
}
Field Description
resposne Array containing the data
provider Provider System
service Service
serviceUri URI of the Service
secure Security info
metadata Metadata
interfaces List of the interfaces the Service supports
version Version of the Service
authorizationTokens Authorization Tokens
warnings Warnings

Note: authorizationTokens object only appears if the provider requires token authentication, authorizationTokens is interface-specific

Note: warnings array can contains the following texts:

  • FROM_OTHER_CLOUD (if the provider is in an other cloud)
  • TTL_EXPIRED (the provider is no longer accessible)
  • TTL_EXPIRING (the provider will be inaccessible in a matter of minutes),
  • TTL_UNKNOWN (the provider does not specified expiration time)

Note: 4.1.2 version: POST /orchestrator/orchestration
It was basically the same, however security requirement was not available.
Orchestration activity diagram

Alt text

Start store Orchestration by ID

GET /orchestrator/rchestration/{id}

If the consumer knows its' ID, it can used this service as shortcut for store-based orchestration when the service returns the top priority local provider of all services contained by the orchestrator store database for the requester system (identified by the ID)

Returns an Orchestration Response

{
  "response": [
    {
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "service": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceUri": "string",
      "secure": "TOKEN",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },  
      "interfaces": [
        {
          "id": 0,
          "createdAt": "string",
          "interfaceName": "string",
          "updatedAt": "string"
        }
      ],
      "version": 0,
      "authorizationTokens": {
        "interfaceName1": "token1",
        "interfaceName2": "token2"
      },
      "warnings": [
        "FROM_OTHER_CLOUD", "TTL_UNKNOWN"
      ]
    }
  ]
}
Field Description
resposne Array containing the data
provider Provider System
service Service
serviceUri URI of the Service
secure Security info
metadata Metadata
interfaces List of the interfaces the Service supports
version Version of the Service
authorizationTokens Authorization Tokens
warnings Warnings

Note: authorizationTokens object only appears if the provider requires token authentication, authorizationTokens is interface-specific

Note: warnings array can contains the following texts:

  • FROM_OTHER_CLOUD (if the provider is in an other cloud)
  • TTL_EXPIRED (the provider is no longer accessible)
  • TTL_EXPIRING (the provider will be inaccessible in a matter of minutes),
  • TTL_UNKNOWN (the provider does not specified expiration time)
Store Orchestration activity diagram

Alt text

Get all Store Entries

GET /orchestrator/mgmt/store

Returns a list of orchestrator store rule records. If page and item_per_page are not defined, returns all records.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns a StoreEntryList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "foreign": true,
      "providerCloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": false,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceInterface": {
        "id": 0,
        "interfaceName": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "priority": 1,
      "attribute": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count Number of records found
data Array of data
id ID of the Store Entry
serviceDefinition Service Definition
consumerSystem Consumer System
foreign Provider System in Foreign Cloud
providerCloud Provider Cloud
providerSystem Provider System
serviceInterface Service Interface
priority Priority
metadata Metadata
attribute Attributes
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: Rules are a little stricter than before: the service interface is also part of it. But the defaultEntry flag is no longer supported; now, entries with priority 1 is considered as defaults.

Note: 4.1.2 version: GET /orchestrator/mgmt/store/all
This version always returned all records in an array of JSON objects. The objects did not contain any time information. Rules didn't depend on interface.

Add Store Entries

POST /orchestrator/mgmt/store

Creates Orchestrator Store records and returns the newly created records.

StoreRules is the input

[
  {
    "serviceDefinitionName": "string",
    "consumerSystemId": 0,
    "attribute": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "providerSystem": {
      "systemName": "string",
      "address": "string",
      "port": 0
    },
    "cloud": {
      "operator": "string",
      "name": "string"
    },
    "serviceInterfaceName": "string",
    "priority": 1
  }
]
Field Description Mandatory
serviceDefinitionName Service Definition yes
consumerSystemId Consumer System ID yes
attribute Attributes no
providerSystem Provider System yes
cloud Cloud yes
serviceInterfaceName Service Interface Name yes
priority Priority yes

Returns a StoreEntryList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "foreign": true,
      "providerCloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": false,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceInterface": {
        "id": 0,
        "interfaceName": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "priority": 1,
      "attribute": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count Number of records found
data Array of data
id ID of the Store Entry
serviceDefinition Service Definition
consumerSystem Consumer System
foreign Provider System in Foreign Cloud
providerCloud Provider Cloud
providerSystem Provider System
serviceInterface Service Interface
priority Priority
metadata Metadata
attribute Attributes
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: POST /orchestrator/mgmt/store<br/ > This version required whole JSON objects as consumer instead of id and didn't contains interface names. Also, it used defaultEntry flags.

Get Store Entry by ID

GET /orchestrator/mgmt/store/{id}

Returns the orchestrator store rule record specified by the ID path parameter.

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "consumerSystem": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "foreign": true,
  "providerCloud": {
    "id": 0,
    "operator": "string",
    "name": "string",
    "authenticationInfo": "string",
    "secure": true,
    "neighbor": true,
    "ownCloud": false,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "providerSystem": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceInterface": {
    "id": 0,
    "interfaceName": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "priority": 1,
  "attribute": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the Store Entry
serviceDefinition Service Definition
consumerSystem Consumer System
foreign Provider System in Foreign Cloud
providerCloud Provider Cloud
providerSystem Provider System
serviceInterface Service Interface
priority Priority
metadata Metadata
attribute Attributes
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /orchestrator/mgmt/store/{id}
The returned structure did not contain time information and interface names

Delete Store Entries by ID

DELETE /orchestrator/mgmt/store/{id}

Removes the Orchestrator Store rule record specified by the ID path parameter.

Note: 4.1.2 version: DELETE /orchestrator/mgmt/store/{id}
Same as the new version.

Get Entries by Consumer

GET /orchestrator/mgmt/store/all_by_consumer

Returns a list of Orchestrator Store rule records related to consumer, service definition and optionally service interface. If page and item_per_page are not defined, no paging is involved.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

ConsumerRule is the input

{
 "consumerSystemId": 0,
 "serviceDefinitionName": "string",
 "serviceInterfaceName": "string"
}
Field Description Mandatory
consumerSystemId ID of the Consumer yes
serviceDefinitionName Service Definition yes
serviceInterfaceName Service Interface no

Returns a StoreEntryList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "foreign": true,
      "providerCloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": false,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceInterface": {
        "id": 0,
        "interfaceName": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "priority": 1,
      "attribute": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count Number of records found
data Array of data
id ID of the Store Entry
serviceDefinition Service Definition
consumerSystem Consumer System
foreign Provider System in Foreign Cloud
providerCloud Provider Cloud
providerSystem Provider System
serviceInterface Service Interface
priority Priority
metadata Metadata
attribute Attributes
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: PUT /orchestrator/mgmt/store
This version always returned all matching records in an array of JSON objects. The objects did not contain any time information and filtering by interface name was not available.

Get Top Priority Entries

GET /orchestrator/mgmt/store/all_top_priority

Returns a list of orchestrator store rule records whose priority is 1. If page and item_per_page are not defined, no paging is involved.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

Returns a StoreEntryList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "foreign": true,
      "providerCloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": false,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceInterface": {
        "id": 0,
        "interfaceName": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "priority": 1,
      "attribute": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count Number of records found
data Array of data
id ID of the Store Entry
serviceDefinition Service Definition
consumerSystem Consumer System
foreign Provider System in Foreign Cloud
providerCloud Provider Cloud
providerSystem Provider System
serviceInterface Service Interface
priority Priority
metadata Metadata
attribute Attributes
createdAt Creation date of the entry
updatedAt When the entry was last updated

Note: 4.1.2 version: GET /orchestrator/mgmt/store/all_default
This version always returned all records where defaultEntry flag is true in an array of JSON objects. The objects did not contain any time information.

Modify Priorities

POST /orchestrator/mgmt/store/modify_priorities

Changes the priority field of the specified entries.

PriorityList is the input

{
  "priorityMap": {
    "{id1}": 1,
    "{id2}": 2,
    "{id3}": 3
 }
}
Field Description Mandatory
priorityMap Priority List yes

Note: The keys of the map are Orcherstrator store rule IDs, the values are the new priorities.

Note: 4.1.2 version: PUT /orchestrator/mgmt/store/priorities
Same as the new version

Event Handler

System Design Description Overview

placeholder

Services and Use Cases

placeholder

Publish Service Description Overview

placeholder

Endpoints

placeholder

Gatekeeper

System Design Description Overview

This supporting core system has the purpose of providing inter-Cloud servicing capabilities in the Arrowhead Framework by its following services:

  • Global Service Discovery (GSD)
  • Inter-Cloud Negotiation (ICN)

These Services are part of the inter-Cloud orchestration process, but the Gatekeeper is only available for the other core systems. Gatekeeper is the only one core system which has the functionality of discovering other Clouds via Relay systems. Neighbor Clouds and Relay systems are stored in the MySQL database of this module.
During the inter-Cloud orchestration, the Global Service Discovery is the first process which aims to collect the known clouds with providers serving the specified service. After GSD, the Inter Cloud Negotiation process steps in place with the purpose of establishing the way of collaboration. Working together with the Orchestrators of both Clouds, at the end a servicing instace can be created.

Alt text

Please follow this guide to setup the Arrowhead Gatekeeper and Gateway core systems: Gatekeeper & Gateway Setup Guide with ActiveMQ Relay

Services and Use Cases

Use case 1: Global Service Discovery request

Name Description
ID GSD-1
Brief Description The Gatekeeper is tasked to find a Service in other Local Clouds
Primary Actors Gatekeeper
Secondary Actors - Relays used by the Gatekeeper
- The Gatekeeper instances of another Clouds
Preconditions Orchestration process was started by an Application System.
Main Flow - The Orchestrator consumes the GSD Initialization Service of its local Gatekeeper.
- Gatekeeper collects the preferred or neighbor Clouds and one of its Relays.
- The Gatekeeper queries the other Gatekeepers via the Relays.
- These Gatekeepers verify whether they could facilitate this request or not.
- The requester Gatekeeper collects these answers and respond via the GSD Initialization Service to its Orchestrator
Postconditions The Orchestrator has a list of other Local Clouds that can provide the Service we are looking for.

Use case 2: Inter-Cloud Negotiation request

Name Description
ID ICN-1
Brief Description The Gatekeeper is tasked to start negotiating with another Cloud.
Primary Actors Gatekeeper
Secondary Actors - Relays used by the Gatekeeper
- The Gatekeeper instances of another Clouds
- The other Orchestrator from the second Cloud
Preconditions Orchestration process was started by an Application System. The GSD process has ended, the requester Orchestrator has chosen a partnering Cloud, where it wants to connect to.
Main Flow - The Orchestrator consumes the ICN Initialization Service of its local Gatekeeper.
- The Gatekeeper consumes the other Gatekeeper's ICN Proposal service via an Relay.
- The secondary Gatekeeper validates the AuthorizationControl and requests Orchestration from its own Orchestrator
- The secondary Orhestrator responds to the secondary Gatekeeper with an Orchestration result.
- The secondary Gatekeeper responds to the primary, requester Gatekeeper.
- Additional administrative tasks are executed (e.g. configuration of the Gateway modules)
- The primary, requester Orchestrator is receiving the response via the ICN initialization service.

Endpoints

Client endpoint description

Function URL subpath Method Input Output
Echo /echo GET - OK

Private endpoint description

Function URL subpath Method Input Output
Init GSD /gatekeeper/init_gsd POST GSDQueryForm GSDQueryResult
Init ICN /gatekeeper/init_icn POST ICNRequestForm ICNResult

Management endpoint description

Function URL subpath Method Input Output
Get all Cloud entries /mgmgt/clouds GET - CloudWithRelaysListResponse
Get Cloud by ID /mgmgt/clouds/{id} GET cloudId CloudWithRelaysResponse
Register Clouds /mgmgt/clouds POST CloudRequest list CloudWithRelaysListResponse
Update Cloud /mgmgt/clouds/{id} PUT CloudRequest CloudWithRelaysResponse
Assign Relays to Cloud /mgmgt/clouds/assign POST CloudRelaysAssignmentRequest CloudWithRelaysResponse
Delete Cloud /mgmgt/clouds/{id} DELETE cloudId -
Get all Relay entries /mgmgt/relays GET - RelayListResponse
Get Relay by ID /mgmgt/relays/{id} GET relayId RelayResponse
Get Relay by Address and Port /mgmgt/relays/{address}/{port} GET address, port RelayResponse
Register Relays /mgmgt/relays POST RelayRequest list RelayListResponse
Update Relay /mgmgt/relays/{id} PUT RelayRequest RelayResponse
Delete Relay /mgmgt/relays/{id} DELETE relayId -

Removed Endpoints

The following endpoints no longer exist:

  • GET /gatekeeper/mgmt/neighborhood/operator/{operator}/cloudname/{cloudName}
  • DELETE /gatekeeper/mgmt/neighborhood/operator/{operator}/cloudname/{cloudName}
  • GET /gatekeeper/mgmt/brokers/brokername/{brokerName}
  • GET /gatekeeper/mgmt/brokers/address/{address}

Echo

GET /gatekeeper/echo

Returns a "Got it" message with the purpose of testing the core service availability.

Init GSD

POST /gatekeeper/init_gsd

Returns the result of Global Service Discovery.

GSDQueryForm is the input

{
  "requestedService": {
	"serviceDefinitionRequirement": "string",
    "interfaceRequirements": [
      "string"
    ],
	"securityRequirements": [
      "NOT_SECURE"
    ],
	"versionRequirement": 0,
    "maxVersionRequirement": 0,
    "minVersionRequirement": 0,
    "pingProviders": true,
	"metadataRequirements": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "preferredClouds": [
    {
	  "name": "string",
      "operator": "string",
	  "neighbor": true,
      "secure": true,
      "authenticationInfo": "string",
      "gatekeeperRelayIds": [
        0
      ],
      "gatewayRelayIds": [
        0
      ]
    }
  ]
}
Field Description Mandatory
requestedService Object describes the requested service yes
serviceDefinitionRequirement Service Definition yes
interfaceRequirements List of interfaces no
securityRequirements List of required security levels no
versionRequirement Version of the Service no
maxVersionRequirement Maximum version of the Service no
minVersionRequirement Minimum version of the Service no
pingProviders Whether or not the providers should be pinged no
metadataRequirements Metadata no
preferredClouds List of preferred clouds no

GSDQueryResult is the output

{
  "results": [
    {
      "providerCloud": {
	    "id": 0,
		"name": "string",
		"operator": "string",
        "authenticationInfo": "string",        
        "neighbor": true,        
        "ownCloud": true,
        "secure": true,
		"createdAt": "string",
        "updatedAt": "string"
      },
	  "requiredServiceDefinition": "string",
	  "availableInterfaces": [
        "string"
      ],
      "serviceMetadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
	   "numOfProviders": 0
    }
  ],
  "unsuccessfulRequests": 0
}
Field Description
results List of result objects
providerCloud Cloud where the result coming from
requiredServiceDefinition Service Definition
availableInterfaces List of available interfaces
serviceMetadata Metadata
numOfProviders Number of providers serving the service within the cloud
unsuccessfulRequests Number of clouds not responded

Init ICN

POST /gatekeeper/init_icn

Returns the result of Inter-Cloud Negotiation.

ICNRequestForm is the input

{
  "targetCloudId": 0,
  "requestedService": {
    "serviceDefinitionRequirement": "string",
    "interfaceRequirements": [
      "string"
    ],
    "securityRequirements": [
      "NOT_SECURE"
    ],
	"versionRequirement": 0,
    "maxVersionRequirement": 0,
    "minVersionRequirement": 0,
    "pingProviders": true,	
	"metadataRequirements": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "preferredSystems": [
    {
      "systemName": "string",
	  "address": "string",
	  "port": 0,
      "authenticationInfo": "string"
    }
  ],
  "requesterSystem": {
	"systemName": "string",
    "address": "string",
	"port": 0,
    "authenticationInfo": "string"
  },
  "negotiationFlags": {
    "additionalProp1": true,
    "additionalProp2": true,
    "additionalProp3": true
  }
}
Field Description Mandatory
targetCloudId Local ID of the target cloud yes
requestedService Object describes the requested service yes
serviceDefinitionRequirement Service Definition yes
interfaceRequirements List of interfaces no
securityRequirements List of required security levels no
versionRequirement Version of the Service no
maxVersionRequirement Maximum version of the Service no
minVersionRequirement Minimum version of the Service no
pingProviders Whether or not the providers should be pinged no
metadataRequirements Metadata no
preferredSystems List of perferred systems no
requesterSystem Requester Cloud details (Own cloud) yes
negotiationFlags Orchestration flags no

ICNResult is the output

{
  "response": [
    {
      "service": {
	    "id": 0,       
        "serviceDefinition": "string",
		"createdAt": "string", 
        "updatedAt": "string"
      },
	  "serviceUri": "string",
	  "provider": {
	    "id": 0,
		"systemName": "string",
        "address": "string",
		"port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",        
        "updatedAt": "string"
      },
	  "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
		  "createdAt": "string",
          "updatedAt": "string"
        }
      ],      
      "secure": "NOT_SECURE",     
      "version": 0,
	  "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
	  "authorizationTokens": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "warnings": [
        "FROM_OTHER_CLOUD"
      ]
    }
  ]
}
Field Description
results List of result objects
service Required service
serviceUri URI of the service
provider Provider details
interfaces List of available interfaces
secure Level of security
version Version number
metadata Service metadata
authorizationTokens Authorization Tokens per interfaces
warnings Warnings

Get all Cloud entries

GET /gatekeeper/mgmgt/clouds

Returns Cloud entries by the given paging parameters. If page and item_per_page are not defined, no paging is involved.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

CloudWithRelaysListRespone is the output.

{
  "count": 0,
  "data": [
    {
	  "id": 0,
      "name": "string",
	  "operator": "string",
      "neighbor": true,      
      "ownCloud": true,
      "secure": true,
      "authenticationInfo": "string",
      "createdAt": "string",
	  "updatedAt": "string",
      "gatekeeperRelays": [
        {
          "id": 0,
		  "address": "string",
          "port": 0,		            
          "exclusive": true,
          "secure": true,
          "type": "GATEKEEPER_RELAY",
		  "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "gatewayRelays": [
        {
          "id": 0,
		  "address": "string",
          "port": 0,		            
          "exclusive": true,
          "secure": true,
          "type": "GATEWAY_RELAY",
		  "createdAt": "string",
          "updatedAt": "string"
        }
      ]
    }
  ]
}
Field Description
count Number of record found
data Array of data
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
ownCloud Whether or not it is the own Cloud
secure Whether or not it is a secured Cloud/Relay
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelays List of Relays uesd by Gatekeeper
gatewayRelays List of Relays uesd by Gateway
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Get Cloud by ID

GET /gatekeeper/mgmgt/clouds/{id}

Returns the Cloud Entry specified by the ID path parameter.

CloudWithRelaysResponse is the output.

{
  "id": 0,
  "name": "string",
  "operator": "string",
  "neighbor": true,      
  "ownCloud": true,
  "secure": true,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "gatekeeperRelays": [
      {
       "id": 0,
       "address": "string",
       "port": 0,		            
       "exclusive": true,
       "secure": true,
       "type": "GATEKEEPER_RELAY",
       "createdAt": "string",
       "updatedAt": "string"
      }
    ],
    "gatewayRelays": [
      {
        "id": 0,
	"address": "string",
        "port": 0,		            
        "exclusive": true,
        "secure": true,
        "type": "GATEWAY_RELAY",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
}
Field Description
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
ownCloud Whether or not it is the own Cloud
secure Whether or not it is a secured Cloud/Relay
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelays List of Relays used by Gatekeeper
gatewayRelays List of Relays used by Gateway
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Register Clouds

POST /gatekeeper/mgmgt/clouds

Returns created Cloud entries.

CloudRequest list is the input.

[
  {   
    "name": "string",
    "operator": "string",
    "neighbor": true,    
    "secure": true,
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  }
]
Field Description
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
secure Whether or not it is a secured Cloud
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelayIds List of Relay IDs used by Gatekeeper
gatewayRelayIds List of Relay IDs used by Gateway

CloudWithRelaysListResponse is the output.

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "name": "string",
      "operator": "string",
      "neighbor": true,      
      "ownCloud": true,
      "secure": true,
      "authenticationInfo": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "gatekeeperRelays": [
        {
          "id": 0,
	  "address": "string",
          "port": 0,		            
          "exclusive": true,
          "secure": true,
          "type": "GATEKEEPER_RELAY",
	  "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "gatewayRelays": [
        {
          "id": 0,
	  "address": "string",
          "port": 0,		            
          "exclusive": true,
          "secure": true,
          "type": "GATEWAY_RELAY",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ]
    }
  ]
}
Field Description
count Number of record found
data Array of data
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
ownCloud Whether or not it is the own Cloud
secure Whether or not it is a secured Cloud/Relay
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelays List of Relays uesd by Gatekeeper
gatewayRelays List of Relays uesd by Gateway
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Update Cloud

PUT /gatekeeper/mgmgt/clouds/{id}

Returns updated Cloud entry specified by the ID path parameter.

CloudRequest is the input.

{
  "name": "string",
  "operator": "string",
  "neighbor": true,
  "secure": true,
  "authenticationInfo": "string",
  "gatekeeperRelayIds": [
    0
  ],
  "gatewayRelayIds": [
    0
  ]
}
Field Description
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
secure Whether or not it is a secured Cloud
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelayIds List of Relay IDs used by Gatekeeper
gatewayRelayIds List of Relay IDs used by Gateway

CloudWithRelaysResponse is the output.

{
  "id": 0,
  "name": "string",
  "operator": "string",
  "neighbor": true,      
  "ownCloud": true,
  "secure": true,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "gatekeeperRelays": [
      {
       "id": 0,
       "address": "string",
       "port": 0,		            
       "exclusive": true,
       "secure": true,
       "type": "GATEKEEPER_RELAY",
       "createdAt": "string",
       "updatedAt": "string"
      }
    ],
    "gatewayRelays": [
      {
        "id": 0,
	"address": "string",
        "port": 0,		            
        "exclusive": true,
        "secure": true,
        "type": "GATEWAY_RELAY",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
}
Field Description
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
ownCloud Whether or not it is the own Cloud
secure Whether or not it is a secured Cloud/Relay
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelays List of Relays uesd by Gatekeeper
gatewayRelays List of Relays uesd by Gateway
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Assign Relays to Cloud

POST /gatekeeper/mgmgt/clouds/assign

Returns updated Cloud entry.

CloudRelaysAssignmentRequest is the input.

{
  "cloudId": 0,
  "gatekeeperRelayIds": [
    0
  ],
  "gatewayRelayIds": [
    0
  ]
}
Field Description
cloudId ID of the cloud
gatekeeperRelayIds List of Relay IDs used by Gatekeeper
gatewayRelayIds List of Relay IDs used by Gateway

CloudWithRelaysResponse is the output.

{
  "id": 0,
  "name": "string",
  "operator": "string",
  "neighbor": true,      
  "ownCloud": true,
  "secure": true,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "gatekeeperRelays": [
      {
       "id": 0,
       "address": "string",
       "port": 0,		            
       "exclusive": true,
       "secure": true,
       "type": "GATEKEEPER_RELAY",
       "createdAt": "string",
       "updatedAt": "string"
      }
    ],
    "gatewayRelays": [
      {
        "id": 0,
	"address": "string",
        "port": 0,		            
        "exclusive": true,
        "secure": true,
        "type": "GATEWAY_RELAY",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
}
Field Description
name Name of the cloud
operator Operator of the cloud
neighbor Whether or not it is a neighbor Cloud
ownCloud Whether or not it is the own Cloud
secure Whether or not it is a secured Cloud/Relay
authenticationInfo Base64 encoded public key of the Cloud
gatekeeperRelays List of Relays used by Gatekeeper
gatewayRelays List of Relays used by Gateway
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Delete Cloud

DELETE /gatekeeper/mgmgt/clouds/{id}

Remove requested Cloud entry

Get all Relay entries

GET /gatekeeper/mgmgt/relays

Returns Relay entries by the given paging parameters. If page and item_per_page are not defined, no paging is involved.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no
sort_field sorts by the given column no
direction direction of sorting no

Note: Default value for sort_field is id. All possible values are:

  • id
  • createdAt
  • updatedAt

Note: Default value for direction is ASC. All possible values are:

  • ASC
  • DESC

RelayListResponse is the output.

{
  "count": 0,
  "data": [
    {      
      "id": 0,
      "address": "string",
      "port": 0,
      "exclusive": true,
      "secure": true,
      "type": "GATEKEEPER_RELAY",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count Number of record found
data Array of data
id ID of the Relay
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Get Relay by ID

GET /gatekeeper/mgmgt/relays/{id}

Returns the Relay Entry specified by the ID path parameter.

RelayResponse is the output.

{      
  "id": 0,
  "address": "string",
  "port": 0,
  "exclusive": true,
  "secure": true,
  "type": "GATEKEEPER_RELAY",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the Relay
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Get Relay by Address and Port

GET /gatekeeper/mgmgt/relays/{address}/{port}

Returns the Relay Entry specified by the address and port path parameter.

RelayResponse is the output.

{      
  "id": 0,
  "address": "string",
  "port": 0,
  "exclusive": true,
  "secure": true,
  "type": "GATEKEEPER_RELAY",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the Relay
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Register Relays

POST /gatekeeper/mgmgt/relays

RelayRequest list is the input

[
 {      
  "address": "string",
  "port": 0,
  "exclusive": true,
  "secure": true,
  "type": "GATEKEEPER_RELAY",
  "createdAt": "string",
  "updatedAt": "string"
 }
]
Field Description
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

RelayListResponse is the output.

{
  "count": 0,
  "data": [
    {      
      "id": 0,
      "address": "string",
      "port": 0,
      "exclusive": true,
      "secure": true,
      "type": "GATEKEEPER_RELAY",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
Field Description
count Number of record found
data Array of data
id ID of the Relay
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Update Relay

PUT /gatekeeper/mgmgt/relays/{id}

Returns updated Relay entry specified by the ID path parameter.

RelayRequest is the input.

{      
  "address": "string",
  "port": 0,
  "exclusive": true,
  "secure": true,
  "type": "GATEKEEPER_RELAY",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

RelayResponse is the output.

{      
  "id": 0,
  "address": "string",
  "port": 0,
  "exclusive": true,
  "secure": true,
  "type": "GATEKEEPER_RELAY",
  "createdAt": "string",
  "updatedAt": "string"
}
Field Description
id ID of the Relay
address Host of the Relay
port Port of the Relay
exclusive Whether or not is is a not public Relay
secure Whether or not it is a secured Relay
type Type of the Relay (Possible values: 'GENERAL_RELAY, 'GATEKEEPER_RELAY', 'GATEWAY_RELAY')

Delete Relay

DELETE /gatekeeper/mgmgt/relays/{id}

Remove requested Relay entry.

Gateway

System Design Description Overview

This supporting core system has the purpose of establishing a secured datapath - if required - between a consumer and a provider located in different clouds by its following services:

  • Connect to Consumer
  • Connect to Provider

These Services are part of the Inter-Cloud Negotiation (ICN) process initiated by the requester cloud's Gatekeeper. During the ICN process, when a Gateway is required by one of the cloud, then the Gatekeepers in both cloud establish a new datapath to their application systems and ensure the data exchange via a Relay system.

Alt text

Please follow this guide to setup the Arrowhead Gatekeeper and Gateway core systems: Gatekeeper & Gateway Setup Guide with ActiveMQ Relay

Services and Use Cases

Use case 1: Connect to Consumer

Name Description
ID Connect-To-Consumer
Brief Description The Gateway is tasked to connect to the Consumer and mediate between the Relay and the Consumer.
Primary Actors Gatekeeper
Secondary Actors - Arrowhead compliant ActiveMQ Relay
Preconditions Inter-Cloud orchestration process was started by a consuming Application System.
Main Flow - The Gatekeeper sends a ConnectToConsumerRequest to the Gateway.
- The Gateway internally creates a new ActiveSession object.
- The Gateway starts a new thread.
- The Gateway creates a sslServerSocket.
- The Consumer connects to the port of the serverSocket.
- The Gateway gets the request from the Consumer through the SSLSocket forwards it to the Relay.
- The Gateway gets the response from the Provider via the Relay, decrypts and forwards it to the Consumer through the socket.
- The Gateway checks the control messages from the Relay and if a "close" message is received, than close the session.

Use case 2: Connect to Provider

Name Description
ID Connect-To-Provider
Brief Description The Gateway is tasked to connect to the Provider and mediate between the Relay and the Provider.
Primary Actors Gatekeeper
Secondary Actors - Arrowhead compliant ActiveMQ Relay
Preconditions Inter-Cloud orchestration process was started by a consuming Application System.
Main Flow - The Gatekeeper sends a ConnectToProviderRequest to the Gateway.
- The Gateway internally creates a new ActiveSession object with new queues for a choosen Relay.
- The Gateway starts a new thread.
- The Gateway creates a sslServerSocket.
- The Gateway gets the request from the Consumer through the Relay.
- The Gateway gets the response from the Provider via the SSLSocket, then encrypts and forwards it to the Relay.
- The Gateway checks the control messages from the Relay and if a "close" message is received, than close the session.

Endpoints

Client endpoint description

Function URL subpath Method Input Output
Echo /echo GET - OK

Private endpoint description

Function URL subpath Method Input Output
Connect To Consumer /connect_consumer POST GatewayConsumerConnectionRequest Server Port number
Connect To Provider /connect_provider POST GatewayProviderConnectionRequest GatewayProviderConnectionResponse
Get Public Key /publickey GET - Public Key string

Management endpoint description

Function URL subpath Method Input Output
Get Active Sessions /mgmgt/sessions GET - ActiveSessionList
Close Session /mgmgt/sessions/close POST ActiveSession OK

Echo

GET /gateway/echo

Returns a "Got it" message with the purpose of testing the core service availability.

Connect To Consumer

POST /gateway/connect_consumer

Creates a ServerSocket between the given Relay and Consumer and return the ServerSocket port.

GatewayConsumerConnectionRequest is the input.

{
  "consumer": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"    
  },
  "consumerCloud": {    
    "name": "string",
    "operator": "string",
    "neighbor": true,
    "secure": true,
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  },
  "provider": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "providerCloud": {
    "name": "string",
    "operator": "string",
    "neighbor": true,
    "secure": true,
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  },
  "providerGWPublicKey": "string",
  "peerName": "string",
  "queueId": "string",
  "relay": {
    "address": "string",
    "port": 0,
    "exclusive": true,
    "secure": true,
    "type": "string"
  },
  "serviceDefinition": "string"
}
Field Description
consumer Consumer Application System
consumerCloud Cloud of Consumer Application System
provider Provider Application System
providerCloud Cloud of Provider Application System
providerGWPublicKey Base64 encoded public key of provider cloud's Gateway
peerName Server Common Name of provider cloud's Gateway
queueId ID of the message queue in the Relay created by the provider
relay Messaging Relay system
serviceDefinition Definition of the service.

Connect To Provider

POST /gateway/connect_provider

Creates a Socket and Message queue between the given Relay and Provider and returns the necessary connection information.

GatewayProviderConnectionRequest is the input.

{
  "consumer": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"    
  },
  "consumerCloud": {    
    "name": "string",
    "operator": "string",
    "neighbor": true,
    "secure": true,
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  },
  "provider": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "providerCloud": {
    "name": "string",
    "operator": "string",
    "neighbor": true,
    "secure": true,
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  },
  "consumerGWPublicKey": "string",
  "relay": {
    "address": "string",
    "port": 0,
    "exclusive": true,
    "secure": true,
    "type": "string"
  },
  "serviceDefinition": "string"
}
Field Description
consumer Consumer Application System
consumerCloud Cloud of Consumer Application System
provider Provider Application System
providerCloud Cloud of Provider Application System
consumerGWPublicKey Base64 encoded public key of consumer cloud's Gateway
relay Messaging Relay system
serviceDefinition Definition of the service.

GatewayProviderConnectionResponse is the output.

{
  "peerName": "string",
  "queueId": "string",
  "providerGWPublicKey": "string"  
}
Field Description
peerName Server Common Name of provider cloud's Gateway
queueId ID of the message queue in the Relay created by the provider
providerGWPublicKey Base64 encoded public key of provider cloud's Gateway

Get Public Key

GET /gateway/publickey

Returns the public key of the Gateway core service as a Base64 encoded text.

Get Active Sessions

GET /gateway/mgmgt/sessions

Returns active Gateway sessions by the given paging parameters. If page and item_per_page are not defined, no paging is involved.

Query params:

Field Description Mandatory
page zero based page index no
item_per_page maximum number of items returned no

ActiveSessionList is the output.

{
  "count": 0,
  "data": [
    {
      "queueId": "string",
	  "peerName": "string",
	  "consumer": {
        "systemName": "string",
		"address": "string",
        "port": 0,
		"authenticationInfo": "string"        
      },
      "consumerCloud": {
        "name": "string",
		"operator": "string",
		"authenticationInfo": "string",        
        "neighbor": true,        
        "secure": true,
		"gatekeeperRelayIds": [
          0
        ],
        "gatewayRelayIds": [
          0
        ]
      },      
      "provider": {
        "systemName": "string",
		"address": "string",
        "port": 0,
		"authenticationInfo": "string"
      },
      "providerCloud": {
        "name": "string",
		"operator": "string",
		"authenticationInfo": "string",        
        "neighbor": true,        
        "secure": true,
		"gatekeeperRelayIds": [
          0
        ],
        "gatewayRelayIds": [
          0
        ]
      },
	  "serviceDefinition": "string",
      "relay": {
        "address": "string",
		"port": 0,
        "exclusive": true,        
        "secure": true,
        "type": "GATEWAY_RELAY"
      },
      "requestQueue": "string",
	  "requestControlQueue": "string",
      "responseQueue": "string",
      "responseControlQueue": "string",      
      "sessionStartedAt": "string",
	  "consumerServerSocketPort": 0
    }
  ]
}
Field Description
count Number of record found
data Array of data
queueId ID of the message queue in the Relay created by the provider
peerName Server Common Name of provider cloud's Gateway
consumer Consumer Application System
consumerCloud Cloud of Consumer Application System
provider Provider Application System
providerCloud Cloud of Provider Application System
serviceDefinition Definition of the service.
relay Messaging Relay system
requestQueue request messaging queue through the the Relay
requestControlQueue control queue of request messaging through the the Relay
responseQueue response messaging queue through the the Relay
responseControlQueue control queue of response messaging through the the Relay
sessionStartedAt Time stamp of session start
consumerServerSocketPort Port number delegated to consumer connection

Close Session

POST /gateway/mgmgt/sessions/close

Closing the requested active gateway session.

ActiveSession is the output.

{
  "queueId": "string",
  "peerName": "string",
	"consumer": {
    "systemName": "string",
	"address": "string",
    "port": 0,
	"authenticationInfo": "string"        
  },
  "consumerCloud": {
    "name": "string",
	"operator": "string",
	"authenticationInfo": "string",        
    "neighbor": true,        
    "secure": true,
	"gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  },      
  "provider": {
    "systemName": "string",
	"address": "string",
    "port": 0,
	"authenticationInfo": "string"
  },
  "providerCloud": {
    "name": "string",
	"operator": "string",
	"authenticationInfo": "string",        
    "neighbor": true,        
    "secure": true,
	"gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ]
  },
  "serviceDefinition": "string",
  "relay": {
    "address": "string",
	"port": 0,
    "exclusive": true,        
    "secure": true,
    "type": "GATEWAY_RELAY"
  },
  "requestQueue": "string",
  "requestControlQueue": "string",
  "responseQueue": "string",
  "responseControlQueue": "string",      
  "sessionStartedAt": "string",
  "consumerServerSocketPort": 0
}
Field Description
queueId ID of the message queue in the Relay created by the provider
peerName Server Common Name of provider cloud's Gateway
consumer Consumer Application System
consumerCloud Cloud of Consumer Application System
provider Provider Application System
providerCloud Cloud of Provider Application System
serviceDefinition Definition of the service.
relay Messaging Relay system
requestQueue request messaging queue through the the Relay
requestControlQueue control queue of request messaging through the the Relay
responseQueue response messaging queue through the the Relay
responseControlQueue control queue of response messaging through the the Relay
sessionStartedAt Time stamp of session start