Wallboard API Documentation (1.11)

In this document, you can find some useful information about the Wallboard API. The API mainly follows the REST approach with OAuth 2.0 authentication and authorization standards.

Wallboard have two types of end-points:

Public

• Callable by any client
• API root starts with /public-api/
• No OAuth2 authorization
• Usually used with GUID based ID-s

Secured

• Only callable with OAuth2 authorization
• API root starts with /api/

Notes

• The API only uses JSON format for data transfer objects.
• The update logic usually follows the “if an attribute is null, it’s ignored” logic.
• In the return value if an attribute is not present it means NULL (to lower the overall traffic).

customerId - tenant selector parameter

• Customer ID parameter is present on most our endpoints and it can be used to select a specific tenant in the system, which the operations should be performed on.
• This is used by ADMIN users (or network/subresellers OWNERS) as they have access to multiple tenants.
• Non-admin users don't have to fill this parameter, because they can only access their customer's resources.
• If as an ADMIN you want to get every resource in the system set this value to "-1".

page,size - pagination parameters

• Pagination is implemented by the default Spring pagination logic.
• Page index starts from 0.
• If you don’t set any additional parameter, the API gives back the first 20 elements.
• The maximum element count for a page is 1000.

sort parameter

• Spring's default sort expression
• Directions: asc, desc
• Multiple parameters are supported - sort=name,asc&sort=lastActivity,desc
• There is no escape logic, the parameter simply has to be URL encoded.
• Value selectors can be chained with a . to be able to access embedded or connected entities' attributes
• Examples: sort=name,asc, sort=content.name,asc

search - filtering parameter

With this parameter you can create dynamic queries to filter the resources.

select - selecting fields

With this parameter you can specify which attributes or related entities should be present in the response.

Syntax (WBQL - Wallboard Query Language)

Search (WBCriteria)

Value operators

• : - means contains in case of string literals and equals in case of other value types
  • Example: name:mydevice - matches for prefix-mydevice-postfix
• = - means exact match
• ≠ - not equals
  • Unicode escape sequence: \u2260
• ∉ - not contains
  • Works only with string literals
  • Unicode escape sequence: \u2209
• ^ - starts with
  • Works only with string literals
• > - greater than
• ≥ - greater than or equal
  • Unicode escape sequence: \2265
• < - less than
• ≤ - less than or equal
  • Unicode escape sequence: \2264

Logical operators

• , - AND
  • Example: name=a,name=b
• | - OR
  • Example: name=something|name=something else
• Logical groupings are currently not supported

Value matcher keywords

• true
  • Only can be used with boolean attributes
  • Example: isValid:true
• false
  • Only can be used with boolean attributes
• NULL - value or connected entity is null
  • Example: content=NULL
• !NULL - value or connected entity is NOT null
  • Example: folder.parent=!NULL

Escaping

• All values has to be URL encoded
• The search parameter value must be URL encoded (most libraries encode request parameters by default)
• Format: search=urlEncode({value_name}{value_operator}urlEncode({value}))
• Example: search=name:mydevice:athome (the second : is part of the device's name) -> search=name%3Amydevice%253Aathome
• Example: search=teamAssignments.team.id=teamId1|teamAssignments.team.id=teamId2

Notes

• Date type attributes are supported and can be matched by UTC timestamps (milliseconds)
  • Example: startDate>1683616562 - means the startDate should be after 2023-05-09T07:15:46+00:00
• Value selectors can be chained with a . to be able to access embedded or connected entities' attributes
  • Example: deviceGroup.parent.id=000c08d294df48efb1b0f5aa754d7ef9 - meaning: the device's group's parent group's id should be '000c08d294df48efb1b0f5aa754d7ef9'.

Basic Examples

• User name contains the letter a: name:a
• Device state is online and is in emergency state: state:ONLINE,device.emergencyStatus:true
• A device content's name contains the substring "happy new year": content.name:happy new year

Advanced Examples

• Coming soon

Select (WBSelect)

With the select parameter you can also specify attributes that you want to select from a given entity. This method allows you to run more optimal and faster queries.

You can use the select function to append attributes from other related entities to the query (if the relationship is one-to-one or many-to-one).

Syntax:

• * : Selects all primitive attributes of the entity
  • Equivalent to the missing select parameter
  • Calculated fields and related entities are NOT included
  • Example: select=*
• , : Attributes should be separated with a ,
  • Example: select=id,name,comment
• ( ) : Used to select specific attributes from related entities
  • Example: select=id,name,device(id,name)

Advanced examples:

• select=*,customer(id,name)
  • Selects all primitive attributes from the device, plus the id and name of the customer it belongs to
• select=*,totalUserLoginCount,lastDeviceActivity
  • Select all the primitive attributes from the customer and the two specified calculated fields

Team management

includeReadOnlyInfo parameter

• Most of the GET endpoints support the optional calculation of the readOnly-ness of a resource
• An entity can be read-only for a user depending on the team settings
• If specifically not needed we suggest to turn if off, for faster response times

includeResourcesWithoutTeam parameter

• Determines whether or not to include resources which are not assigned to any team

selectTeamIds parameter

• A list of team ids that resources should be included in the response
• If empty, all team's resources are included
• Example: selectTeamIds=teamId1,teamId2

Roles

All users have a role and all of the secured API requires a minimum role to use it. The role is always hierarchical, so a user with an OWNER role can use all endpoints that require an OWNER or lower roles. We use the following hierarchy:

Global:

• ADMIN
  • Super admin of the system.
  • Can access anything and can do everything.

Tenant:

• OWNER
  • Tenant(customer) admin.
  • Under it's own domain can access anything and can do everything.
  • Can't belong to any team.
• TECHNICIAN
  • Can do everything except user and team management.
• APPROVER
• EDITOR
• VIEWER
• DEVICE USER

Terminology

We are using a bit different terminology for entities like you used to in our GUI. The following expressions mean the same:

• device = screen = player
• customer = client = tenant
• subreseller = network owner

Swagger - Deprecated

We have swagger set up at https://development.wallboard.info/swagger-ui.html, but it's not perfectly configured, there can be missing or misleading parameters. Also, the microservice's API is missing from there.

OAuth2 client credentials

By default, there are two built-in client credentials in the system, which you can use to get an access_token.

Default client details:

• client-id: default-client
• client-secret: 76211db5d8ea
• Basic auth header value: Basic ZGVmYXVsdC1jbGllbnQ6NzYyMTFkYjVkOGVh
• access_token validity: 20 minutes
• refresh_token validity: 30 days

Short-lived client details:

• client-id: short-lived
• client-secret: mPSjfsJy8rs4m7y4
• Basic auth header value: Basic c2hvcnQtbGl2ZWQ6bVBTamZzSnk4cnM0bTd5NA==
• access_token validity: 20 minutes
• refresh_token validity: 30 minutes

JWT

Certain new API endpoints use JWT token as authorization instead of the regular access_token.

OAuth2 token management operations

Advertiser management

Alert management

Alert rule management