1.8 API Introduction


#1

Introduction

This guide assumes that you already have working CMS, players in 1.8.0-rc1 version and XMR is also configured.

As a first step, you will need to decide what application you will want to use to connect to the API.
In this guide we will use Postman as an example application.

The 1.8 API documentation can be found here - http://xibo.org.uk/manual-tempel/en/api.html

CMS Application

No matter what application you want to use, you will have to create new application in your CMS Instance.

To do that please navigate to the Applications page in CMS and click the green ‘Add application’ button as shown below and give your application a name.

Now, please click on the row menu and select ‘Edit’, you will see the following form:

The Client Id and Client secret will be needed later, in this example we also need client credentials for our application.
Switch to Permissions tab and check ‘All access’ then press ‘Save’ button.

Application Configuration

Once we’ve created new application in the CMS and have clientId and clientSecret we can configure our application to communicate with CMS.

As mentioned we will use Postman in this guide as an example.

Environment
On the top right side of the Postman application, there will be a gear icon, please click on it then select ‘Manage environments’ as shown below:

Click the Add button and configure your environment:

Access token - you will get this with your first API call, more one that in the next section.
URL - your CMS address
ClientId and ClientSecret - are the keys you got when you created the application in the CMS

hardwareKey, serverKey and version are not required (but can be used in some calls).

Once configured, make sure Postman is set to use your environment - in this example ‘Local 1.8’ is the name of my environment.

API calls

To make it easier, I’ll link a test API collection.json here, which you can download and import to your Postman application.
https://www.dropbox.com/s/h6caxsv4bounzcg/Test%20API.postman_collection.json?dl=1

Which is quite straightforward, on the top left side there is the ‘Import’ button, all you will need to do is click it and drag&drop the json collection file:

Your first API call should be Access Token.
Please select the call from the left panel and click ‘Send’ button, once you receive response you will need to right-click on the token as save is as access_token as shown below:

Now you’re ready to start using API calls via Postman.

There are couple of API calls in the collection I linked in this guide, I’ll briefly describe the calls we need to create new layout, upload media and assign that media to your player.

Most calls will require Authorization Bearer {{access_token}} in the headers:

All parameters in {{}} like {{url}} or {{clientSecret}} are set in your environment, so you don’t have to, for example, copy whole access_token in each API call that needs it, instead you just put {{access_token}} in call’s header.

Layout create - pretty self explanatory, you will need to pass the name as a parameter. You can also add additional parameters to the call, please see linked documentation for details.

When you create a new layout via API call in the response field you will also see the region information ( as we all know, when you create new layout in Xibo it comes with empty full screen region)

We will use playlistId later to assign new media file to that region.

Now, we need to upload new file to our CMS library, to do that we will use library upload call in our test collection.

When you open it, it’s set to only upload a new file, you click on the files button, select media file, change the name and click send and new file will be uploaded to your CMS library.

The three additional parameters that are there, but are inactive:

  • oldMediaId - you can put existing mediaId here which you want to replace with this new upload
  • updateInLayouts - flag (1,0) which you can set to update this media in all layouts (it is used with replace).
  • deleteOldRevisions - flag (1,0) to either remove or leave the old file revisions (it is used with replace)

You can try edit media in library in CMS to see exactly the same checkboxes there.

After you use this call, in the response field, you will see mediaId of your newly uploaded file, it will be needed in our next call.

At this point we have layout and media uploaded to our CMS, time to assign our media file to our layout.

Playlist library assign - you will need playlistId and mediaId with optional duration parameter.

playlistId - each region has a playlistId, if you know the playlistId (in this example 3) then you can use that.
If you don’t know the playlistId, you will need to call GET Layouts (included in the collection .json from this guide).

media[] - is an array of mediaId you wish to assign to this region (at least one required)
If you don’t know the mediaId you want to use, you can call GET Media (included in the collection .json from this guide)

duration - optional parameter that can be passed in this call.

At this point we have created a layout, uploaded a media file and assigned it to our layout.

Another interesting call in our test .json collection from this guide is:
Action: Change layout

You’ll need displayGroupId and layoutId
You can call GET Displays to get displayGroupId - each display has it’s own unique displayGroupId
You can also call GET DisplaysGroup to get displayGroupId of a display group, if you have any in your CMS.
You can call GET Layout to get the layoutId you need

Once configured it will let you instantly change the layout displayed on your display/ display group.
If you send it without duration specified, it will be displayed for the layout’s duration.

Notes

There are a lot more API calls available, with this guide and API documentation you should be able to create them by yourself.

In all GET calls you can pass additional parameters to filter the results, again please check the API documentation - http://xibo.org.uk/manual-tempel/api/#/

If you will find that some calls aren’t working, please create new topic in dev category.


How to change text or image through API
Uploading Media through API
Using XMR with Xibo CMS v1.8.0-rc2
1.8 Alpha3 - How do you get a list of the playlist via the API?
Which Xibo api can be used to add webpage widget in a playlist for a layout?
Xibo API Question
Scripting Content Management - A Brief tour of the API (with example code)
How to request screenshot.jpg through api
Connection with API
Trigger layouts based on external decision
PDF Dynamic Display
Editing Region Library via API
API Call through Postman
Player API working examples
Change layout on event
Is there any possible way to enter into xibo without client_id and secret_id through api
Put image/video on a region as widget through xibo api 1.8
ReplaceVideo.py
Back to api : change layout
Lockdown procedure
API Add Media - Error Filetype Not Allowed
Common Layout with Different Media?
Powerpoint in a folder
Api calls return error 500
API Access Error Client authentication failed
Trouble with my first api call with postman
New Media in 1.8
1.8 CMS API Add Media to Layout, how to get playlistid from Layoutname
Need help to schedule a layout on event
How do i automatically set environment variables to API
Overlay Layout API
Windows Xibo player, update / reload default layout over http post?
Just Lost Everything
How to generate access_token and clients_id
ReplaceVideo.py
1.8.1 Postman Get Access Token 401
API tempel 1.8 Upload Media items
API tempel 1.8 Upload Media items
Pulling Information from External CSV/Documents
1.8beta API Getting MediaID when adding a new media in library
Xibo API "The resource owner.... "
Xibo CMS v1.8 (rc1 & rc2) installation
404 error trying to authenticate with API OAuth
#2

A post was split to a new topic: Automating API calls


#3