core-data API documentation version 1.1.x

http://localhost:48080/api

Welcome

Welcome to the Core Data Microservice API Documentation.

Event Resource

example - http://localhost:48080/api/v1/event

post put get

post

Add a new event (with its associated readings). Prefers the event device is a device name but can also be a device id (database generated). DataValidationException (HTTP 409) if the a reading is associated to a non-existent value descriptor. ServiceException (HTTP 500) for unknown or unanticipated issues.

put

Update the event data (not including updating the readings). NotFoundException (HTTP 404) if the event cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

get

Fetch all events with their associated readings. LimitExceededException (HTTP 413) if the number of events exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Add a new event (with its associated readings). Prefers the event device is a device name but can also be a device id (database generated). DataValidationException (HTTP 409) if the a reading is associated to a non-existent value descriptor. ServiceException (HTTP 500) for unknown or unanticipated issues.

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor event","title":"event","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"device":{"type":"string","required":false,"title":"device"},"readings":{"type":"array","required":false,"title":"readings","items":{"type":"object","$ref":"#/schemas/reading"},"uniqueItems":false}}}

Example:

{"origin":1471806386919,"device":"livingroomthermostat","readings":[{"origin":1471806386919,"name":"temperature","value":"38"}]}

HTTP status code 200

new event database generated id

HTTP status code 400

creation request is invalid

HTTP status code 404

if the a reading is associated to a non-existent value descriptor, or if device verification is enabled and the device is not found.

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by id)

example - http://localhost:48080/api/v1/event/c4094ab7-a0dc-4721-aee3-a28b967a5801

get

get

Fetch a specific event by database specified id - returning null if none are found. Note: does not yet handle device managers. ServiceException (HTTP 500) for unknown or unanticipated issues

Fetch a specific event by database specified id - returning null if none are found. Note: does not yet handle device managers. ServiceException (HTTP 500) for unknown or unanticipated issues

URI Parameters

  • id: (string)

    database generated id

HTTP status code 200

event

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor event","title":"event","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"device":{"type":"string","required":false,"title":"device"},"readings":{"type":"array","required":false,"title":"readings","items":{"type":"object","$ref":"#/schemas/reading"},"uniqueItems":false}}}

Example:

{"id":"c4094ab7-a0dc-4721-aee3-a28b967a5801","created":1485364897029,"modified":1485364897029,"origin":1471806386919,"pushed":0,"device":"livingroomthermostat","readings":[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]}

HTTP status code 404

if the event cannot be found by id.

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by checksum)

http://localhost:48080/api/v1/event/checksum/499a1a799c47c567

put

put

Update an existing event's pushed time

Update an existing event's pushed time

URI Parameters

  • checksum: required (string)

    checksum value of the event provided by core-data via the message bus

HTTP status code 200

success no body returned

HTTP status code 404

if the event cannot be found by checksum.

HTTP status code 500

for unknown or unanticipated issues.

Event Resource Count

example - http://localhost:48080/api/v1/event/device/count

get

get

Return a count of the number of events in core data. ServiceException (HTTP 500) for unknown or unanticipated issues..

Event Resource Count for a given device

example - http://localhost:48080/api/v1/event/count/livingroomthermostat

get

get

Return a count of the number of events in core data for a given device - identified by id or name. InternalServerError (HTTP 500) for unknown or unanticipated issues..

Return a count of the number of events in core data for a given device - identified by id or name. InternalServerError (HTTP 500) for unknown or unanticipated issues..

URI Parameters

  • deviceId: required (string)

HTTP status code 200

number of events for the device

HTTP status code 400

query request is invalid

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by id)

example - http://localhost:48080/api/v1/event/id/5f79f674-a25e-44e6-bab0-1cc687420e40

delete put

delete

Delete an event and all its readings given its database generated id. NotFoundException (HTTP 404) if the event cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

put

Update the event to be pushed (out of EdgeX to an enterprise or cloud system) by setting the pushed timestamp to the current time. NotFoundException (HTTP 404) if the event cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

