Devices Information =================== The devices information is available through endpoints that are specific to the type of information requested - **Specification** information contains - the information that uniquely identifies a device and its type - the permanent properties throughout the life of a device that defines and describes the device. For example, the manufacturer, model, and serial number are not going to change for a device statistic. - **Status** information contains properties that define the state of a device at a specific date-time. For example, the filling level of a dispenser is only valid at the time it was recorded. - **Statistic** information contains KPIs and business properties aggregated over a period of time. For example, the total runtime of a cleaning machine depends on the requested period. - **Diagnostic** information contains properties related to future state and activities such as service and maintenance schedule of the device. For example, the refill of a dispenser is scheduled for the next day. Definitions ----------- :doc:`Common definitions <../../common/common_definitions>` :doc:`Object model definitions <../../common/object_model_definitions>` .. include:: ../../common/pull_model_definitions.rst FDS compliance requirements for new device types ------------------------------------------------ This section provides the FDS compliance requirements when implementing an endpoint for a new device type. Requirements common to all device endpoints ''''''''''''''''''''''''''''''''''''''''''' - All endpoints must provide the authorization token in the HTTPS header - If a request is unauthorized, the information provider must return - a 401 HTTP status code in the response header - an error object in the response body with a "unauthorized_request" message - If a query parameter name is invalid, the information provider must return - a 400 HTTP status code in the response header - an error object in the response body with a "invalid_parameter" message - if a parameter provided appears more than once in the request, the information provider must return - a 400 HTTP status code in the response header - an error object in the response body with a "duplicate_parameter" message - If no devices are found in the query, the information provider must return an empty list of devices - a 200 HTTP status code in the response header - the response object with an empty array of data Specifications endpoint ''''''''''''''''''''''' - The device information provider must expose the **specifications** endpoint to get the list of available devices and their specifications .. code-block:: GET https://{Device Information Provider URL}/fds/v2/specifications - The specifications enpoint must accept the query parameters +--------------------+-------------+-----------------------------------------------------+ | parameter | Type | Description | +====================+=============+=====================================================+ | registered_since | date | - Get the devices registered since that date | | | | - Optional | | | | - If not specified, returns the specifications | | | | for all the registered devices for the | | | | authorized resource owner | | | | | +--------------------+-------------+-----------------------------------------------------+ - If the registered_since date is invalid or not properly formatted, the information provider must return - a 403 HTTP status code in the response header - an error object in the response body with a "invalid_date" message - The information provider must return the full list of devices found - Successful devices specification retrieval must return - a 200 HTTP status code in the response header - the **specifications** object containing the **specification** for each device The following diagram provides a high level description of the **specifications** endpoint: .. figure:: ../../_static/specifications_endpoint.png :width: 100% Statuses endpoint ''''''''''''''''' - The device information provider must expose the **statuses** endpoint to get the latest status for one or multiple devices .. code-block:: GET https://{Device Information Provider URL}/fds/v2/statuses - The statuses enpoint must accept the query parameters +--------------------+-------------------------+-----------------------------------------------------+ | parameter | Type | Description | +====================+=========================+=====================================================+ | device_ids | Comma separated list | - The list of devices to query | | | of device IDs | - Optional | | | | - If not specified, tag_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ | tag_ids | Comma separated list | - the list of tags to query | | | of tag IDs | - Optional | | | | - If not specified, device_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ - The information provider must accept both the device_ids and tag_ids parameter in the same request - If no query parameter is provided in the request, the information provider must return - a 400 HTTP status code in the response header - an error object in the response body with a "missing_parameter" message - If one or multiple device IDs do not exist on the information provider side, the information provider must return a successful response with an **item_error** object for each of the device information not available - a 200 HTTP status code in the response header - the **statuses** object - The **errors** property must contain - the **item_error** objects for each unavailable device - the ID of the device - the item type must be **"device"** - the message must be "invalid_device" - If one or multiple tags do not exist on the information provider side, the information provider must return a successful response with an **item_error** object for each of the tags not found - a 200 HTTP status code in the response header - the **statuses** object - The **errors** property must contain - the **item_error** objects for each tag not found - the ID of the tag - the item type must be **"tag"** - the message must be "invalid_tag" - The device information provider can limit the number of device statuses returned to avoid potentially large responses - When response size limit is implemented and the limit is reached, the information provider must return - a 403 HTTP status code in the response header - an error object in the response body with - a "over_limit" message - the maximum number of **status** objects that can be returned - Successful devices status retrieval must return - a 200 HTTP status code in the response header - the **statuses** object containing the **status** object for each device The following diagram provides a high level description of the **statuses** endpoint: .. figure:: ../../_static/statuses_endpoint.png :width: 100% Statistics endpoint ''''''''''''''''''' - The device information provider can implement the **statistics** endpoint to expose the statistics for one or multiple devices .. code-block:: GET https://{Device Information Provider URL}/fds/v2/statistics - The **statistics** endpoint is optional. If the statistics endpoint is not implemented, the information provider must return - a 204 HTTP status code - an error object in the response body with a "not_implemented" message - The statistics enpoint must accept the query parameters +--------------------+-------------------------+-----------------------------------------------------+ | parameter | Type | Description | +====================+=========================+=====================================================+ | device_ids | Comma separated list | - The list of devices to query | | | of device IDs | - Optional | | | | - If not specified, tag_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ | tag_ids | Comma separated list | - the list of tags to query | | | of tag IDs | - Optional | | | | - If not specified, device_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ | start_date | Date-time | - The aggregation start date | | | | - Required | +--------------------+-------------------------+-----------------------------------------------------+ | end_date | Date-time | - The aggregation end date | | | | - Optional | | | | - if not specified, now is assumed | +--------------------+-------------------------+-----------------------------------------------------+ - The information provider must accept both the device_ids and tag_ids parameter in the same request - If no query parameter is provided in the request, the information provider must return - a 400 HTTP status code in the response header - an error object in the response body with a "missing_parameter" message - The aggregation start date must be prior to the current UTC date and time - When provided, the aggregation end date must be prior to the current UTC date and time - When provided, the aggregation end date must be past the aggregation start date - If the aggregation start date is invalid or not properly formatted, the information provider must return - a 403 HTTP status code in the response header - an error object in the response body with a "invalid_start_date" message - If the aggregation end date is invalid or not properly formatted, the information provider must return - a 403 HTTP status code in the response header - an error object in the response body with a "invalid_end_date" message - If one or multiple device IDs do not exist on the information provider side, the information provider must return a successful response with an **item_error** object for each of the device information not available - a 200 HTTP status code in the response header - the **statistics** object - The **errors** property must contain - the **item_error** objects for each unavailable device - the ID of the device - the item type must be **"device"** - the message must be "invalid_device" - If one or multiple tags not exist on the information provider side, the information provider must return a successful response with an **item_error** object for each of the tags not found - a 200 HTTP status code in the response header - the **statistics** object - The **errors** property must contain - the **item_error** objects for each tag not found - the ID of the tag - the item type must be **"tag"** - the message must be "invalid_tag" - The device information provider can limit the number of device statistics returned to avoid potentially large responses - When response size limit is implemented and the limit is reached, the information provider must return - a 403 HTTP status code in the response header - an error object in the response body with - a "over_limit" message - the maximum number of **statistic** objects that can be returned - Successful devices statistics retrieval must return - a 200 HTTP status code in the response header - the **statistics** object containing the **statistic** object for each device The following diagram provides a high level description of the **statistics** endpoint: .. figure:: ../../_static/statistics_endpoint.png :width: 100% Diagnostics endpoint '''''''''''''''''''' - The device information provider can implement the **diagnostics** endpoint to expose the prognostic and predictive information for one or multiple devices .. code-block:: GET https://{Device Information Provider URL}/fds/v2/diagnostics - The **diagnostics** endpoint is optional. If the diagnostics endpoint is not implemented, the information provider must return - a 204 HTTP status code - an error object in the response body with a "not_implemented" message - The diagnostics enpoint must accept the query parameters +--------------------+-------------------------+-----------------------------------------------------+ | parameter | Type | Description | +====================+=========================+=====================================================+ | device_ids | Comma separated list | - The list of devices to query | | | of device IDs | - Optional | | | | - If not specified, tag_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ | tag_ids | Comma separated list | - the list of tags to query | | | of tag IDs | - Optional | | | | - If not specified, device_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ - The information provider must accept both the device_ids and tag_ids parameter in the same request - If no query parameter is provided in the request, the information provider must return - a 400 HTTP status code in the response header - an error object in the response body with a "missing_parameter" message - If one or multiple device IDs do not exist on the information provider side, the information provider must return a successful response with an **item_error** object for each of the device information not available - a 200 HTTP status code in the response header - the **diagnostics** object - The **errors** property must contain - the **item_error** objects for each unavailable device - the ID of the device - the item type must be **"device"** - the message must be "invalid_device" - If one or multiple tags not exist on the information provider side, the information provider must return a successful response with an **item_error** object for each of the tags not found - a 200 HTTP status code in the response header - the **diagnostics** object - The **errors** property must contain - the **item_error** objects for each tag not found - the ID of the tag - the item type must be **"tag"** - the message must be "invalid_tag" - The device information provider can limit the number of device diagnostics returned to avoid potentially large responses - When response size limit is implemented and the limit is reached, the information provider must return - a 403 HTTP status code in the response header - an error object in the response body with - a "over_limit" message - the maximum number of **diagnostic** objects that can be returned - Successful devices specification retrieval must return - a 200 HTTP status code in the response header - the **diagnostics** object containing the **diagnostic** object for each device The following diagram provides a high level description of the **diagnostics** endpoint: .. figure:: ../../_static/diagnostics_endpoint.png :width: 100% Workflow -------- This section provides a guideline and best practice to use the REST API endpoints. Initial Call '''''''''''' When a client application manages devices for a resource owner, it should first get the initial list of all the devices registered to this resource owner from the device manufacturer, according to the workflow: .. figure:: ../../_static/initial_list_of_devices_workflow.png :width: 100% Important note: The call to the ‘specifications ' endpoint without any query parameters should only happen once for a resource owner. Periodic Information '''''''''''''''''''' There should be two types of periodic operations to access devices information through the REST API as specified in the following workflow - Get the list of potential new devices - Get status, statistic, diagnostic, and/or event information on managed devices. Note that the device IDs must be known for these operations .. figure:: ../../_static/periodic_operations_workflow.png :width: 100% .. include:: ../../common/use_case_pull_model_devices.rst