# List the definition of a feature `GET /api/2/things/{thingId}/features/{featureId}/definition` Returns the complete definition field of the feature identified by the `thingId` and `featureId` path parameter. Authentication (security requirement alternatives): ```json [ { "OpenIDConnect": [] }, { "NginxBasic": [] }, { "Bearer": [] } ] ``` - OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured. - NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo) - Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider. Parameters: - `thingId` (path, string, required) - The ID of a thing needs to follow the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)). Type: string - `featureId` (path, string, required) - The ID of the feature - has to conform to RFC-3986 (URI) Type: string - `If-Match` (header, string, optional) - The `If-Match` header which has to conform to RFC-7232 (Conditional Requests). Common usages are: * optimistic locking by specifying the `ETag` from a previous HTTP response, e.g. `If-Match: "hash:a75ece4e"` * retrieving or modifying a resource only if it already exists, e.g. `If-Match: *` Type: string - `If-None-Match` (header, string, optional) - The `If-None-Match` header, which has to conform to RFC-7232 (Conditional Requests). A common usage scenario is to modify a resource only if it does not yet exist, thus to create it, by specifying `If-None-Match: *`. Type: string - `if-equal` (header, string, optional) - The `if-equal` header can take the values 'update' (which is the default if omitted), 'skip' or 'skip-minimizing-merge'. If 'update' is defined, the entity will always be updated, even if it is equal before the update. If 'skip' is defined, the entity not be updated if it is equal before the update. In this case a 'Precondition Failed' 412 status is returned. If 'skip-minimizing-merge' is defined, the entity will not be updated if it is equal before the update. In this case a 'Precondition Failed' 412 status is returned. Additionally, merge/patch commands will be minimized to only the fields which actually changed, compared to the current state of the entity. Type: string enum: ["update","skip","skip-minimizing-merge"] - `get-metadata` (header, string, optional) - The `get-metadata` header, which retrieves Metadata of the Thing. Type: string A string of comma separated JsonPointers to retrieve from the Metadata of the Thing. - `timeout` (query, string, optional) - Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested acknowledgements via the `requested-acks` param. Can be specified without unit (then seconds are assumed) or together with `s`, `ms` or `m` unit. Example: `42s`, `1m`. The default (if omitted) and maximum timeout is `60s`. A value of `0` applies fire and forget semantics for the command resulting in setting `response-required=false`. Type: string - `condition` (query, string, optional) - Defines that the request should only be processed if the given condition is met. The condition can be specified using RQL syntax. #### Examples E.g. if the temperature is not 23.9 update it to 23.9: * ```PUT /api/2/things/{thingId}/features/temperature/properties/value?condition=ne(features/temperature/properties/value,23.9)``` `body: 23.9` Further example conditions: * ```?condition=eq(features/temperature/properties/unit,"Celsius")``` * ```?condition=ge(features/temperature/properties/lastModified,"2021-08-22T19:45:00Z")``` * ```?condition=gt(_modified,"2021-08-05T12:17:00Z")``` * ```?condition=exists(features/temperature/properties/value)``` * ```?condition=empty(features/temperature/properties/value)``` * ```?condition=and(gt(features/temperature/properties/value,18.5),lt(features/temperature/properties/value,25.2))``` * ```?condition=or(gt(features/temperature/properties/value,18.5),not(exists(features/temperature/properties/value))``` Type: string - `channel` (query, string, optional) - Defines to which channel to route the command: `twin` (digital twin) or `live` (the device). * If setting the channel parameter is omitted, the `twin` channel is set by default and the command is routed to the persisted representation of a thing in Eclipse Ditto. * When using the `live` channel, the command/message is sent towards the device. Type: string enum: ["twin","live"] - `live-channel-condition` (query, string, optional) - Defines that the request should fetch thing data via `live` channel if the given condition is met. The condition can be specified using RQL syntax. #### Examples * ```?live-channel-condition=lt(_modified,"2021-12-24T12:23:42Z")``` * ```?live-channel-condition=ge(features/ConnectionStatus/properties/status/readyUntil,time:now)``` Type: string - `live-channel-timeout-strategy` (query, any, optional) - Defines a strategy how to handle timeouts of a live response to a request sent via `channel=live` or with a matching live-channel-condition. Type: any enum: ["fail","use-twin"] Responses: - 200: The definition was successfully retrieved. Content type: application/json Type: Array The definitions of a feature. Schema: [FeatureDefinition](https://sourcey-ditto.pages.dev/http-api-doc/models/featuredefinition.md) Items: Type: string A single fully qualified identifier of a feature definition in the form '::' or a valid HTTP(s) URL pattern: "([_a-zA-Z0-9\\-.]+):([_a-zA-Z0-9\\-.]+):([_a-zA-Z0-9\\-.]+)" - 304: The (sub-)resource has not been modified. This happens when you specified a If-None-Match header which matches the current ETag of the (sub-)resource. - 400: The request could not be completed. Possible reasons: * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)). * at least one of the defined query parameters is invalid. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 401: The request could not be completed due to missing authentication. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 404: The request could not be completed. The specified feature has no definition or the thing with the specified `thingId` or the feature with `featureId` was not found. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 412: A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a failing If-None-Match header for a read request, status 304 will be returned instead. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it ## Examples ### cURL ```bash curl -X GET 'https://ditto.eclipseprojects.io/api/2/things/string/features/string/definition' \ -H 'Authorization: Bearer YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://ditto.eclipseprojects.io/api/2/things/string/features/string/definition', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://ditto.eclipseprojects.io/api/2/things/string/features/string/definition', headers={ 'Authorization': 'Bearer YOUR_TOKEN', }, ) print(response.text) ```