Delete an event and all its readings given its database generated id. NotFoundException (HTTP 404) if the event cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • id: (string)

    database generated id

HTTP status code 200

boolean on success of deletion request

HTTP status code 404

if the event cannot be found by id.

HTTP status code 500

for unknown or unanticipated issues.

Update the event to be pushed (out of EdgeX to an enterprise or cloud system) by setting the pushed timestamp to the current time. NotFoundException (HTTP 404) if the event cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • id: (string)

    database generated id

HTTP status code 200

boolean on success of update request

HTTP status code 404

if the event cannot be found by id

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by device)

example - http://localhost:48080/api/v1/event/device/livingroomthermostat/10 (where livingroomthermostat is a device name)

get

get

Return list of events with their associated readings for a given device, sorted by event modified date. Newest events are at the top of list. May be an empty list if none are associated to the device. Note: does not yet handle device managers. LimitExceededException (HTTP 413) if the number of events exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues. NotFoundException (HTTP 404) if the meta data checks are on and no device is found for supplied id.

Return list of events with their associated readings for a given device, sorted by event modified date. Newest events are at the top of list. May be an empty list if none are associated to the device. Note: does not yet handle device managers. LimitExceededException (HTTP 413) if the number of events exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues. NotFoundException (HTTP 404) if the meta data checks are on and no device is found for supplied id.

URI Parameters

  • limit: (integer)

    maximum number of events to fetch, must be < max limit

  • deviceId: (string)

    the id (database generated id) or name of the device associated to events

HTTP status code 200

list of events associated to the matching device by id - limited in size by the limit parameter

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor event","title":"event","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"device":{"type":"string","required":false,"title":"device"},"readings":{"type":"array","required":false,"title":"readings","items":{"type":"object","$ref":"#/schemas/reading"},"uniqueItems":false}}}

Example:

[{"id":"c4094ab7-a0dc-4721-aee3-a28b967a5801","created":1485364897029,"modified":1485364897029,"origin":1471806386919,"pushed":0,"device":"livingroomthermostat","readings":[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 404

if the meta data checks are on and no device is found for supplied id.

HTTP status code 413

if the number of events exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by device)

example - http://localhost:48080/api/v1/event/device/livingroomthermostat (where livingroomthermostat is a device name)

delete

delete

Delete all events (and their readings) associated to a device given the device's id (either database generated id or name). ServiceException (HTTP 500) for unknown or unanticipated issues. NotFoundException (HTTP 404) if the meta data checks are on and no device is found for supplied id.

Delete all events (and their readings) associated to a device given the device's id (either database generated id or name). ServiceException (HTTP 500) for unknown or unanticipated issues. NotFoundException (HTTP 404) if the meta data checks are on and no device is found for supplied id.

URI Parameters

  • deviceId: (string)

    the id (database generated id) or name of the device associated to events

HTTP status code 200

count of the number of events deleted

HTTP status code 400

could not unescape URL

HTTP status code 404

if the meta data checks are on and no device is found for supplied id.

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by creation time)

example - http://localhost:48080/api/v1/event/1471809160000/1471809161000/10

get

get

Return all events between a given begin and end date/time (in the form of longs) sorted by event modified date. Newest events are at the top of list. LimitExceededException (HTTP 413) if the number of events exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return all events between a given begin and end date/time (in the form of longs) sorted by event modified date. Newest events are at the top of list. LimitExceededException (HTTP 413) if the number of events exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: (integer)

    maximum number of events to fetch, must be < max limit

  • start: (integer)

    start date in long form

  • end: (integer)

    end date in long form

HTTP status code 200

list of events between the specified dates

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor event","title":"event","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"device":{"type":"string","required":false,"title":"device"},"readings":{"type":"array","required":false,"title":"readings","items":{"type":"object","$ref":"#/schemas/reading"},"uniqueItems":false}}}

Example:

