GraphQL API

The Glartek API is built with GraphQL, a flexible and versionless query language that allows you to return as much or as little data as you need. GraphQL is an application layer that parses the query you send it and returns (or changes) data accordingly.

Unlike REST APIs, where multiple endpoints return different data, GraphQL always exposes one endpoint and allows you to determine the structure of the returned data.

The Glartek endpoint can be used to send/fetch all data or execute any action supported by the platform. The Glartek Web, Mobile and Glasses applications use this same endpoint.

There are multiple GraphQL client libraries to consume the API and, because data is arranged in types, there is no need for manual parsing.

You can view the available datatypes and queries/mutations on the documentation of generated GraphQL Schema.

The Glartek GraphQL API endpoint is located at: https://glarcloud.com/graphql

Our production GraphQL API endpoint has introspection disabled so you cannot use an explorer directly on that endpoint. However, we can provide upon request access to a sandbox endpoint where you can use an Explorer to explore the API schema.

You need an Authentication Token to be able to perform authenticated queries. The token can be fetched directly from the GraphQL API. The token may expire after some time so you will need to handle the error and renew it. Nevertheless, you should re-use the last valid token for all the authenticated queries (i.e., no need for a new token for each query).

To fetch the Authentication Token, you should use the login mutation and include you user username, password and domain fields. The domain field is your organization tenant name (i.e., subdomain of the URL you use to access the Web app). Even if you use the endpoint URL with the subdomain of your tenant, you need to include the domain field in the query.

Example query to get the Authentication Token:

The Authentication Token is a 64 long string that is return as _id. See example below:

All the authenticated queries should add the Authentication Token to the HTTP Authorization header.

All the Glartek platform users can use the API. The API automatically restricts which data and which queries can be executed based on Authentication token of the role of the user.

Below are some examples of how to run queries and mutations:

The explorer provided a Web UI with API Schema documentation and a query interface with syntax highlighting and autocompletion to perform real GraphQL queries against the API.

You need to authenticate the queries so contact us to request access to this sandbox endpoint.

You can run GraphQL queries in a curl request on the command line. This tool allows you to quickly test the payload of the query and to see the responses.

You need to perform beforehand a query to get an Authentication Token. The Authentication Token is valid for up to 365 days from the last usage.

Example query to get the Authentication Token:

Example query to get list of Work Orders (with the Authentication Token of the previous query):

There are multiple well maintained third-party Client Libraries that your applications can use. Refer to GraphQL client libraries. Glartek can also provide you some example applications interacting with Glartek GraphQL API.

The GraphQL Schema identifies the objects and fields available for clients to query and their corresponding data types. Refer to the Glartek GraphQL Schema reference. You can also download the full schema here.

The Glartek GraphQL API leverages the following data types:

• Scalars - Primitive values, such as Int, Float, String, Boolean and ID, and additional types defined by Glartek.
  
• Objects - GraphQL queries are hierarchical and composed, describing a tree of information. While Scalar types describe the leaf values of these hierarchical queries, Objects describe the intermediate levels. The Glartek GraphQL API uses Objects to represent different resources (e.g., a Site or an Action).
  
• Enums - Possible sets of values for a field.
  
• Interfaces - Parent objects from which other objects can inherit.
  
• Unions - Type of object representing many objects.
  
• Input objects - Define a set of input fields; the input fields are either scalars, enums, or other input objects. This allows query arguments to accept arbitrarily complex structs.
  

Queries are used for data retrieval. See example above to fetch issues' name, sorted by name.

Mutations are use for creating, updating, and deleting data, which may also trigger specific behaviour on the platform. See the GraphQL Mutations documentation.

Mutations have:

• Inputs. For example, arguments, such as which label you'd like to add, and to which site.
  
• Return statements. That is, what you’d like to get back when it’s successful.
  
• Errors.
  

See example above of the mutation to create and get an Authentication Token, where you send the relevant input and a Token is created and returned.

Introspections can be used to query the GraphQL endpoint for information about tis schema. This is only enabled for the sandbox endpoint. See the GraphQL Introspections documentation.

Most GraphQL endpoints allow you to specify how to sort a collection of objects. Please check the Schema for sorting options.

Pagination allows you to limit the number of records you'd like to receive (e.g., only the first ten records or the next records). By default, the Glartek GraphQL API returns 100 records per page. You can use the first or last arguments, together with the cursor to retrieve a specific page. See the GraphQL Pagination documentation.

Note that some Queries and Mutations may not return the final response synchronously (e.g., generating reports or exporting data). Please refer to the Glartek GraphQL Schema and API Examples.

The Glartek GraphQL API aims to always return useful errors information. You should validate if the HTTP response code is different from 200 Success (e.g., 400 Bad Request) and look at the response body to understand the error. Example below:

In rare occasions, the API may not return a JSON content type with error information (e.g., API endpoint is done).

Subscriptions enable you to fetch data. Unlike queries, subscriptions are long-lasting operations that can change their result over time. They can maintain an active connection to the GraphQL server (most commonly via WebSocket), enabling the server to push updates to the subscription's result.

Subscriptions are useful for notifying clients in real time about changes to backend data, such as the progress of the execution of a work order or chat messages.

Refer to the Glartek GraphQL Schema for the list of available Subscriptions.

The Glartek GraphQL API is versionless and changes to the API are typically backward compatible. However, from time to time, breaking changes could include removing or renaming fields, arguments, or other parts the schema.

Deprecated items are marked in the schema. Glartek will try to keep deprecated items available as long as feasible, for at least 6 major releases and 12 months, and will identify and notify customers to change their API calls.

The Glartek GraphQL API applies limits to protect the API from performing queries that could impact the endpoint performance.

In the future, the Glartek GraphQL API usage may be scored for complexity or limited for depth of node that query can return. You should use a reasonable number of fields and arguments in the queries and aim for simpler responses. We recommend keeping queries and mutations as simple as possible to avoid being rejected in the future.

Please contact Glartek to access the history of changes of the API and get a notification for new relevant changes.

For more information please contact us.