Home › APIs › Scheduling and Management Segment

Scheduling and Management Segment

What is a Scheduling and Management Segment?

A Scheduling and Management Segment supports supports management of physical hardware and content schedules (i.e. which content items are played where, and when).

Overview

The Scheduling and Management Segment API provides 2 resources with a total of 5 methods:

Display Management
GET /displays List displays and their capabilities.
POST /displays Register information on displays and their capabilities.

 

Schedule Management
GET /schedule/<id>/ Get a Content Descriptor Set (CDS) representing the schedule described by the specified ID.
POST /schedule/<id>/subscribe/ Request that subscription record is created in order to provide schedule updates to the caller.
POST /schedule/<id>/unsubscribe/ Request that a subscription record is removed.

Each of the Display Management endpoints supports JSON as both the request and response format; XML formatted requests and responses are not supported.

The Schedule Management endpoints supports JSON as the request format; XML requests are not supported. The “get schedule” method (“/schedule/”) provides only an XML response, JSON responses are not supported by this method.

Display Management

This resource provides two methods:

 

List displays

GET /displays List displays and their capabilities.

POST parmeters

url-only optional If “url-only” is true, the response will included only the location and a URL at which more information can be sought (i.e. the URL of the “Get Info” method for the display segment); if “url-only” is false, all known information about the display will be sent in the response. If a “url-only” parameter is not included in the request, its value will default to true.

Request headers

None specified.

Response

Possible response status codes:

  • 200 — OK.
Response fields
url string A URL at which information on the display may be acquired. This should correspond to the url of the “Get Info” method for the display segment.
location object An JSON object describing the location of the display.

The following additional response fields will only be returned if the “url-only” request parameter was set to false.

name string A user-friendly name for the display. This may not uniquely identify the display.
sensors object A list of JSON sensor objects representing the context sources available at a display. This should correspond to the output of the “Get Info” method for the display segment.

Examples

Two examples:

 

List displays

request

Accept: application/json

response

200 (OK)
    Content-Type: application/json
[
    {
        "name": "PD Display 1",
        "url": "http://pd-display1.pd-net.org/api",
    },
    {
        "name": "PD Display 2",
        "url": "http://pd-display2.pd-net.org/api",
    }
]
List displays and their capabilities

request

Accept: application/json
{
    "url-only" : false,
}

response

200 (OK)
    Content-Type: application/json
[
    {
        "name": "PD Display 1",
        "location": {
            "latitude" : "N 50° 43.449",
            "longitude" : "W 002° 03.115",
        },
        "sensors": [
            {
                "sensor-id": "ac:bc:e8:42:f9",
                "sensor-type": "air temperature",
            },
            {
                "sensor-id": "e8:42:f9:ac:bc",
                "sensor-type": "video stream",
            },  
        ],
        "url": "http://pd-display1.pd-net.org/api",
    },
    {
        "name": "PD Display 2",
        "location": {
            "latitude" : "N 27.174799",
            "longitude" : "E 78.042111",
        },
        "sensors": [
            {
                "sensor-id": "a1:23:bc:de:45",
                "sensor-type": "light",
            },
        ],
        "url": "http://pd-display2.pd-net.org/api",
    }
]

 

Register displays

POST /displays Register information on displays and their capabilities.

POST parmeters

url required A URL at which information on the display may be acquired. This should correspond to the url of the “Get Info” method for the display segment.
location required An JSON object describing the location of the display.

Request headers

None specified.

Response

Possible response status codes:

  • 201 — Created.
Examples

request

Content-Type: application/json
{
    "url": "http://pd-display1.pd-net.org/api",
    "location": {
        "latitude" : "N 50° 43.449",
        "longitude" : "W 002° 03.115",
    },
}

response

201 (Created)
    Content-Type: application/json
{}

Schedule Management

This resource provides three methods:

Get Schedule

GET /schedule/<id>/ Get a Content Descriptor Set (CDS) representing the schedule described by the specified ID.

Resource URI

The URI includes the following parameter:

id required An identifier for the schedule.
Sample URIs

The following URI includes an id of “pd-playlist-1”:
http://www.pd-content-management.com/schedule/pd-playlist-1/

Request headers

None specified.

Response

Possible response status codes:

  • 200 — OK.
Response fields

The response XML will be a valid Content Descriptor Set (CDS).

Examples

Coming soon…

Subscribe

POST /schedule/<id>/subscribe/ Request that subscription record is created in order to provide schedule updates to the caller.

Resource URI

The URI includes the following parameter:

id required An identifier for the schedule.
Sample URIs

The following URI includes an id of “pd-playlist-1”:
http://www.pd-content-management.com/schedule/pd-playlist-1/subscribe/

POST parameters

subscriber-uri string The URI to which sensor updates should be posted. Updates posted to the URL will be Content Descriptor Set (CDS) XML, which is valid request data for the Display Segement‘s “Request content scheduling” 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 /schedule/<id>/unsubscribe/ Request that a subscription record is removed.

Resource URI

The URI includes the following parameter:

id required An identifier for the schedule.
Sample URIs

The following URI includes an id of “pd-playlist-1”:
http://www.pd-content-management.com/schedule/pd-playlist-1/unsubscribe/

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)
{
}