Executing GraphQL
To execute GraphQL we’ll use gql.Exec(query); JScript function. query parameter will be the query in string format.
return gql.Exec(‘{findLocalSetting(name:Promotion){name,value}}’);
GraphQL structure
GraphQL formatted as a JSON like structure. There are two basic terms to remember. A Query and a Mutation. We’ll use queries to query data and mutations to mutate (change) data.
Queries
A query have a field name and a result format.
{globalSettings{name,value}}
This query will execute globalSettings function and expects result as name & value format.
If we have 2 global settings stored in database query should return a JSON formatted result.
{
“data”:{
“globalSettings”:[
{
“name”:“Promotion”,
“value”:“Active”
},
{
“name”:“Printing”,
“value”:“Active”
}
]
}
}
We have two settings named as Promotion and Printing.
Aliases
You’ll notice query result includes function names and field names as we define them. You can optionally use aliases to change names defined in queries.
{settingNames:globalSettings{setting:name}}
settingNames is an alias for function name name and we want name field named as setting. This is how result appears. In this query we only want names so values does not appear in result.
{
“data”:{
“settingNames”:[
{
“setting”:“Promotion”
},
{
“setting”:“Printing”
}
]
}
}
Arguments
To query a single setting we’ll use findGlobalSetting function. To be able to query a single setting by name we’ll use arguments. We can define an argument by typing it after function name in parenthesis.
{findGlobalSetting(name:Promotion){name,value}}
We’re executing findGlobalSetting function with name argument. So the result will display setting named as Promotion.
{
“data”:{
“findGlobalSetting”:{
“name”:“Promotion”,
“value”:“Active”
}
}
}
You’ll notice result contains single result instead of an array on previous example.
This is what we should see when we query a setting named NotExists.
{
“data”:{
“findGlobalSetting”:{
“name”:“NotExists”,
“value”:null
}
}
}
Uses in JScript
You can convert this to a JScript function for easy accessing settings from SambaPOS automation features.
function readSetting(settingName)
{
var response = gql.Exec(‘{findGlobalSetting(name:’+settingName+‘){name,value}}’);
var result = JSON.parse(response);
return result.data.findGlobalSetting.value;
}
Pasted image2064x1371 110 KB
Mutations
In fact we used shortcut syntax for queries. Full syntax for a query starts with query keyword and a custom name for the query. For example it may start with query myQuery.
query myQuery{globalSettings{name}}
Naming queries is useful while using some advanced techniques to merge results of multiple queries but we won’t cover that for now. We should remember for queries we can skip query keyword and query name.
Mutation is a special kind of query that we use to mutate (change) data. For example to update or delete a global setting we need to use a mutation. Unlike queries we should start it with mutation keyword and give it a name. There is no shortcut syntax for that.
mutation myMutation{
updateGlobalSetting(name:Promotion,value:Disabled){name,value}
}
This mutation calls updateGlobalSetting function with two arguments. Name and value. This mutation changes Promotion setting as Disabled.
updateGlobalSetting(name:Promotion,value:Disabled)
Like queries all mutations should return a result so we also append result query format to the mutation.
{name,value}
So mutation will return resulting name and value.
This is how the mutation should respond after a successful call.
{
“data”:{
“updateGlobalSetting”:{
“name”:“Promotion”,
“value”:“Disabled”
}
}
}
Another mutation we have can be used to delete settings from database.
mutation m{deleteSetting(name:Promotion){name,value}}
That should also return deleted value as the query result.
{
“data”:{
“deleteSetting”:{
“name”:“Promotion”,
“value”:“Disabled”
}
}
}
How you’ll know what to write?
This is the best thing about GraphQL. It is self documented. I mean we document it while coding it. When I release the server solution it will also contain a tool to observe API. Until that you can use my tutorials as a reference.
Currently we have…
Queries
globalSettings
findLocalSetting(name)
findGlobalSetting(name)
Mutations
updateLocalSetting(name,value)
updateGlobalSetting(name,value)
deleteSetting(name)