DS Service Registry User Guide

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

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:

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

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_name>/<service_id>/alive : (Retained message) The body contains service description of alive service

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

Examples

vhost for Service Registry: serviceregistry_vhost

mosquitto_pub -h dataspine.efpf.linksmart.eu -p 8883 -u 'serviceregistry_vhost:username' -P 'password' -t 'tests/test1' -m 'test1' --cafile /c/Users/user1/Downloads/cacert-2020-07-22.pem

mosquitto_sub -h dataspine.efpf.linksmart.eu -p 8883 -u 'serviceregistry_vhost:username' -P 'password' -t 'tests/test1' --cafile /c/Users/user1/Downloads/cacert-2020-07-22.pem

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

Previous