DS Service Registry User Guide

Connection Details

The Production environment will be available soon

Environment Component URL Port Description
Production HTTP REST API https://efpf.smecluster.com/apis/sr/ Secure API exposed through API Security Gateway
Production MQTT Service Status Announcements API efpf.smecluster.com 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://efpf.smecluster.com/auth/realms/efpf/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=user-terminal' \
--data-urlencode 'username=your-efpf-user@companyx.org' \
--data-urlencode 'password=replace_this_with_password'

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

SR schema extension (optional): While registering your iFlow API from DS NiFi, if you want to enable authorization (AuthZ) for it, you can use the enableAuthZ attribute in the API.meta object as follows:

"meta": {
    "dataspine": {
        "enableAuthZ": true

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


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.


vhost for Service Registry: efpf

mosquitto_sub -h efpf.smecluster.com -p 8883 -u 'efpf: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


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


Data Spine Service Registry Documentation