Client (HHP) to TV Application Communication

REST Interface

The communication path from the client device (HHP) to the TV application is provided via the REST interface. The following calls are designed to be a generic set of communication APIs that allow developers to define the content of the messages, while providing a structured protocol easily understood by the server (TV).

Each of the following requests includes a URI that contains an {appID}, which is required to communicate with the corresponding TV application.

Note: appID is an unique TV application ID issued by Samsung Apps.

REST URIs

Resource

Operation

HTTP method and URI

Application methods

Get application info

GET /ws/app/{appID}/info

Connect to application

POST /ws/app/{appID}/connect

Disconnect from application

POST /ws/app/{appID}/disconnect

Message Queue methods

Send message

POST /ws/app/{appID}/queue
POST /ws/app/{appID}/queue/device/{deviceID}
POST /ws/app/{appID}/queue/group/{groupID}

Receive message

GET /ws/app/{appID}/queue/device/{deviceID}

Device group methods

Join group

POST /ws/app/{appID}/queue/group/{groupID}/join

Leave group

POST /ws/app/{appID}/queue/group/{groupID}/leave

List members

GET /ws/app/{appID}/queue/group/{groupID}

File upload methods

Upload file to widget

POST /ws/app/{appID}/queue

Request Headers

Header

Description

Required

SLDeviceID

This header contains the DeviceID used to identify the client device and the corresponding TV application.

YES (for ALL requests except Get Application Info request)

Content-type

This header refers to the content type of the request. The value for this header can be either JSON or XML.

YES (for POST requests only)

ProductID

This header is only required for Device Connect requests.

The value MUST begin with "SMART" and be exactly 8 characters long.

Example: SMARTTVI,SMARTDev

YES (for Connect requests only)

VendorID

This header is only required for Device Connect requests.

The value must be exactly 8 characters long.

YES (for Connect requests only)

DeviceName

This header is only required for Device Connect requests.

This header contains the name of the client device. The value MUST be less than 64 characters long.

YES (for Connect requests only)

User-Agent

This header is used by the TV to identify the type of the client device and its capabilities.

YES (for ALL requests)

Custom (User-Defined)

The developer can add any other headers needed for proper performance of their application. Any custom headers added to a request are included as the second parameter in the message context (JSON object)

NO

Application Methods

Get Application Info

This request retrieves the following information related to the application ID included in the request.

This is a system message and the message format is predefined in JSON format.

HTTP method and URI
GET /ws/app/{appID}/info

Syntax

Request type:     GET 
URI:     /ws/app/{appID}/info

Return value

200 OK
404 Not found
Body: Widget information presented as JSON.
For example:
{"widgetInfo":{"ID": "sampleWidget","Version":"0.930", "Status":"RUNNING","widgetname":"sampleWidget"}}

Parameter

appID (Application ID)

Example

Sample request:
GET  /ws/app/sampleWidget/info  HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 192.168.1.108
Accept: */*

Sample response:
HTTP/1.1 200 OK
Content-type: text/html
Transfer-Encoding: chunked
Date: Thu, 14 Jul 2011 22:16:25 GMT
Server: lighttpd/1.4.28
{"widgetInfo":{"ID": "sampleWidget","Version":"0.930", "Status":"RUNNING","widgetname":"sampleWidget"}}

Connect to Application

This request initiates the connection between the client application and the TV application. Client must provide the following headers with the request:

HTTP method and URI
POST /ws/app/{appID}/connect

Syntax

Request Type:   POST 
URI:   /ws/app/{appID}/connect

Return value

200 OK (connection request is accepted)
403 Forbidden
404 Not found

Parameter

appID (Application ID)

Example

Sample request:
POST  /ws/app/sampleWidget/connect  HTTP/1.1
Accept: */*
Accept-Language: en-us
sldeviceid: 12345
vendorid: VenderMe
devicename: IE-Client
productid: SMARTDev
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: 127.0.0.1:8008
Content-Length: 0
Connection: Keep-Alive

Sample response:
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28

Disconnect from Application

This request disconnects the mobile application from the TV application.

HTTP method and URI
POST /ws/app/{appID}/disconnect

Syntax

Request type:   POST 
URI:    /ws/app/{appID}/disconnect

Return value

200 OK (disconnect request is accepted)

Parameter

appID (Application ID)

Example

Sample request:
POST  /ws/app/sampleWidget/disconnect  HTTP/1.1
Accept-Encoding: gzip, deflate
Accept-Language: en-us
sldeviceid: 12345
Accept: */*
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: 192.168.1.108
Content-Length: 0
Connection: Keep-Alive
Pragma: no-cache

Sample response:
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 01 Jan 1970 01:32:23 GMT
Server: lighttpd/1.4.28

Message Queue Methods

Each of the following requests is designed to communicate directly with the message queueing system on the TV. These REST APIs are limited to either pushing a message onto the queue or popping (removing) a message from the queue.

Message from Mobile App to TV App

This request pushes a TV application message onto the message queue in the TV. Any message sent to the following URI only goes to the TV application.

Note: The message body included in this request is determined by the developer of the application.

HTTP method and URI
POST /ws/app/{appID}/queue

Push message (to TV App): To send application data to TV App

Syntax

Request type:   POST 
URI:    /ws/app/{appID}/queue

Return value

200 OK (message sent to application)
403 Forbidden (client not allowed to send message to the requested application)
404 Not found (requested application does not exist)

Parameter

appID (Application ID)

Example

Sample request:
POST  /ws/app/sampleWidget/queue  HTTP/1.1
Accept: */*
Accept-Language: en-us
sldeviceid: 12345
Content-Type: application/json
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Host: 192.168.1.108
Content-Length: 56
{"type":"touchMove","coordinates":{"x":"343","y":"252"}}

