Service Listing V1 Rest API

📘

This API can also be accessed via the RequestHandler with app-id: SVCLIST-V1.

The SVCLIST-V1 cloud request handler and the corresponding REST APIs allow to retrieve the identifiers (kura.service.pid) of the service running on the system that match user provided search criteria.

• Request definitions
  • GET/servicePids
  • POST/servicePids/byInterface
  • POST/servicePids/byProperty
  • POST/servicePids/satisfyingReference
  • GET/factoryPids
  • POST/factoryPids/byInterface
  • POST/factoryPids/byProperty
• JSON definitions
  • InterfaceNames
  • Reference
  • Filter
  • PropertyFilter
  • NotFilter
  • AndFilter
  • OrFilter
  • PidSet
  • GenericFailureReport

Request definitions

GET/servicePids

• REST API path : /services/serviceListing/v1/servicePids
• description : Returns the pid of all services running in the framework.
• responses :
  • 200
    • description : An object reporting the pid of all services running in the framework
    • response body :
      • PidSet
  • 500
    • description : If an unexpected failure occurs while retrieving the service pid list.
    • response body :
      • GenericFailureReport

POST/servicePids/byInterface

• REST API path : /services/serviceListing/v1/servicePids/byInterface
• description : Returns the pid of the services providing all of the service interfaces specified in the request
• request body :
  • InterfaceNames
• responses :
  • 200
    • description : An object reporting the pid of the matching services.
    • response body :
      • PidSet
  • 400
    • description : If the request body is not syntactically correct.
    • response body :
      • GenericFailureReport
  • 500
    • description : If an unexpected failure occurs while retrieving the service pid list.
    • response body :
      • GenericFailureReport

POST/servicePids/byProperty

• REST API path : /services/serviceListing/v1/servicePids/byProperty
• description : Returns the pid of the services whose properties match the specified filter.
• request body :
  • Filter
• responses :
  • 200
    • description : An object reporting the pid of the matching services.
    • response body :
      • PidSet
  • 400
    • description : If the request body is not syntactically correct.
    • response body :
      • GenericFailureReport
  • 500
    • description : If an unexpected failure occurs while retrieving the service pid list.
    • response body :
      • GenericFailureReport

POST/servicePids/satisfyingReference

• REST API path : /services/serviceListing/v1/servicePids/satisfyingReference
• description : Returns the pid of the services that provide an interface compatible with a Declarative Service reference. Reference examples are KeystoreService and TruststoreKeystoreService defined by the org.eclipse.kura.ssl.SslManagerService component.
• request body :
  • Reference
• responses :
  • 200
    • description : An object reporting the pid of the matching services.
    • response body :
      • PidSet
  • 400
    • description : If the request body is not syntactically correct.
    • response body :
      • GenericFailureReport
  • 500
    • description : If an unexpected failure occurs while retrieving the service pid list.
    • response body :
      • GenericFailureReport

GET/factoryPids

• REST API path : /services/serviceListing/v1/factoryPids
• description : Returns the factory pids defined in the framework.
• responses :
  • 200
    • description : An object reporting the factory pids defined in the framework.
    • response body :
      • PidSet
  • 500
    • description : If an unexpected failure occurs while retrieving the factory pid list.
    • response body :
      • GenericFailureReport

POST/factoryPids/byInterface

• REST API path : /services/serviceListing/v1/factoryPids/byInterface
• description : Returns the factory pid of the services that provide all of the specified interfaces.
• request body :
  • InterfaceNames
• responses :
  • 200
    • description : An object reporting the matching factory pids.
    • response body :
      • PidSet
  • 400
    • description : If the request body is not syntactically correct.
    • response body :
      • GenericFailureReport
  • 500
    • description : If an unexpected failure occurs while retrieving the factory pid list.
    • response body :
      • GenericFailureReport

POST/factoryPids/byProperty

• REST API path : /services/serviceListing/v1/factoryPids/byProperty
• description : Returns the list of factory pids whose properties match the specified filter.
• request body :
  • Filter
• responses :
  • 200
    • description : An object reporting the matching factory pids.
    • response body :
      • PidSet
  • 400
    • description : If the request body is not syntactically correct.
    • response body :
      • GenericFailureReport
  • 500
    • description : If an unexpected failure occurs while retrieving the factory pid list.
    • response body :
      • GenericFailureReport

JSON definitions

InterfaceNames

A list of serviceinterface names.

Properties:

• interfaceNames: array
  The list of service interface names.

  • array element type: string
    A service interface name.

{
  "interfaceNames": [
    "org.eclipse.kura.security.keystore.KeystoreService",
    "org.eclipse.kura.configuration.ConfigurableComponent"
  ]
}

Reference

A object specifying a service pid and a reference name.

Properties:

• pid: string
  The pid of the service containing the reference

• referenceName: string
  The reference name

{
  "pid": "org.eclipse.kura.ssl.SslManagerService",
  "referenceName": "KeystoreService"
}

PropertyFilter

A filter matching property keys and values. If the value property omitted, the filter will match if the property is set, regardless of the value. If the service property value is of array or list type, the filter will match if at least one of the elements match.

Properties:

• name: string
  The property name that should be matched, it must not contain spaces

• value: string (optional)
  The property value that should be matched.

{
  "name": "foo",
  "value": "bar"
}

{
  "name": "foo"
}

NotFilter

A filter that negates the result returned by the filter specified as the "not" propertiy.

Properties:

• not: object
  • Filter

{
  "not": {
    "name": "foo",
    "value": "bar"
  }
}

AndFilter

A filter that matches if all filters specified by the "and" propertiy match.

Properties:

• and: array
  A list of filters that should be combined with the and operator

  • array element type: object
    • Filter

{
  "and": [
    {
      "name": "foo",
      "value": "bar"
    },
    {
      "name": "baz"
    }
  ]
}

OrFilter

A filter that matches if any of the filters specified by the "or" propertiy match.

Properties:

• or: array
  A list of filters that should be combined with the or operator

  • array element type: object
    • Filter

{
  "or": [
    {
      "name": "foo",
      "value": "bar"
    },
    {
      "name": "baz"
    }
  ]
}

Filter

A filter that operates on service properties. This object allows to specify basic property key/value matchers and the and or and not operators.

• Variants:
  • object
    • PropertyFilter
  • object
    • NotFilter
  • object
    • AndFilter
  • object
    • OrFilter

PidSet

Represents a set of pids or factory pids.

Properties:

• pids: array
  The set of pids

  • array element type: string
    The pid

{
  "pids": [
    "org.eclipse.kura.cloud.app.command.CommandCloudApp",
    "org.eclipse.kura.cloud.CloudService",
    "org.eclipse.kura.cloud.publisher.CloudNotificationPublisher",
    "org.eclipse.kura.container.orchestration.provider.ContainerOrchestrationService",
    "org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport",
    "org.eclipse.kura.core.deployment.CloudDeploymentHandlerV2",
    "org.eclipse.kura.crypto.CryptoService",
    "org.eclipse.kura.data.DataService",
    "org.eclipse.kura.db.H2DbService",
    "org.eclipse.kura.deployment.agent"
  ]
}

GenericFailureReport

An object reporting a failure message.

Properties:

• message: string
  A message describing the failure.