Difference between revisions of "REST Push API"

From A-SMIL.org
Jump to: navigation, search
Line 3: Line 3:
 
You may push SMIL scripts and media files into a player using a [http://en.wikipedia.org/wiki/Representational_state_transfer REST] API as documented below.
 
You may push SMIL scripts and media files into a player using a [http://en.wikipedia.org/wiki/Representational_state_transfer REST] API as documented below.
  
−
== Naming ==
+
= Naming =
  
 
The REST API can be accessed via prefix
 
The REST API can be accessed via prefix
Line 21: Line 21:
 
  grant_type=password&username=...
 
  grant_type=password&username=...
  
−
== Authentication ==
+
= Authentication =
  
 
Before a remote client can access the player, it must authenticate itself by providing the access password set in the player.
 
Before a remote client can access the player, it must authenticate itself by providing the access password set in the player.
  
−
=== POST oauth2/token ===
+
== POST oauth2/token ==
  
 
Request an access token for API calls.
 
Request an access token for API calls.
Line 63: Line 63:
 
|}
 
|}
  
−
== Media Transfer ==
+
= Media Transfer =
  
−
=== POST files/new ===
+
== POST files/new ==
  
 
Create a file under ''<nowiki>http://(device_ip):8080/user-data</nowiki>'' download path
 
Create a file under ''<nowiki>http://(device_ip):8080/user-data</nowiki>'' download path
Line 132: Line 132:
 
|}
 
|}
  
−
=== POST files/(id)===
+
== GET files/(id)==
 +
 
 +
Get file information
 +
 
 +
'''Input (JSON or multi-part form)'''
 +
 
 +
None
 +
 
 +
'''Output (JSON)'''
 +
 
 +
''FileResource'' structure
 +
 
 +
== POST files/(id)==
  
 
Modify a file
 
Modify a file
Line 169: Line 181:
 
''FileResource'' structure
 
''FileResource'' structure
  
−
=== POST files/delete ===
+
== POST files/find ==
 +
 
 +
List files on the system
 +
 
 +
'''Input (JSON or multi-part form)'''
 +
 
 +
{| class="wikitable" border="1"
 +
|-
 +
! Parameter
 +
! Function
 +
|-
 +
| access_token
 +
| Access token returned from ''oauth2/token''
 +
|-
 +
| maxResults
 +
| (Optional) Max number of file records to return
 +
|-
 +
| pageToken
 +
| (Optional) Continuation record
 +
|-
 +
| query
 +
| (Optional) Reserved
 +
|}
 +
 
 +
'''Output (JSON)'''
 +
 
 +
{| class="wikitable" border="1"
 +
|-
 +
! Parameter
 +
! Function
 +
|-
 +
| nextPageToken
 +
| null of an identifier for report continuation
 +
|-
 +
| items
 +
| Array of ''FileResource'' structures
 +
|}
 +
 
 +
== POST files/delete ==
  
 
Delete a file
 
Delete a file
Line 190: Line 240:
  
 
None
 
None
 +
 +
== GET (downloadPath) ==
 +
 +
Retrieve a file

Revision as of 06:16, 17 October 2012

Applies to: IAdea XMP-2200, XMP-2300 media appliances

You may push SMIL scripts and media files into a player using a REST API as documented below.

Naming

The REST API can be accessed via prefix 

http://(device_ip):8080/v2/

appended by API call. For example, for API 

POST oauth2/token

the actual HTTP request should be sent to (device_ip) at port 8080, with content similar to: 

POST /v2/oauth2/token HTTP/1.1
Host: (device_ip)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=password&username=...

Authentication

Before a remote client can access the player, it must authenticate itself by providing the access password set in the player.

POST oauth2/token

Request an access token for API calls.

Input (Multi-part form)

Parameter Function
grant_type Must be "password"
username User name requesting access. Device default value is "admin"
password Password. Device default value is the empty string ""

Output (JSON)

Parameter Function
access_token Authorization token for further API access
token_type Always "Bearer"
expires_in Number of seconds before the access_token expires

Media Transfer

POST files/new

Create a file under http://(device_ip):8080/user-data download path

Input (JSON or multi-part form)

Parameter Function
access_token Access token returned from oauth2/token
downloadPath Path of file, must start with prefix /user-data/
data (Optional) File encoded in multipart/form-data
fileSize (Required except when data is provided) Size of file; if provided file can be uploaded in separate chunks
etag (Optional) User-supplied unique string for version identification; default empty string
mimeType (Optional) MIME type of the file; default empty string
modifiedDate (Optional) ISO8601-encoded date time string indicating modified date time; default empty string

Output (JSON)

FileResource structure:

Parameter Function
id String for identifying the file in subsequent operations
downloadPath Path of file to append after http://(device_ip):8080
fileSize Size of file
etag Unique string for version identification
mimeType MIME type of the file
modifiedDate ISO8601-encoded date time string indicating modified date time; default empty string
transferredSize Size uploaded into the player
completed Boolean (true or false) indicating whether file upload has completed

GET files/(id)

Get file information

Input (JSON or multi-part form)

None

Output (JSON)

FileResource structure

POST files/(id)

Modify a file

Input (JSON or multi-part form)

Parameter Function
access_token Access token returned from oauth2/token
seek (Optional) Offset from beginning of file to replace data. Default 0
data (Optional) File encoded in multipart/form-data
downloadPath Path of file, must start with prefix /user-data/
etag (Optional) User-supplied unique string for version identification; default empty string
mimeType (Optional) MIME type of the file; default empty string
modifiedDate (Optional) ISO8601-encoded date time string indicating modified date time; default empty string

Output (JSON)

FileResource structure

POST files/find

List files on the system

Input (JSON or multi-part form)

Parameter Function
access_token Access token returned from oauth2/token
maxResults (Optional) Max number of file records to return
pageToken (Optional) Continuation record
query (Optional) Reserved

Output (JSON)

Parameter Function
nextPageToken null of an identifier for report continuation
items Array of FileResource structures

POST files/delete

Delete a file

Input (JSON or multi-part form)

Parameter Function
access_token Access token returned from oauth2/token
id ID string of file returned by files/new

Output (JSON)

None

GET (downloadPath)

Retrieve a file

Retrieved from "https://www.a-smil.org/index.php?title=REST_Push_API&oldid=346"