Getting Started with Postman
Introduction
This guide is applicable for CMS 1.8 and later versions and assumes that you already have a working CMS. Players need to be version 1.8.0-rc1 or later and XMR also needs to be 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 API documentation can be found in the Developer manual under the Integration section.
CMS Application
No matter what application you want to use, you will have to create a new application in your CMS Instance.
Navigate to Applications under the Administration section of the main CMS menu and click the Add Application button:
Give your Application a Name and click Save:
After saving, the Edit Application form will open.
The Client Id and Client Secret will be needed later. For this example, check the Client Credentials? and Is Confidential? checkboxes for the application:
From the Sharing tab, check Full Account Access.
Click Save.
Application Configuration
Once the application is created in the CMS and you have the Client Id and Client Secret, configure the application to communicate with CMS.
Postman will be used for this example.
Environment
Select the gear icon at the top right of the Postman application and select Manage Environments:
Click the Add button and configure your environment:
access_token — you will get this with your first API call.
url — your CMS address
clientId and clientSecret — keys from creating the application in the CMS.
hardwareKey / serverKey / 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 environment name.
Add Xibo APIs to Postman
Postman can import Xibo’s swagger.json file which will add a collection containing all of our documented APIs. On the top left side there is the ‘Import’ button; select it, choose “Link”, and paste in the link to our swagger.json file.
You can find our latest swagger.json file here: https://xibosignage.com/manual/swagger.json, however we recommend using the one from the CMS you are connecting to which is available at <your_cms_url>/swagger.json.
Configure authorisation
All APIs require authorisation, which can be configured for the entire collection in Postman on the “Authorization” tab.
For this example, the variables created in the environment will be used to fill in the URL / clientId / clientSecret from the “Configure New Token” options. The grant type should be “Client Credentials”.
Once configured, select the Get New Access Token button to get and use a new token.
Variables
The new collection has a baseUrl variable in the Variables tab, which we can set to {{url}}/api.
Once we have an access token and have configured everything, we are ready to make our first request. Scroll to the “About” item in the collection, open it and click Send.
Example — creating a Layout, uploading Media and assigning it
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 copy the whole access_token into each API call — instead use {{access_token}} in the call’s header.
Create a Layout
Call the Layout create endpoint — you will need to pass the name as a parameter. Additional parameters are available; see the linked API documentation for details.
Reference: Layout create
When you create a new layout via the API, the response includes region information (a new Layout comes with an empty full-screen region). Note the returned playlistId for the region — it will be used to assign media to that region.
After creation, you will see region details in the response:
Upload Media to the CMS Library
Use the library upload call in the test collection to upload a new file.
On opening, it will be set to upload a new file:
Click the files button
Select the media file
Change the name (optional)
Click Send
The response will contain the mediaId of the newly uploaded file — keep this for the next step.
There are additional (inactive) parameters available for replace/update behavior:
oldMediaId — replace an existing mediaId with this upload
updateInLayouts — flag (1,0) to update this media in all layouts (used with Replace)
deleteOldRevisions — flag (1,0) to remove or keep old file revisions (used with Replace)
Assign Media to the Layout (Playlist)
Use the playlist library assign call. You will need the playlistId from the layout region and the mediaId from the upload.
Reference: Playlist library assign
playlistId — each region has a playlistId. If you know it (e.g., 3), use that. If not, call GET Layouts (included in the collection) to find it.
media — an array of mediaId values to assign to the region (at least one required). If you don’t know a mediaId, call GET Media.
duration — optional parameter to set duration for the assigned media.
At this point you have created a Layout, uploaded a Media file, and assigned it to the Layout.
Another useful call in the collection:
Action: Change layout
You’ll need displayGroupId and layoutId.
Call GET Displays to get displayGroupId — each display has its own displayGroupId.
Or call GET DisplayGroups to get a display group’s displayGroupId if you have Display Groups set up.
Call GET Layout to get the layoutId you need.
If you send the change layout action without a specified duration, the layout will be shown according to the layout's duration settings.
Notes
There are a lot more API calls available; using this guide and the API documentation you should be able to create them yourself.
In all GET calls you can pass additional parameters to filter results — check the API documentation: Swagger UI at http://xibo.org.uk/manual-tempel/api/#/
If you find that some calls are not working, please create a new topic in the Dev Category on the Xibo Community site.
Was this helpful?