REST-API Reference

This REST-API reference focuses on garlic-player, but it also works with the Android-based media player from IAdea. Some results may vary.

Authentication

Every API call requires a token to be passed as a GET parameter. This section of the authentication explains how to obtain the token.

Input parameter description for /v2/oauth2/token
Parameter	Function
grant_type	Must be the string “password”, currently
username	Username requesting access, admin by default
password	Password is currently not supported

Output parameter description for /v2/oauth2/token
Parameter	Function
access_token	This is the authorization token you need to use for every other API call. You must send it as a GET parameter.
expires_in	An ISO date of the time, when the token expires.
token_type	Bearer is default

You will find an example how to use the authentication in the Introduction Tutorial.

Handling of Media Files

For working with media files, we have the typical CRUD (creation, read, update, and delete) functions. In our cases, the “C” for create is equal to upload.

Create: Upload a Media via files/new

JSON and multipart form are supported

Input parameter description for /v2/files/new
Parameter	Function
downloadPath	Path of media file. In IAdea player, it must start with prefix /user-data/. Garlic-player put the files in the cache directory.
data	File encoded in multipart/form-data
fileSize	Size of file

Out parameter in JSON
Parameter	Function
completed	Boolean (true or false) describes if the file upload is complete. If it is not completed, look at the transferredSize parameter.
id	The unique identification for the file
downloadPath	Path of file. In garlic-player, this is the cache directory.
fileSize	Size of file
modifiedDate	ISO8601-encoded date time string indicating modified date time; default is an empty string.
transferredSize	Size uploaded

Read: Find Files

The 'find' API command lists the media files paginated as JSON.

Input (JSON or multipart form) for files/find
Parameter	Function
maxResults	(Optional) Max number of file records to return
pageToken	(Optional) Continuation record

If you do not enter an input parameter, all files in the cache directory will be shown.

Output as JSON
Parameter	Function
nextPageToken	null of an identifier for report continuation
items	Array of a so-called FileResource structure described in ID

Get ID to read

This is a GET request. It requires the ID as directory and the token in this URI form: http://your_device_ip:8080/v2/files/ID?access_token=YOUR_ACCESS_TOKEN

Output of the as JSON as FileResource structure
Parameter	Function
id	String for identifying the file in subsequent operations
downloadPath	Path of file. This is normally the cache directory of the player.
fileSize	Size of file in byte
etag	Unique string for version identification. This is identically with the ID.
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.

Update: Edit a media file record

These are the same parameters as in upload media.

Input parameter description for /v2/files/ID
Parameter	Function
downloadPath	Path of media file. In IAdea player, it must start with prefix /user-data/. Garlic-player put the files in the cache directory.
data	File encoded in multipart/form-data
fileSize	Size of file

The output is the FileResource structure.

Delete Media File

To delete a media, you need the parameter in body as JSON or multipart form.

Input parameter for /v2/files/delete
Parameter	Function
id	String for identifying the file in subsequent operations

The response is an HTTP 200 OK if succeeded.

Playback functions

The playback function handles the set and switch to a specific SMIL-Index as Content-URL. Furthermore, you can trigger an instant display of a media via REST-API.

Set Default Content-URL

Setting a new SMIL-index as Content-URL. The current displayed index will not be interrupted. On a reboot or restart, the new set Content-URL will be used.

Input parameter description for /v2/app/start
Parameter	Function
uri	Location of content. URI can be: https://domain.tld/index.smil
packageName	Optional and currently not used with garlic-player. For IAdea: On Android, it can be package to launch.
className	Optional and currently not used with garlic-player. For IAdea: On Android, it can be a class-name to launch.
action	Optional and currently not used with garlic-player. For IAdea: On Android, it can be an action.
type	Optional and currently not used with garlic-player. For IAdea: On Android, it can be a type.
extras	Optional and currently not used with garlic-player. For IAdea: On Android, it can be extra parameters for intents.

Out parameter as JSON
Parameter	Function
uri	Location of content. URI can be: https://domain.tld/index.smil
packageName	Optional and currently not used with garlic-player. For IAdea: On Android, it can be package to launch.
className	Optional and currently not used with garlic-player. For IAdea: On Android, it can be a class-name to launch.
action	Optional and currently not used with garlic-player. For IAdea: On Android, it can be an action.
type	Optional and currently not used with garlic-player. For IAdea: On Android, it can be a type.

Execute a SMIL-Index once

Setting a new SMIL-index as Content-URL and play it once. Then jump back to the default Content-URL.

The input and output parameter for /v2/app/exec are the same as /v2/app/start.

Switch to set Content-URL

This command causes the player switching to the default Content-URL.

Input parameter description for /v2/app/switch
Parameter	Function
mode	Currently, the only supported value is “start”

The output parameter for /v2/app/switch are the same as /v2/app/start

Network Trigger via notify

This is a trigger event for jumping to a previous set network trigger via notify in begin or end attribute.

Input parameter description for /v2/task/notify
Parameter	Function
smilEvent	The name of the trigger point set in notify(). In our tutorial, it is play0001 or play0001.

The response is an HTTP 200 OK if succeeded.

System Management

Reboot

This reboots the operating system immediately. For garlic-player, this works already only on Android. OS related functions require a small helper app. In this case, the garlic-launcher. For Linux, garlic-daemon with similar functions is currently under development.

For /v2/task/reboot, no special input parameter is required. The play reboots instantly, so expect no response.

Screenshot

A secure digital signage player should avoid complex managing apps like team viewer. But in some cases it is necessary to see what is displayed on screen. This is possible with the screenshot API call.

For /v2/task/screenshot, no special input parameter is required. The response is a JPEG image like described in the REST-API introduction.

System Information

This REST-API calls are based on GET and give you some detailed information.

Get Information about the Model

The call is GET so: http://your_device_ip:8080/v2/system/modelInfo?access_token=YOUR_ACCESS_TOKEN

Out parameter as JSON can be empty
Parameter	Function
PCB	Name of the Printed Circuit Board or player app
PCBRevision	Revision of the Printed Circuit Board
licenseModel	Specified license or name of the operating system
manufacturer	Manufacturer name or software author
manufacturerURL	The URL to the manufacturer or the player software
modelDescription	Additional descriptions of the board model
modelName	Additional descriptions of the board model
modelDescription	Additional descriptions of the board model
modelName	Name of the device model
modelURL	URL of the device manufacturer
options	Additional options of the model, e.g. sensors

Get Information about the Firmware

The call is GET so: http://your_device_ip:8080/v2/system/firmwareInfo?access_token=YOUR_ACCESS_TOKEN

Out parameter as JSON
Parameter	Function
family	Product model family, like “garlic-player-android”
firmwareVersion	Firmware version of the device and player software version