2.4.1. 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.
2.4.1.1. Definitions
2.4.1.1.1. Web API
- Endpoint
- The URL to access a service implemented on the server of an information provider with the aim to provide responses to requests sent by a client application
https://soapinc.com/fds/v2/specifications is the endpoint to access the specifications of my soap dispensers
- Request
The action to be performed by the endpoint and requested by the client application. The action is identified by a HTTP method and can be
GET: to retrieve item information from the provider
POST: to let an information consumer create an item managed by the information provider
PUT: to modify the content of an item managed by the information provider
DELETE: to remove an item managed by the information provider
GET https://soapinc.com/fds/v2/specifications is the request to retrieve the specifications of my soap dispensers
- Response
- The information supplied by the information provider server in response of the request
The response to the GET https://soapinc.com/fds/v2/specifications is a list of device objects
- Query parameters
- Parameters added to the end of a request to specify additional information about the response expected by the server of the client application
To get the status of a soap dispenser, add the ‘ids’ query parameter with the device ID for the dispenser
- Request header
- A set of metadata information about the request provided by the client application that the server uses to manage the response
The authentication token in the request header lets the server assess if this is a valid request
- Request body
- A set of JSON-formatted data provided as part of the request that contains item information requested by the server of the client application
When defining the location of the soap dispenser, put the device ID in the request body of the POST https://soapinc.com/fds/v2/devices_location request
- Response body
- A set of JSON-formatted data part of the response that contains the information provided by the server of the information provider
The soap dispenser specifications will be found in the response body of the GET https://soapinc.com/fds/v2/specifications request/
2.4.1.2. FDS compliance requirements for new device types
This section provides the FDS compliance requirements when implementing an endpoint for a new device type.
2.4.1.2.1. 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
2.4.1.2.2. Specifications endpoint
The device information provider must expose the specifications endpoint to get the list of available devices and their specifications
GET https://{Device Information Provider URL}/fds/v2/specifications
The specifications enpoint must accept the query parameters
parameter |
Type |
Description |
|---|---|---|
registered_since |
date |
|
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:
2.4.1.2.3. Statuses endpoint
The device information provider must expose the statuses endpoint to get the latest status for one or multiple devices
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 of device IDs |
|
tag_ids |
Comma separated list of tag IDs |
|
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:
2.4.1.2.4. Statistics endpoint
The device information provider can implement the statistics endpoint to expose the statistics for one or multiple devices
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 of device IDs |
|
tag_ids |
Comma separated list of tag IDs |
|
start_date |
Date-time |
|
end_date |
Date-time |
|
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:
2.4.1.2.5. Diagnostics endpoint
The device information provider can implement the diagnostics endpoint to expose the prognostic and predictive information for one or multiple devices
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 of device IDs |
|
tag_ids |
Comma separated list of tag IDs |
|
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:
2.4.1.3. Workflow
This section provides a guideline and best practice to use the REST API endpoints.
2.4.1.3.1. 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:
Important note: The call to the ‘specifications ‘ endpoint without any query parameters should only happen once for a resource owner.
2.4.1.3.2. 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
2.4.1.4. Use case example
Note
Join FDS to get access to examples and use cases.