[{"id":"c4094ab7-a0dc-4721-aee3-a28b967a5801","created":1485364897029,"modified":1485364897029,"origin":1471806386919,"pushed":0,"device":"livingroomthermostat","readings":[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of events exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Event Resource (by age)

example - http://localhost:48080/api/v1/event/removeold/age/604800000

delete

delete

Remove all old events (and associated readings) based on delimiting age. ServiceException (HTTP 500) for unknown or unanticipated issues. Should only be used by the scrubber micro service

Remove all old events (and associated readings) based on delimiting age. ServiceException (HTTP 500) for unknown or unanticipated issues. Should only be used by the scrubber micro service

URI Parameters

  • age: (integer)

    minimum age in milliseconds (from created timestamp) an event should be in order to be removed

HTTP status code 200

count of the number of events removed

HTTP status code 500

for unknown or unanticipated issues.

Scrub Event Resource

example - http://localhost:48080/api/v1/event/scrub

delete

delete

Remove all pushed events and their associated readings.ServiceException (HTTP 500) for unknown or unanticipated issues. Should only be used by the scrubber micro service

Reading Resource

example - http://localhost:48080/api/v1/reading

post put get

post

Add a new reading. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the associated value descriptor is non-existent.

put

Update the reading. Reading object needs to contain the database generated id of the existing reading. NotFoundException (HTTP 404) if the reading cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException if the associated value descriptor is non-existent.

get

Return list of all readings. Sorts by reading id. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Add a new reading. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the associated value descriptor is non-existent.

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

{"origin":1471806386919,"name":"temperature","value":"38"}

HTTP status code 200

String id (database id) of the new Reading

HTTP status code 400

request is invalid or unparseable

HTTP status code 409

if the associated value descriptor is non-existent

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource Count

example - http://localhost:48080/api/v1/reading/count

get

get

Return a count of the number of readings in core dataServiceException (HTTP 500) for unknown or unanticipated issues..

Reading Resource (by id)

example - http://localhost:48080/api/v1/reading/5f79f674-a25e-44e6-bab0-1cc687420e40

get

get

Retrieve a reading by its database generated id. NotFoundException (HTTP 404) if reading not found by id. ServiceException (HTTP 500) for unknown or unanticipated issues

Retrieve a reading by its database generated id. NotFoundException (HTTP 404) if reading not found by id. ServiceException (HTTP 500) for unknown or unanticipated issues

URI Parameters

  • id: (string)

    reading database generated id

HTTP status code 200

Reading

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}

HTTP status code 404

if the reading cannot be found by id

HTTP status code 500

for unknown or unanticipated issues

Reading Resource (by id)

example - http://localhost:48080/api/v1/reading/id/5f79f674-a25e-44e6-bab0-1cc687420e40

delete

delete

Delete the reading from persistent storage. NotFoundException (HTTP 404) if the reading cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

Delete the reading from persistent storage. NotFoundException (HTTP 404) if the reading cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • id: (string)

    database generated id of the reading to be deleted

HTTP status code 200

boolean indicating success of the delete operation

HTTP status code 404

if the reading cannot be found by id

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource (by device)

example - http://localhost:48080/api/v1/reading/device/livingroomthermostat/10 (where livingroomthermostat is the name of a device)

get

get

Return list of all readings for a given device, sorted by the readings modified date. Newest readings are at the top of list. Note: does not yet handle device managers. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues. NotFoundException (HTTP 404) if meta checks are in place and if the device id or name does not match any existing devices.

Return list of all readings for a given device, sorted by the readings modified date. Newest readings are at the top of list. Note: does not yet handle device managers. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues. NotFoundException (HTTP 404) if meta checks are in place and if the device id or name does not match any existing devices.

URI Parameters

  • limit: (integer)

    maximum number of readings requested (not to exceed max limit)

  • deviceId: (string)

    device database generated id or device name

HTTP status code 200

List of readings for a device, could be an empty list if none match

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 404

if meta checks are in place and if the device id or name does not match any existing devices

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

or unknown or unanticipated issues

Reading Resource (by value descriptor and device)

example - http://localhost:48080/api/v1/reading/name/temperature/device/livingroomthermostat/10 (where temperature is the name of a value descriptor and livingroomthermostat is the name of the device)

get

get

Return a list of readings that are associated to a ValueDescripter by name and Device by name (or id), sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return a list of readings that are associated to a ValueDescripter by name and Device by name (or id), sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: required (integer)

    maximum number of readings to return (must not exceed max limit)

  • name: required (string)

    name of the matching ValueDescriptor

  • device: required (string)

    name or id of the matching device (as the device is represented in the associated event)

HTTP status code 200

list of readings matching on the value descriptor name and device name (or id)

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource (by value descriptor)

example - http://localhost:48080/api/v1/reading/name/temperature/10 (where temperature is the name of a value descriptor)

get

get

Return a list of readings that are associated to a ValueDescripter by name, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return a list of readings that are associated to a ValueDescripter by name, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: (integer)

    maximum number of readings to return (must not exceed max limit)

  • name: (string)

    name of the matching ValueDescriptor

HTTP status code 200

list of readings matching on the value descriptor name

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource (by unit of measure)

example - http://localhost:48080/api/v1/reading/uomlabel/degree cel/10 (where degree cel is the unit of measure for an assocaited value descriptor)

get

get

Return a list of readings with an associated value descriptor of the UoM label specified, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return a list of readings with an associated value descriptor of the UoM label specified, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: (integer)

    exceed max limit)

  • uomLabel: (string)

    Unit of Measure label (UoMLabel) matching the ValueDescriptor associated to the reading

HTTP status code 200

list of matching readings having value descriptor with UoM label specified

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource (by label)

example - http://localhost:48080/api/v1/reading/label/hvac/10 (where hvac is a label on an associated value descriptor)

get

get

Return a list of readings with an associated value descriptor of the label specified, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return a list of readings with an associated value descriptor of the label specified, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: (integer)

    maximum number of readings to return (must not exceed max limit)

  • label: (string)

    label that should be in matching Value Descriptor's label array

HTTP status code 200

list of matching readings having value descriptor with the associated label. Could be an empty list if none match.

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource (by value data type)

example - http://localhost:48080/api/v1/reading/type/F/10 (where F, which is IoTtype for float, is in the type for an associated value descriptor)

get

get

Return a list of readings with an associated value descriptor of the type (IoTType) specified, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return a list of readings with an associated value descriptor of the type (IoTType) specified, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: (integer)

    maximum number of readings to be allowed to be returned

  • type: (string)

    an IoTType in string form (one of I, B, F, S for integer, Boolean, Floating point or String)

HTTP status code 200

list of matching readings having value descriptor of the types specified. Could be an empty list if none match.

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Reading Resource (by creation time)

example - http://localhost:48080/api/v1/reading/1471806984000/14718069900000/10

get

get

Return a list of readings between two timestamps - limited by the number specified in the limit parameter, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return a list of readings between two timestamps - limited by the number specified in the limit parameter, sorted by the readings modified date. Newest readings are at the top of list. LimitExceededException (HTTP 413) if the number of readings exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • limit: (integer)

    maximum number of readings to be allowed to be returned

  • start: (integer)

    millisecond (long) timestamp of the beginning of the time

  • end: (integer)

    millisecond (long) timestamp of the end of the time rage

HTTP status code 200

list of matching readings in this range (limited by the limit parameter)

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core device/sensor reading","title":"reading","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"pushed":{"type":"integer","required":false,"title":"pushed"},"name":{"type":"string","required":false,"title":"name"},"value":{"type":"string","required":false,"title":"value"}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1485364896983,"modified":1485364896983,"origin":1471806386919,"pushed":0,"name":"temperature","value":"38","device":"livingroomthermostat"}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 413

