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.

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

1. Quick Start Guide
2. Migration Guide 4.1.2 -> 4.1.3
3. How to Contribute
4. Documentation
   1. Service Registry
      • System Design Description Overview
      • Services and Use Cases
      • Security
      • Endpoints
        • Client
        • Private
        • Management
        • Removed Endpoints
   2. Authorization
      • System Design Description Overview
      • Services and Use Cases
      • Service Description Overview
      • Endpoints
        • Client
        • Private
        • Management
        • Removed Endpoints

Placeholder

The project has the following dependencies:

• JRE/JDK 11 Download from here
• Maven 3.5+ Download from here | Install guide
• MySQL server 5.7+ (other SQL databases can work with Hibernate ORM, but the common module pom.xml has to include the appropriate connector dependency to use them)

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

Run the MySQL script which is in the scripts folder. If you won't run this script first, the project won't build.

cd core-java-spring

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

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

• 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

Wait until servers start...

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

Swagger with API documentation is available in the root route.

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.

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:

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

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

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

Store based orchestration is available for now.

• /mgmt/store - data structure changed

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.

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. :)

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.

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

Join our developer team on Slack. Write an email to szvetlin@aitia.ai for an invite.

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.

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.

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.

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

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

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

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

GET /serviceregistry/echo

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

Note: 4.1.2 version: GET /serviceregistry

POST /serviceregistry/query

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

{
 "serviceDefinitionRequirement": "string",
 "interfaceRequirements": [
   "string"
 ],
 "securityRequirements": [
   "NOT_SECURE"
 ],
 "metadataRequirements": {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
 },
 "versionRequirement": 0,
 "maxVersionRequirement": 0,
 "minVersionRequirement": 0,
 "pingProviders": true
}

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

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.

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

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

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:

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

POST /serviceregistry/query/system

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

GET /serviceregistry/system/{id}

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

GET /serviceregistry/mgmt

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

Query params:

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

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

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

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

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 /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"
}

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.

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

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

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.

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

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

Note: 4.1.2 version: Not existed

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 /serviceregistry/mgmt/grouped

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

• autoCompleteData
• servicesGroupedByServiceDefinitionAndInterface
• servicesGroupedBySystems

{
  "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"
      }
    ]
  },
  "servicesGroupedByServiceDefinitionAndInterface": [
    {
      "serviceDefinitionId": 0,
      "serviceDefinition": "string",
      "interfaceName": "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"
        }
      ]
    }
  ]
}

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:

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
}

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 /serviceregistry/mgmt/services

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

Query params:

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

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

POST /serviceregistry/mgmt/services

Creates service definition record and returns the newly created record.

{
  "serviceDefinition": "string"
}

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

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

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.

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

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

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.

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

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: Not existed

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 /serviceregistry/mgmt/systems

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

Query params:

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

{
  "data": [
    {
      "id": 0,
      "systemName": "string",
      "address": "string",
      "port": 0,
      "authenticationInfo": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}

POST /serviceregistry/mgmt/systems

Creates a System record and returns the newly created record.

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

GET /serviceregistry/systems/{id}

Returns the System record specified by the ID path parameter.

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

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

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

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

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

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: Not existed

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.

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.

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)

Figure 1. Authorization crosscheck during orchestration process

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.

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

<a name="authorization_endpoints_private />

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

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

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}

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

POST /authorization/intercloud/check

TODO

POST /authorization/intracloud/check

TODO

POST /authorization/token

TODO

GET /authorization/mgmt/intracloud

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

POST /authorization/mgmt/intracloud

Creates Intracloud authorization rules and returns the newly created rules.

<a name="datastructures_intracloud_rule"_form />

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.

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

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 /authorization/mgmt/intracloud/{id}

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

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

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 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:

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

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

POST /authorization/mgmt/intercloud

Creates Intercloud authorization rules and returns the newly created rules.

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

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

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

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

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.