Client Application Development

The GraphQL API allows developers to build applications that communicate with SICON OS, with greater control than through the REST API. GraphQL allows users to select the exact data fields that they need for their application, including nested data.

Operations available through the GraphQL API are:

• Queries - fetch data from SICON.

• Mutations - create, edit and delete data on SICON.

• Subscriptions - allow applications to subscribe to real time updates, which are issued when data changes on SICON.

Filtering is available for queries and subscriptions, see Query and Subscription Filters.

Recommended libraries for building a GraphQL application:

• Apollo Client - a Javascript library for managing client interactions with a GraphQL API.

• GraphQL Code Generator - generate typescript types using the GraphQL schema.

Apollo Client Code Examples

Apollo client configuration file:

import { GRAPHQL_URL, GRAPHQL_WS } from './constants.js';

export default {                
            clientConfigs: {            
            default: {
              httpEndpoint: GRAPHQL_URL,
              tokenName: 'token-name',
              persisting: false,
            },
          },          
          authenticationType: 'autenticate-type',       
          tokenName: 'token-name',      
          includeNodeModules: true,          
        }

GraphQL Query:

query DeviceInstanceQuery {
  deviceInstanceQuery {
    data {
      id
      kpi
      name
    }
  }
}

Using query with Apollo client:

this.devices = (await this.$apollo.query({
                query: deviceInstanceQuery,
                variables: {
                            "deviceInstanceWhere": {
                                "regStatusId": {
                                "gt": 4
                                },
                                "hidden": false
                            }
                            }
                })).data.deviceInstanceQuery.data

Authentication

The SICON OS GraphQL API is protected and requires that requests are sent with an HTTP Authorization header, with an access token (JWT) set as the content. The server uses this access token to identify the user and to decide whether or not they can access a requested resource.

For Apollo Client users, adding an Authorization header to requests is explained here: https://www.apollographql.com/docs/react/networking/authentication.

Generating an Access Token (development)

For use in development, a JWT token can be found in the main SICON application after logging in, under: System Settings → Users

Note that this token changes on each login and is only useful for development purposes.

Generating an Access Token (production)

In production, authentication will fall into one of two cases:

• An application that is embedded in SICON OS and running under the same domain.

• An external application running under a different domain.

Embedded Application Authentication

If an application is embedded in the main SICON application it can access the sicon session cookie, which is set when a user logs in. A helper function is provided here, which can be used to extract a user’s access token from the session cookie:

const getCookieValue = (name) => {
	const cookie =
		document?.cookie
			?.match('(^|;)\\s*' + name + '\\s*=\\s*([^;]+)')
			?.pop() || null
	if (cookie) return JSON.parse(decodeURIComponent(cookie))
}

const getToken = () => {
	const siconCookie = getCookieValue('sicon')
	return siconCookie?.token || null
}

External Application Authentication

If an application doesn’t have access to the SICON session cookie it is necessary to provide a login page where users can submit their username and password. The GraphQL Login mutation can be used to send a user’s credentials to the API, where an access token is generated and sent back, and used on subsequent API requests.

For more information on the Login mutation see the section on ‘Authentication Headers’ in the Apollo Sandbox guide.