if the number of readings exceeds the current max limit.

HTTP status code 500

for unknown or unanticipated issues.

Value Descriptor Resource

example - http://localhost:48080/api/v1/valuedescriptor

post put get

post

Add a new ValueDescriptor whose name must be unique. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the a formatting string of the value descriptor is not a valid printf format.

put

Update the ValueDescriptor identified by the id or name in the object provided. Id is used first, name is used second for identification purposes. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the a formatting string of the value descriptor is not a valid printf format. NotFoundException (404) if the value descriptor cannot be located by the identifier.

get

Return all ValueDescriptor objects. LimitExceededException (HTTP 413) if the number of value descriptors exceeds the current max limit. ServiceException (HTTP 500) for unknown or unanticipated issues.

Add a new ValueDescriptor whose name must be unique. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the a formatting string of the value descriptor is not a valid printf format.

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core and MetaData value descriptor - describes device/sensor data sent and received","title":"valueDescriptor","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"min":{"type":"string","required":false,"title":"min"},"max":{"type":"string","required":false,"title":"max"},"type":{"type":"string","required":false,"title":"type"},"uomLabel":{"type":"string","required":false,"title":"uomLabel"},"defaultValue":{"type":"string","required":false,"title":"defaultValue"},"formatting":{"type":"string","required":false,"title":"formatting"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false}}}

