RESTful API – TargetR Digital Signage Help

Note: Please refer to our documentation at swaggerhub. This development resource makes it easy to test and understand RESTful operations: TargetR Stacks REST API at SwaggerHub

Generic Object Structure

All objects follow a common structure.

{
    "id": "ABCEF1234567",
    "type": "object-type",
    "data": {
        "label": "My label",
        "version": "23",
        "createdMillis": "1404910684273",
        "modifiedMillis": "1412943312770",
    },
}

The id field is used to uniquely store and reference an object of a specific type. The data field references an inner object containing a map of name value pairs. Anything can be stored in this map and used in condition evaluation and for other purposes. All values in the data must be text strings, however, they will be dynamically cast to numbers and boolean values when condition evaluation is performed.

The data contains a label, a version number, created and modified dates in milliseconds since the epoc. Additional fields will vary depending on the object type. The quickest way to learn the additional fields and object structure is to click the "REST API" button in the data tab of objects within the admin interface.

RESTful Endpoints:

/rest-api/v1/screens - GET list of screens.
/rest-api/v1/screens/[SCREEN-ID] - GET, PUT and DELETE a specific screen.
/rest-api/v1/sequences - GET list of sequences. Or POST a new one.
/rest-api/v1/sequences/[SEQUENCE-ID] - GET, PUT and DELETE a specific sequence.
/rest-api/v1/libraryitems - GET list of library items. Or POST a new one.
/rest-api/v1/libraryitems/[LIBRARY-ITEM-ID] - GET, PUT and DELETE a specific library item.
/rest-api/v1/users - GET list of users. Or POST a new one.
/rest-api/v1/users/[USER-ID] - GET, PUT and DELETE a specific user.
/rest-api/v1/groups - GET list of groups. Or POST a new one.
/rest-api/v1/groups/[GROUP-ID] - GET, PUT and DELETE a specific group.
/rest-api/v1/serverconfigs - GET list of server configs. Or POST a new one. (Also known as cloud configs).
/rest-api/v1/serverconfigs/[SERVER-CONFIG-ID] - GET, PUT and DELETE a specific server config.
/rest-api/v1/op/[OPERATION] - POST a special operation command. For example instruct the system to re-encode a video.

Updates can only be performed on the items the authenticated user has access to. To control access to items, access controls are used and can be updated using the following endpoints:

/rest-api/v1/accesscontrol - GET list of access controls. Or POST a new one.
/rest-api/v1/accesscontrol/[ACTOR-ID]/[OBJECT-TYPE]/[OBJECT-ID] - DELETE an access control.

New objects can be created by a POST or PUT without including an ID for the new object. New objects will automatically create a new access control allowing the authenticated user to access it.

Access Controls are used to assign items to a Group. Each access control references the group and an item in the group. All users with access to the group have access to items in the group.

Searching by group

To search for members of a group, the group name or group ID can be added to the list request.

?groupName=[GROUP-NAME]
?groupId=[GROUP-ID]

For example, /rest-api/v1/libraryitems?groupName=mycustomgroup will return library items in the group named mycustomgroup.

This operation avoids querying access controls to find items in a group and then fetching the items individually.

Applying user visibility

A masquerade parameter can be used to list objects a specific user is able to access. For example:

?masquerade=[USER-ID]

Please note, the active user (as defined by the authenticated API credentials) must have permissions to access the specific user to perform masquerading.

Filtering by predicate

To filter results from a list request a filter parameter can be used. The filter is a predicate that is applied to data in each object. For example:

?filter=modifiedMillis>=1533901286294
?filter=label=="test"
?filter=mycustomkey=="mycustomvalue"
?filter=androidSdk>20&&screenSize<55

Please URL encode the value of the filter to encapsulate any special characters.

Example Java Code

The following examples require json_simple-1.1.jar on the classpath. This library is used to help construct the JSON for the server communications.

Users, Groups and Access Controls

This example demonstrates how to create users and groups and apply access controls.

UserManagementExample.java [Output]

Library items, Sequences and media uploads.

List responses can be filtered by group by adding the query parameter groupId or groupName referencing a group to return.