Apollo Sandbox
Apollo Sandbox can be viewed in a browser at: <installation-ip-address>/api/graphql
The main functions of Apollo Sandbox are providing a Schema Reference view and an Explorer view. The menu on the left side of the screen allows you to switch between the different views in the Sandbox.
The Schema view presents an API reference view showing all of the available queries, subscriptions and mutations, along with input and return data types.
The Explorer allows for queries and mutations to be run and validated on the server. To use the explorer a setup guide is provided below.
Apollo Explorer Setup
This guide is provided to help developers get started using Apollo Explorer, for more detailed documentation of the Explorer, from Apollo, please see https://www.apollographql.com/docs/graphos/explorer/ .
Authentication Headers
The SICON OS API is protected and users must first login and obtain an access token, which will be used in subsequent requests by setting an authentication header.
To login either use the Documentation panel on the left of the screen to build a login mutation, or input the mutation directly into the Operation panel. Enter your SICON OS username and password into the Variables tab. Execute the operation using the blue button in the top-right of the Operation panel.
If your request is successful an access token is sent back from the server, which is visible in the Response tab. Copy the access token, taking care not to copy the quotation marks (““).
The access token can now be used to authenticate with the server, to do this an authentication header must be set on all subsequent requests.
Open a new workspace by clicking on the + icon in the central panel.
At the bottom of the new panel that opens up, click on the Headers tab (next to Variables). Then click on the button “+ New header”. In the input fields that appear enter “Authorization” as the header name, and then paste your access token into the header content field.
This header will be sent with operations that are executed in the Operation panel and used to authenticate your user on the server. You can now use the Explorer to validate and run operations on your SICON OS installation.
Building Queries, Subscriptions and Mutations
The Explorer provides a simple way to explore the API and build operations. In the Documentation panel, operations are organised into their root types, queries, subscriptions and mutations.
After selecting a root type, all the available operations within that group are shown.
Clicking on the “+” icon next to the operation name adds the operation to the Operation panel. And the Documentation panel updates to show the Arguments (inputs) and Fields (return data) that are available for this operation.
As an example deviceInstanceQuery is selected.
We can see that this operation takes the arguments deviceInstanceWhere, deviceInstanceSkip, deviceInstanceTake and deviceInstanceOrderBy. These input filters are typical for SICON OS queries, providing developers with multiple ways to filter data. By clicking on a filter, all the available Input Fields are listed.
Clicking the “+” icon next to an input, adds this argument to the operation. After adding arguments to an operation, their value must be specified in the Variables tab.
At least one field should be selected and added to the operation to specify the response payload.
As an example “deviceInstanceWhere” is selected, then the Input field “active” is selected, and set to “true” in the Variables tab. As a return field “count” is selected. Intuitively this operation is asking the server to return a count of all active devices. The operation can now be executed using the blue button in the top-right of the Operation Panel.