Example:

{"name":"temperature","description":"test description", "min":"-40","max":"140","type":"F","uomLabel":"degree cel","defaultValue":"0","formatting":"%s","labels":["temp","hvac"]}

HTTP status code 200

database generated id of the new ValueDescriptor

HTTP status code 400

request is invalid or unparseable

HTTP status code 409

if the a formatting string of the value descriptor is not a valid printf format or if the name is determined to not be unique with regard to other value descriptors.

HTTP status code 500

for unknown or unanticipated issues

Value Descriptor Resource (by id)

example - http://localhost:48080/api/v1/valuedescriptor/id/5f79f674-a25e-44e6-bab0-1cc687420e40

delete

delete

Remove the ValueDescriptor designated by database generated identifier. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the value descriptor is still referenced in Readings. NotFoundException (404) if the value descriptor cannot be located by the identifier.

Remove the ValueDescriptor designated by database generated identifier. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the value descriptor is still referenced in Readings. NotFoundException (404) if the value descriptor cannot be located by the identifier.

URI Parameters

  • id: (string)

    Value descriptor database generated id

HTTP status code 200

boolean indicating success of the remove operation

HTTP status code 400

id is invalid or unparseable

HTTP status code 404

if the value descriptor cannot be located by the identifier.

HTTP status code 409

if the value descriptor is still referenced in Readings

HTTP status code 500

for unknown or unanticipated issues

Value Descriptor Resource (by name)

example - http://localhost:48080/api/v1/valuedescriptor/name/temperature (where temperature is the unique name of a value descriptor)

get delete

get

Return ValueDescriptor object with given name. Could be null if no value descriptors found by the name (name is unique across all value descriptors). NotFoundException (HTTP 404) if the value descriptor cannont be found by nmee. ServiceException (HTTP 500) for unknown or unanticipated issues.

delete

Remove the ValueDescriptor designated by name. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the value descriptor is still referenced in Readings. NotFoundException (404) if the value descriptor cannot be located by the identifier.

Return ValueDescriptor object with given name. Could be null if no value descriptors found by the name (name is unique across all value descriptors). NotFoundException (HTTP 404) if the value descriptor cannont be found by nmee. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • name: (string)

    Unique name of the value descriptor

HTTP status code 200

ValueDescriptor having the provided name, could be null if none are found.

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core and MetaData value descriptor - describes device/sensor data sent and received","title":"valueDescriptor","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"min":{"type":"string","required":false,"title":"min"},"max":{"type":"string","required":false,"title":"max"},"type":{"type":"string","required":false,"title":"type"},"uomLabel":{"type":"string","required":false,"title":"uomLabel"},"defaultValue":{"type":"string","required":false,"title":"defaultValue"},"formatting":{"type":"string","required":false,"title":"formatting"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false}}}

Example:

{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1471806386919,"modified":1471806467057,"origin":0,"name":"temperature","description":"test description","min":"-100","max":"200","type":"F","uomLabel":"degree cel","defaultValue":"0","formatting":"%s","labels":["temp","hvac"]}

HTTP status code 400

request is invalid or unparseable

HTTP status code 404

