Home › APIs › Environment Segment

Environment Segment

What is an Environment Segment?

A Environment Segment supports the collection and distribution of environmental and contextual data (e.g. sensors).

Overview

The Environment Segment API provides one resource with 3 methods:

Data Acquisition
GET / Lists the current value of the sensor.
POST /subscribe Request that a sensor creates a subscription record in order to provide regular sensor data updates to the caller.
POST /unsubscribe Request that a sensor removes a subscription record.

Each endpoint supports JSON as both the request and response format. XML formatted requests and responses are not supported.

Data Acquisition

This resource provides three methods:

 

Get Value

GET / Lists the current value of the sensor.

Request Headers

None specified.

Response

Possible response status codes:

  • 200 – OK.
Response fields:
sensor-id string The unique string identifier for this sensor.
sensor-type string A string description of the functional class of sensor (e.g. “air temperature”). MUST be sent with the first message sent by a sensor, optional thereafter.

Exactly one of the following two additional response fields will also be returned.

data various The sensor reading.
data-source string A URI from which the data can be read.

Examples

request

Accept: application/json

response

200 (OK)
{
    "data": "23.2",
    "sensor-id": "ac:bc:e8:42:f9",
    "sensor-type": "air temperature",
}

Subscribe

POST /subscribe Request that a sensor creates a subscription record in order to provide regular sensor data updates to the caller.

 

POST parameters

subscriber-uri string The URI to which sensor updates should be posted. Updates posted to the URL will be valid request data for the Display Segement‘s “Provide Content Data” API call.

Request Headers

None specified.

Response

Possible response status codes:

  • 201 — Created.

Examples

request

Content-Type: application/json
Accept: application/json
{
    "subscriber-uri": "http://pd-display2.pd-net.org/api/sensing",
}

response

201 (Created)
{
}

Unsubscribe

POST /unsubscribe Request that a sensor removes a subscription record.

 

POST parameters

subscriber-uri string The subscriber-uri sent in the original subscribe call.

Request Headers

None specified.

Response

Possible response status codes:

  • 200 — OK.

Examples

request

Content-Type: application/json
Accept: application/json
{
    "subscriber-uri": "http://pd-display2.pd-net.org/api/sensing",
}

response

200 (OK)
{
}