Development API

API usage guide

1. Overview

In this document, you can find some useful information about the Wallboard development API and the usage of it. The development API completely follows the REST approach with OAuth 2.0 authentication and authorization standard. For the detailed description of the end-points you can use our swagger, which you can find on any of our reseller servers in the following way:

2. About swagger

Swagger is an open source API browser which can be used to try and understand the API through the implicit and explicit (written by developers) documentation. Opening ours swagger you should see something like this:

3. End-points

We have two types of end-points:

Public

Callable by any client

Controller name ends with “-public”

No OAuth2 authorization

Usually used with GUID based ID-s

Secured

Only callable through OAuth2 authorization

Controller name ends with “-controller”

For most of our handled resources we have a resource-based controller which follows the traditional REST rules:

HTTP GET /api/{resource}/: get all resources. Usually, there is some keyword request parameter which can be used for filtering (like filter by name).

HTTP GET /api/{resource}/{resourceId}: get resource by the given ID.

HTTP PUT /api/{resource}/{resourceId} (with object in body): update the resource by the given id.

HTTP DELETE /api/{resource}/{resourceId}: delete the resource by the given ID.

The other calls are action based and full custom so they won’t follow any specific rule. If you have any question about a specific call without external documentation, please contact us.

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.

3.1. Pagination

For “get all” calls we use pagination which is implemented by the basic Spring pagination logic. If you don’t set any additional parameter, the API gives back the first 20 elements.

3.2. OAuth2 usage

For using OAuth2 authentication in swagger click on the “Authorize” button in the top right of the screen and fill the modal with valid login information. Example on the picture below:

User information:

Username: valid username in the system.

Password: the given user’s password.

Client information (oauth client):

Type: always chose “Basic auth”.

ClientId: found in “oauth_client_details” database table.

Secret: the secret of the given client.

Scopes

Always check “read” and “write”

Finally, click the “Authorize” button. After this, the swagger will reload the page and now you can use the secured end-points as the given authorized user.

3.3. About client details

OAuth2 uses client details to describe the different clients (like angular front-end or Android) for cases when we want to handle them differently by giving them tokens different validity times and scopes. For example, the default client’s token in our system (used by front-end) has a 20-minute access validity time and 30-minute refresh validity time.

Important: before you want to use our secure API, you need to contact us to ask for your own OAuth client details record. In this case, we need some information about the type of your client and the access and refresh token validity times.

4. Examples

4.1. Assignee content on device

Our goal is to get contents and devices from a database and assigned a selected content on a selected device. Note: the user will only get its customer’s contents.

4.2. With Swagger

1. Use the “Authorize” button to log in (with a user under the selected customer/client)

4. Do the same with “device-controller” – “GET /api/device/” call

5. Now you have a contentId and a deviceId so we have everything for assignee.

4.3. With Postman

Postman is widely used free http request creator software. I will show the usage through Postman, because it shows every detail which needs to implement a client in any programming language or platform. The most important part of this guide is OAuth usage (what swagger hides from you, everything else is the same).