if the value descriptor cannot be located by the name

HTTP status code 500

for unknown or unanticipated issues.

Remove the ValueDescriptor designated by name. ServiceException (HTTP 500) for unknown or unanticipated issues. DataValidationException (HTTP 409) if the value descriptor is still referenced in Readings. NotFoundException (404) if the value descriptor cannot be located by the identifier.

URI Parameters

  • name: (string)

    Unique name of the value descriptor

HTTP status code 200

boolean indicating success of the remove operation

HTTP status code 400

request is invalid or unparseable

HTTP status code 404

if the value descriptor cannot be located by the identifier

HTTP status code 409

if the value descriptor is still referenced in Readings

HTTP status code 500

for unknown or unanticipated issues.

Value Descriptor Resource (by id)

example - http://localhost:48080/api/v1/valuedescriptor/5f79f674-a25e-44e6-bab0-1cc687420e40

get

get

Fetch a specific ValueDescriptor by its database generated id. NotFoundException (HTTP 404) if the value descriptor cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues

Fetch a specific ValueDescriptor by its database generated id. NotFoundException (HTTP 404) if the value descriptor cannot be found by id. ServiceException (HTTP 500) for unknown or unanticipated issues

URI Parameters

  • id: (string)

    database generated id for the value descriptor

HTTP status code 200

ValueDescriptor

HTTP status code 404

if the value descriptor cannot be located by the identifier

HTTP status code 500

for unknown or unanticipated issues

Value Descriptor Resources associated to the device identified by name

example - http://localhost:48080/api/v1/valuedescriptor/devicename/hallthermostat (where hallthermostat is the name of a device)

get

get

Fetch all ValueDescriptors that are associated to a Device's command set as either a put command parameter name or get/put response expected value. NotFoundException (HTTP 404) if the Device cannot be found by name. ServiceException (HTTP 500) for unknown or unanticipated issues

Fetch all ValueDescriptors that are associated to a Device's command set as either a put command parameter name or get/put response expected value. NotFoundException (HTTP 404) if the Device cannot be found by name. ServiceException (HTTP 500) for unknown or unanticipated issues

URI Parameters

  • name: required (string)

    unique name of the device

HTTP status code 200

list of ValueDescriptors

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core and MetaData value descriptor - describes device/sensor data sent and received","title":"valueDescriptor","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"min":{"type":"string","required":false,"title":"min"},"max":{"type":"string","required":false,"title":"max"},"type":{"type":"string","required":false,"title":"type"},"uomLabel":{"type":"string","required":false,"title":"uomLabel"},"defaultValue":{"type":"string","required":false,"title":"defaultValue"},"formatting":{"type":"string","required":false,"title":"formatting"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1471806386919,"modified":1471806467057,"origin":0,"name":"temperature","description":"test description","min":"-100","max":"200","type":"F","uomLabel":"degree cel","defaultValue":"0","formatting":"%s","labels":["temp","hvac"]}]

HTTP status code 400

if the request is malformed or unparsable

HTTP status code 404

if the device cannot be found by the name provided

HTTP status code 500

for unknown or unanticipated issues.

Value Descriptor Resources associated to the device identified by id

example - http://localhost:48080/api/v1/valuedescriptor/deviceid/5f79f674-a25e-44e6-bab0-1cc687420e40 (where 5f79f674-a25e-44e6-bab0-1cc687420e40 is the id of a device)

get

get

Fetch all ValueDescriptors that are associated to a Device's command set as either a put command parameter name or get/put response expected value. NotFoundException (HTTP 404) if the Device cannot be found by name. ServiceException (HTTP 500) for unknown or unanticipated issues

Fetch all ValueDescriptors that are associated to a Device's command set as either a put command parameter name or get/put response expected value. NotFoundException (HTTP 404) if the Device cannot be found by name. ServiceException (HTTP 500) for unknown or unanticipated issues

URI Parameters

  • id: required (string)

    database generated id of the device

HTTP status code 200

