You are here:
< Back

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:
{reseller server domain}/swagger-ui.html#/     e.g. https://editor.wallboard.info/swagger-ui.html#/

 

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 POST /api/{resource}/ (with object in body): create resource by given object.
  • 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 on 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)
2. Optional: search “user-controller-public” and call “GET /public-api/user/checkLogin”
   a. In the response JSON you can find your users customer ID (Picture 1.)
3. Search “content-controller” and call “GET /api/content/”, nameKeyword is optional (Picture 2.)
   a. CustomerId is optional – if the caller user is an ADMIN it can get any customer’s contents.
   b. In the given response you’ll find the first 20 elements. In the list you can find the contentId-s. (In swagger the pagination is not working yet.) (Picture 3.)
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.
6. In “device-controller” call “POST /api/device/assignContent/{deviceId}/{contentId}” (Picture 4.)

   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).

(Download link: https://www.getpostman.com/)

Login/getting access token (Picture 5. and 6.):

1. POST {server root}/oauth/token (like https://editor.wallboard.info/oauth/token)

2. Auth type is “Basic Auth”

3. Fill “Username” and “Password” fields

4. Click on “Update Request”

5. Navigate to “Body” tab

6. Choose “x-www-form-urlencoded” type

7. Fill the table

a. username: a user who wants to log in

b. password: …

c. grant_type: always “password”

8. Click on “Send”

a. You’ll receive a brand new token (Picture 7.)

b. For later calls we need the “access_token” property

c. “expires_in”: shows the seconds until the access token is valid

Refresh token (Picutre 8.):

1. The “Auth” part is the same as before

2. In body set “refresh_token” value to “refresh_token” from token get response

3. After refresh you’ll get a new access and refresh token

Make sure to always check validity times!!! You need to refresh token before it expires.

Example: get contents

1. Leave “Auth” part empty

2. Create a HTTP header called “Authorization” and set the value to “Bearer {access_token}” (like “Bearer d7b12a23-a145-40c1-8041-26985bcb035e”) (Picture 9.)

3. Set other parameters like we did on swagger

 

Comments are closed.