Sample response:
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28

Pop Message

If the message queue is not empty, this request retrieves a message from the device's message queue on the TV. If the message queue is empty, this request is be held until the message arrives or the request times out (long polling). Status code 408 is returned upon long polling time out. The client must initiate another pop message request immediately when it receives 408.

HTTP method and URI
GET /ws/app/{appID}/queue/device/{deviceID}

Push message (from TV App): To get application data from TV App

Syntax

Request type:   GET 
URI:   /ws/app/{appID}/queue/device/{deviceID}

Return value

200 OK (message sent to application)
403 Forbidden (client not allowed to send message to the requested application)
404 Not found (requested application does not exist)
408 Time out (long polling time out)

Parameter

appID (Application ID)
deviceID (Device ID)

Example

Sample request:
GET /ws/app/sampleWidget/queue/device/12345 HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 127.0.0.1:8008
Accept: */*
SLDeviceID:12345

Sample response:
HTTP/1.1 200 OK
Content-type: text/html
sender: TV
Transfer-Encoding: chunked
Date: Fri, 15 Jul 2011 21:01:59 GMT
Server: lighttpd/1.4.28
{"type":"echo","coordinates":{"x":"343","y":"252"}}

Device Group Methods

Join Group

This request is sent to inform the TV that the device wants to join a particular group.

HTTP method and URI
POST /ws/app/{appID}/queue/group/{groupID}/join

Syntax

Request type:   POST 
URI:    /ws/app/{appID}/queue/group/{groupID}/join

Return value

200 OK (joining request accepted)
403 Forbidden (client does not have the permission to execute the specified operation)
404 Not found (requested group does not exist)

Parameter

appID (Application ID)
groupID (Group ID)
{groupID} corresponds to the group ID the client device wishes to join.

Example

Sample request:
POST  /ws/app/sampleWidget/queue/group/feigroup/join  HTTP/1.1
SLDeviceID:12345
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Content-Length: 0

Sample response:
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28

Leave Group

This request is sent to inform the TV that the device wants to leave a particular group.

HTTP method and URI
POST /ws/app/{appID}/queue/group/{groupID}/leave

Syntax

Request type:   POST 
URI:   /ws/app/{appID}/queue/group/{groupID}/leave

Return value

200 OK (leaving request accepted)
403 Forbidden (client does not have the permission to execute the specified operation)
404 Not found (requested group does not exist)

Parameter

appID (Application ID)
groupID (Group ID)
{groupID} corresponds to the group ID the client device wishes to leave.

Example

Sample request:
POST  /ws/app/sampleWidget/queue/group/feigroup/leave  HTTP/1.1
SLDeviceID:12345
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Content-Length: 0

Sample response:
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28

List Group Members

This request retrieves a list of all devices currently joined to a particular group.

HTTP method and URI
GET /ws/app/{appID}/queue/group/{groupID}

Syntax

Request type:   GET
URI:   /ws/app/{appID}/queue/group/{groupID}

Return value

200 OK (request is fulfilled and the result is in the body)
403 Forbidden (client does not have the permission to execute the specified operation)
404 Not found (requested group does not exist)
BODY

Parameter

appID (Application ID)
groupID (Group ID)

Example

Sample request:
GET /ws/app/sampleWidget/queue/group/sampleWidget HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 127.0.0.1:8008
Accept: */*
SLDeviceID:12345

Sample response:
HTTP/1.1 200 OK
Content-type: text/html
ACCEPT: */*
Transfer-Encoding: chunked
Date: Fri, 15 Jul 2011 21:10:10 GMT
Server: lighttpd/1.4.28
{"group":{"Devices":[{"SLDeviceID":"12345"},]}}

File Upload Methods

It is also possible to send files to the corresponding TV application. In these requests, the content type must be multipart form data. Multiple messages and files may be sent together. Each message has a separate callback on the TV application. Client devices can then access the uploaded files through the following URI: /ws/app/{appID}/file/{filename}.

The size limit for single uploaded file and total uploaded files is 3MB. All the uploaded files will be cleaned up when the TV application quits execution.

Upload File

This request sends a message containing the file data to the message queue on the TV.

Content type must be Multipart form data. Multiple messages and files can be sent together. Each message will be a separate callback on application. Files are saved and served through URI: /ws/app/{appID}/file/{filename}.

HTTP method and URI
POST /ws /app/{appID}/queue

Syntax

Request type:   POST
URI:   /ws/app/{appID}/queue

Return value

200 OK

Parameter

appID (Application ID)

Example

Sample request:
POST /ws/app/sampleWidget/queue HTTP/1.1
User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
Host: 192.168.1.108
Accept: */*
SLDeviceID:12345
Content-Length: 13774
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------c11447104fda
------------------------------c11447104fda
Content-Disposition: form-data; name="message"
{"type":"ShowPic", "filename":"UE-1.jpg"}
------------------------------c11447104fda
Content-Disposition: form-data; name="upload"; filename="UE-1.jpg"
Content-Type: image/jpeg
...
...
...

Sample response:
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 14 Jul 2011 3:32 PM
Server: lighttpd/1.4.28

Where to Go Next