diff --git a/docs/references/rest-apis/rest-service-listing-api.md b/docs/references/rest-apis/rest-service-listing-api.md index fa1c8d129af..b855e052996 100644 --- a/docs/references/rest-apis/rest-service-listing-api.md +++ b/docs/references/rest-apis/rest-service-listing-api.md @@ -1,144 +1,331 @@ +# Service Listing V1 REST APIs !!! note 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. -#### Get Service List -- Method: GET -- API PATH: `/services/serviceListing/v1/list` -##### Responses -- 200 OK status + * [Request definitions](#request-definitions) + * [GET/servicePids](#getservicepids) + * [POST/servicePids/byInterface](#postservicepidsbyinterface) + * [POST/servicePids/byProperty](#postservicepidsbyproperty) + * [POST/servicePids/satisfyingReference](#postservicepidssatisfyingreference) + * [GET/factoryPids](#getfactorypids) + * [POST/factoryPids/byInterface](#postfactorypidsbyinterface) + * [POST/factoryPids/byProperty](#postfactorypidsbyproperty) + * [JSON definitions](#json-definitions) + * [InterfaceNames](#interfacenames) + * [Reference](#reference) + * [Filter](#filter) + * [PropertyFilter](#propertyfilter) + * [NotFilter](#notfilter) + * [AndFilter](#andfilter) + * [OrFilter](#orfilter) + * [PidSet](#pidset) + * [GenericFailureReport](#genericfailurereport) -```JSON -{ - //Alphabetically ordered list of services running on kura - "servicesList": [ - "HttpsKeystore", - ... - ... - "org.eclipse.kura.clock.ClockService", - ... - ... - "org.eclipse.kura.data.DataService", - ... - ... - ] -} -``` +## 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](#pidset) + * **500** + * **description** : If an unexpected failure occurs while retrieving the service pid list. + * **response body** : + * [GenericFailureReport](#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](#interfacenames) + * **responses** : + * **200** + * **description** : An object reporting the pid of the matching services. + * **response body** : + * [PidSet](#pidset) + * **400** + * **description** : If the request body is not syntactically correct. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : If an unexpected failure occurs while retrieving the service pid list. + * **response body** : + * [GenericFailureReport](#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](#filter) + * **responses** : + * **200** + * **description** : An object reporting the pid of the matching services. + * **response body** : + * [PidSet](#pidset) + * **400** + * **description** : If the request body is not syntactically correct. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : If an unexpected failure occurs while retrieving the service pid list. + * **response body** : + * [GenericFailureReport](#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](#reference) + * **responses** : + * **200** + * **description** : An object reporting the pid of the matching services. + * **response body** : + * [PidSet](#pidset) + * **400** + * **description** : If the request body is not syntactically correct. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : If an unexpected failure occurs while retrieving the service pid list. + * **response body** : + * [GenericFailureReport](#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](#pidset) + * **500** + * **description** : If an unexpected failure occurs while retrieving the factory pid list. + * **response body** : + * [GenericFailureReport](#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](#interfacenames) + * **responses** : + * **200** + * **description** : An object reporting the matching factory pids. + * **response body** : + * [PidSet](#pidset) + * **400** + * **description** : If the request body is not syntactically correct. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : If an unexpected failure occurs while retrieving the factory pid list. + * **response body** : + * [GenericFailureReport](#genericfailurereport) ---- -#### Get Service List filtereb by interfaces -- Method: POST -- API PATH: `/services/serviceListing/v1/list/byInterface` +### 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](#filter) + * **responses** : + * **200** + * **description** : An object reporting the matching factory pids. + * **response body** : + * [PidSet](#pidset) + * **400** + * **description** : If the request body is not syntactically correct. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : If an unexpected failure occurs while retrieving the factory pid list. + * **response body** : + * [GenericFailureReport](#genericfailurereport) -##### Responses -- 200 OK status +## JSON definitions +### InterfaceNames +A list of serviceinterface names. -```JSON -Filter example +
**Properties**: + * **interfaceNames**: `array` + The list of service interface names. + + * array element type: `string` + A service interface name. + + + +```json { - "interfacesIds": [ - "org.eclipse.kura.security.keystore.KeystoreService" + "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 -```JSON + + +```json { - //Alphabetically ordered list of services running on kura filtered by implemented interfaces - "servicesList": [ - "HttpsKeystore", - "SSLKeystore" - ] + "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**: -If more than one interface is present in the `interfaceIds` request body, a logic AND of those are performed. -Example: + * **name**: `string` + The property name that should be matched, it must not contain spaces -```JSON -Filter example + + * **value**: `string` (**optional**) + The property value that should be matched. + + +```json { - "interfacesIds": [ - "org.eclipse.kura.configuration.ConfigurableComponent", - "org.eclipse.kura.watchdog.WatchdogService" - ] + "name": "foo", + "value": "bar" } ``` -```JSON -Response: +```json { - "servicesList": [ - "org.eclipse.kura.watchdog.WatchdogService" - ] + "name": "foo" } ``` +### NotFilter +A filter that negates the result returned by the filter specified as the "not" propertiy. -- 500 Internal Server Error - - Can occur if body json is not correctly written -```JSON - Example: +
**Properties**: - { - "interfacesIds": - } + * **not**: `object` + * [Filter](#filter) + + +```json +{ + "not": { + "name": "foo", + "value": "bar" + } +} ``` +### AndFilter +A filter that matches if all filters specified by the "and" propertiy match. -- 400 Bad Status - - If body json is null - ```JSON - Body: - { - } +
**Properties**: - Response: - { - "message": "Bad request. interfacesIds must not be null" - } - ``` - - If body json is empty - ```JSON - Body: - { - "interfacesIds": [ - ] - } + * **and**: `array` + A list of filters that should be combined with the and operator + + * array element type: `object` + * [Filter](#filter) + - Response: +```json +{ + "and": [ { - "message": "Bad request. interfacesIds must not be empty" - } - ``` - - If body json contains null entry - ```JSON - Body: + "name": "foo", + "value": "bar" + }, { - "interfacesIds": [ - "org.eclipse.kura.configuration.ComponentConfiguration", - - ] + "name": "baz" } + ] +} +``` +### OrFilter +A filter that matches if any of the filters specified by the "or" propertiy match. + +
**Properties**: - Response: + * **or**: `array` + A list of filters that should be combined with the or operator + + * array element type: `object` + * [Filter](#filter) + + +```json +{ + "or": [ { - "message": "Bad request. none of the interfacesIds can be null" - } - ``` - - If body json contains empty entry - ```JSON - Body: + "name": "foo", + "value": "bar" + }, { - "interfacesIds": [ - "org.eclipse.kura.configuration.ComponentConfiguration", - "" - ] + "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. - Response: - { - "message": "Bad request. none of the interfacesIds can be null" - } - ``` \ No newline at end of file +* **Variants**: + * **object** + * [PropertyFilter](#propertyfilter) + * **object** + * [NotFilter](#notfilter) + * **object** + * [AndFilter](#andfilter) + * **object** + * [OrFilter](#orfilter) + +### PidSet +Represents a set of pids or factory pids. + +
**Properties**: + + * **pids**: `array` + The set of pids + + * array element type: `string` + The pid + + + +```json +{ + "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. \ No newline at end of file