This is a short description on how to use the Signage Next GraphQL API.
IF you have 14 minutes, then have a look at this YouTube video: "14 minute What is GraphQL?".
In short GraphQL is a query language, which queries a graph datatree, hence the name GraphQL. // todo: add more stuff here
We offer a single GraphQL endpoint for all interactions with Signage. You'll need to be authenticated in order to perform most queries, which requires an API Access Token.
In Signage, go to the admin panel and open the developer-tab. Click "New Key".
You'll need to provide a name and should assign a few access rights to that token. For simplicity you can choose "Grant full access".
If you're an org administrator or owner, you can select the "System User"-option, which assigns the key to and org-based system user. This allows for the key to persist even if your account becomes inactive or deleted.
Click "Create Key" and a new popup will show your API Access Token. Store it away and keep it safe as every action performed with it, is performed and logged in your name. Note that the key will be displayed only once and can't be retrieved later on anymore.
You may however create as many tokes as you like.
All your tokens are displayed in the developer-tab and can be renamed, edited, disabled or permanently deleted.
When querying the GQL endpoint, you'll have to send an Authorization-header with a value of bearer <your token>
Most IDEs by now offer decent GraphQL support, but there are also a lot of great standalone tools and of course you can use Postman or simply CURL to get the job done.
One tool which is remarkebly simple and offers a great code support is the Altair GraphQL Client both in the browser and standalone on your desktop.
You'll need to do two things to be ready.
First copy-paste the GraphQL endpoint url from the developer-page in signage into Altair. It should immediately try to introspect the endpoint and populate all of its documentation. Click on "Docs" to deep-dive into all available data queries and mutations at any time.
Next set set your Authorization-header using the asterisk icon in the left sidebar. The value should be bearer <your token>
Try the following basic queries to get started:
query {
currentUser {
id
givenName
familyName
email
}
}
will return something similar to
{
"data": {
"currentUser": {
"id": "79c74139-22f7-4f35-b6bc-9f15802a4720",
"givenName": "Alice",
"familyName": "McCloud",
"email": "alice@screencloud.com"
}
}
}
query {
currentUser {
email
teamsByUserId {
nodes {
name
screensByTeamId {
nodes {
name
id
screenGroupId
}
}
}
}
}
}
will return something similar to
{
"data": {
"currentUser": {
"email": "alice@screencloud.com",
"teamsByUserId": {
"nodes": [
{
"name": "_default_team",
"screensByTeamId": {
"nodes": [
{
"name": "ScreenCloud Player",
"id": "7f697859-a0cb-4bba-9581-35ba02759086",
"screenGroupId": "1e6836b6-009e-47b1-ba2a-48c16eb1ee4a"
}
]
}
}
]
}
}
}
}
mutation {
pairScreen(input: {
pairing: {
code: "<screen-pairing-code>"
}
screenGroupId: "<target-screen-group-id>"
})
{
screen {
device
name
}
}
}
Will pair a screen to your organisation and add it to the chose screenGroup. It will then return that screens device and name properties.
mutation {
setScreenChannel(input: {
screenId: "<target-screen-id>",
channelId: "<target-channel-id>"
})
{
screen {
channelsByScreenId {
nodes {
id
name
}
}
}
}
}
query {
allChannels {
nodes {
id
name
}
}
}
The actual query needs a JSON envelope similar to:
{
"operationName":"pairScreen",
"query":"mutation pairScreen{ pairScreen(input: { pairing: { code: \"123123\" } screenGroupId: \"123123\" }) { screen { device name id }}}"
}