DS Service Registry User Guide

Connection Details

To be replaced with the Production environment connection details:

Environment Component URL Port Description
Development HTTP REST API https://efpf-security-portal.salzburgresearch.at/apis/sr/ Secure API exposed through API Security Gateway
Development MQTT Service Status Announcements API dataspine.efpf.linksmart.eu 8883 Available through Data Spine Message Bus (RabbitMQ) in vhost serviceregistry_vhost over topics sr/v3/announcement/<service type>/<service Id>/alive and sr/v3/announcement/<service type>/<service Id>/dead

Prerequisites to accessing the Service Registry

  • Access to the shared, cloud-native instance of the Data Spine (DS) Service Registry is secured using the EFPF Security Portal (EFS).
  • As a prerequisite, you must have an EFPF user account ( User Guide 101), and obtain an access token for accessing the DS Service Registry.
  • You would need the efpf_basic role to view the services registered in the DS Service Registry and the efpf_sr_admin role to register/update your services.
  • Obtain the access token from the EFS as given below (For the latest documentation on getting a token, see the API Security Gateway and EFS documentation):
curl --location --request POST 'https://ds-test.smecluster.com/auth/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=apisix' \
--data-urlencode 'client_secret=replace_this_with_apisix_client_secret' \
--data-urlencode 'username=replace_this_with_your_email_id@example.org' \
--data-urlencode 'password=replace_this_with_your_password'

To get a token for accessing the Service Registry, please see the API Security Gateway and EFS documentation.

Data Model and Schema

The following diagram shows the data model of Service Registry (SR):

Service Registry Class Diagram

The attributes are described below:

Catalog object consists of:

  • id: unique id of the catalog
  • description: a friendly name or description of the service
  • services: an array of Service objects
  • page: the current page in catalog
  • per_page: number of items in each page
  • total: total number of registered services

Service object consists of:

  • id: unique id of service
  • type: the functional type of the service, preferably in the form <platform>.<service-type>. E.g., “composition.marketplace-service”
  • title: human-readable name of the service
  • description: human-readable description of the service
  • meta: a hash-map for optional meta-information

SR schema extension (optional): If you are registering an asynchronous (Pub/Sub) service such as a Factory Connector or an IoT Gateway and want to include information such as the location, manufacturer, etc. in the service description object, you can include the following template in this meta object while registering your service:

...
"meta": {
    "async": {
        "location": {
            "description": "string",
            "latitude": "string",
            "longitude": "string"
        },
        "manufacturer": "string"
    }
}
...
  • apis: an array of API objects specifying the service’s APIs
  • doc: URL to service documentation
  • ttl: time after which the service should be removed from the catalog, unless it is updated within the timeframe.
  • createdAt: RFC3339 time of service creation
  • updatedAt: RFC3339 time in which the service was lastly updated
  • expiresAt: RFC3339 time in which the service expires and is removed from the catalog (only if TTL is set)

API object consists of:

  • id: unique id of the API
  • title: human-readable name of the API
  • description: human-readable description of the API
  • protocol: the communication protocol used by the API (E.g., HTTP, MQTT, etc.)
  • url: URL to the server/target host (E.g., https://services.example.com, tcp://broker.example.com:1883, etc.) as defined by ‘Server Object’ in OpenAPI/AsyncAPI specifications
  • spec: the specification of the API as per the Open API Specification (Swagger) standard for synchronous (Request-Response) services or the AsyncAPI Specification standard for asynchronous (PubSub) services
  • meta: a hash-map for optional meta-information

SR schema extension (optional): If your service’s API is already secured and therefore, you want to skip the unnecessary creation of a secure proxy route/endpoint in the API Security Gateway (APISIX), you can use the createSecureProxy attribute in the API.meta object as follows:

...
"meta": {
    "dataspine": {
        "createSecureProxy": false
    }
}
...

Spec object consists of:

  • mediaType: The media type for the spec URL below
    1. For OpenAPI/Swagger Spec: application/vnd.oai.openapi;version=3.0 (YAML variant) or application/vnd.oai.openapi+json;version=3.0 (JSON only variant)
    2. For AsyncAPI Spec: application/vnd.aai.asyncapi;version=2.0.0 or application/vnd.aai.asyncapi+yaml;version=2.0.0 (YAML variant) or application/vnd.aai.asyncapi+json;version=2.0.0 (JSON only variant)
  • url: URL to external spec document
  • schema: the JSON object for the spec can be added here in case if the external document is not available. In case both are present, the spec in the URL takes precedence

HTTP REST API

Visit the Swagger UI for the OpenAPI Specifications

MQTT Service Status Announcements API

Service Registry announces the service registration status via MQTT using retain messages.

The message topics follow following patterns:

<topic_prefix>/<service_type>/<service_id>/alive : (Retained message) The body contains service description of alive service

<topic_prefix>/<service_type>/<service_id>/dead : (Not retained message) The body contains service description of the ‘dead’ service

The retained messages are removed whenever service de-registers.

The topic prefix is configured as part of server configuration. The default topic prefix is sr/v3/announcement/.

The Async API Spec for this API can be found here. The Async API Playground can be used to see a visual representation of this API Spec.

Example

vhost for Service Registry: serviceregistry_vhost

mosquitto_sub -h dataspine.efpf.linksmart.eu -p 8883 -u 'serviceregistry_vhost:username' -P 'password' -t 'sr/v3/announcement/efpf.example/example-service-id/alive' --cafile /c/Users/user1/Downloads/cacert-2020-07-22.pem

You can download the CA certificates bundle extracted from Mozilla (cacert-2020-07-22.pem) here: https://curl.haxx.se/docs/caextract.html

Versioning

API version is based on semver. The version is included as a parameter to the MIME type of all HTTP responses:

application/json;version=X.X.X

Data Spine Service Registry Documentation

Previous
Next