list of ValueDescriptors

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core and MetaData value descriptor - describes device/sensor data sent and received","title":"valueDescriptor","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"min":{"type":"string","required":false,"title":"min"},"max":{"type":"string","required":false,"title":"max"},"type":{"type":"string","required":false,"title":"type"},"uomLabel":{"type":"string","required":false,"title":"uomLabel"},"defaultValue":{"type":"string","required":false,"title":"defaultValue"},"formatting":{"type":"string","required":false,"title":"formatting"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1471806386919,"modified":1471806467057,"origin":0,"name":"temperature","description":"test description","min":"-100","max":"200","type":"F","uomLabel":"degree cel","defaultValue":"0","formatting":"%s","labels":["temp","hvac"]}]

HTTP status code 400

if the request is malformed or unparsable

HTTP status code 404

if the device cannot be found by the id provided

HTTP status code 500

for unknown or unanticipated issues.

Value Descriptor Resource (by unit of measure)

example - http://localhost:48080/api/v1/valuedescriptor/uomlabel/degree cel (where degree cel is the UoM for value descriptors)

get

get

Return ValueDescriptor objects with given UoM label. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return ValueDescriptor objects with given UoM label. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • uomLabel: (string)

    unit of measure

HTTP status code 200

list of ValueDescriptor matching UoM Label

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core and MetaData value descriptor - describes device/sensor data sent and received","title":"valueDescriptor","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"min":{"type":"string","required":false,"title":"min"},"max":{"type":"string","required":false,"title":"max"},"type":{"type":"string","required":false,"title":"type"},"uomLabel":{"type":"string","required":false,"title":"uomLabel"},"defaultValue":{"type":"string","required":false,"title":"defaultValue"},"formatting":{"type":"string","required":false,"title":"formatting"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1471806386919,"modified":1471806467057,"origin":0,"name":"temperature","description":"test description","min":"-100","max":"200","type":"F","uomLabel":"degree cel","defaultValue":"0","formatting":"%s","labels":["temp","hvac"]}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 500

for unknown or unanticipated issues.

Value Descriptor Resource (by label)

example - http://localhost:48080/api/v1/valuedescriptor/label/hvac (where hvac is one of the labels for value descriptors)

get

get

Return ValueDescriptor objects with given label. ServiceException (HTTP 500) for unknown or unanticipated issues.

Return ValueDescriptor objects with given label. ServiceException (HTTP 500) for unknown or unanticipated issues.

URI Parameters

  • label: (string)

    tag or label

HTTP status code 200

list of ValueDescriptor matching UoM Label

Body

Type: application/json

Schema:

{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Core and MetaData value descriptor - describes device/sensor data sent and received","title":"valueDescriptor","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"min":{"type":"string","required":false,"title":"min"},"max":{"type":"string","required":false,"title":"max"},"type":{"type":"string","required":false,"title":"type"},"uomLabel":{"type":"string","required":false,"title":"uomLabel"},"defaultValue":{"type":"string","required":false,"title":"defaultValue"},"formatting":{"type":"string","required":false,"title":"formatting"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false}}}

Example:

[{"id":"5f79f674-a25e-44e6-bab0-1cc687420e40","created":1471806386919,"modified":1471806467057,"origin":0,"name":"temperature","description":"test description","min":"-100","max":"200","type":"F","uomLabel":"degree cel","defaultValue":"0","formatting":"%s","labels":["temp","hvac"]}]

HTTP status code 400

request is invalid or unparseable

HTTP status code 500

for unknown or unanticipated issues.

Value Descriptor Usage

Determines if value descriptors are currently in use. This API does not provide any guarantee that the value descriptor will not be in use in the near future and extra measure should be taken to ensure no race conditions exist.

get

get

Get a list of value descripors and usage state. True if the value descriptor is in use and should not be modified. Otherwise, false.

Ping Resource

example - http://localhost:48080/api/v1/ping

get

get

Test service providing an indication that the service is available.

Config Resource

Example - http://localhost:48080/api/v1/config

get

get

Fetch the current state of the service's configuration.

Edgex API Version

Example - http://localhost:48080/api/version

get

get

Get the API version