Access for Developers

Introduction link

The 2ic Pallets app has two publicly accessible APIs:

• Accounts API: for creating, configuring, and administering one or more pallets databases, e.g., accounts, database users etc.
• Pallets API: for managing data contained within a particular pallets database. Transactions, Locations etc.

The Accounts and Pallets APIs both use the GraphQL query language to support flexible querying. An introduction to GraphQL can be found here: https://graphql.org/learn/. The APIs also provide a response with messages for any errors that occur and can include multiple errors in a response. When encountering errors with a query, try reading the text of the response for more information. All mutations are idempotent.

Setup and Authorisation link

Developers working with the 2ic Pallets APIs require a login like any other user. The one login can be used to access the application and to access both APIs during development. Authorisation to read and write particular data is the same in the 2ic App and the API. If a developer is unable to perform an action in the app, they will also be unable to perform that action via the API with the same login. A developer needs to be provided access within 2ic Pallets to everything that they need to work with via the API, such as access to the relevant databases.

2ic provides two options for third party API integration examples:

1. Altair
2. Postman

Getting Started with Altair link

Altair is the GraphQL client we recommend for development with the 2ic Pallets APIs. Altair can be accessed through our 2ic Altair Client and also from the API endpoints listed above. Altair can be installed as a desktop app on MacOS, Linux, and Windows, or as a browser extension for Google Chrome or Mozilla Firefox. The walk-through below assumes the use of the Chrome browser, however other modern browsers with development tools for viewing network requests can also be used.

Opening Altair

1. Open 2ic Altair Client.

Set the access token

To use the 2ic Pallets APIs you must send a valid access token in the request header. Altair can be configured to include the header, but the access token must be set as an Altair environment variable. An access token is generated when you log in to 2ic Pallets and will expire after 24 hours, at which point the new token must be updated in Altair again. The same access token can be used in all 2ic Pallets environments for as long as it is valid. The process to obtain the token and set it in Altair is:

1. Open https://app.2icsoftware.com/ in Chrome and log in to the 2ic Pallets app, if not already logged in. Ensure you have verified your account and email address before proceeding.
2. If not navigated automatically, using the navigation panel on the left, expand the user panel at the top and open My Details page.
3. On the my details page, there is a section called API Access. Copy the access token from here.
4. Open Altair and click the environment button in the top right (labelled "No environment" when no environment is set) and select environments.
5. In global environment, set the following:
   { "access_token": "PASTE_YOUR_ACCESS_TOKEN_HERE" } and click Save.

info

If the access token is invalid or missing when querying the APIs, you will receive a response message beginning with:
GraphQL.validation.validationError: You are not authorised to run this query.

Import the 2ic Altair example

info

Importing the 2ic Pallets Examples are only required when you access Altair GraphQL Client from anywhere other than 2ic Altair Client.

1. In Altair, open Collections by clicking the bottom-left button.
2. Download and unzip:

get_app 2ic Altair Example 2ic-altair-collection.zip

3. Click the Import button under the Collections header and import the 2ic-altair-collection.agc file from the example collection above.

The 2ic Altair Example collection should now be visible and contain the items Pallets and Accounts.

Query a Pallets API database

1. Ensure that the provided examples are loaded, otherwise ensure collections are imported by following the steps above.

2. Ensure the authorisation header is set and ticked green. The {{accessToken}} syntax will pick up the 'accessToken' variable as set in your environment, or the access token can be pasted in here directly.

   

3. In the 2ic Pallets Example Collection click on Pallets to open.

4. Run the query named GetLocations. Note the error message response GraphQL.Validation.ValidationError: You are not authorised to run this query.\nDatabase cannot be found.. The Pallets API requires the ID of a specific database to query. This database ID needs to be sent as a request header similarly to the access token.

5. The databaseId can be found on https://app.2icsoftware.com/ next to where the access token was copied from, you will need to ensure your database is open for the ID value to appear.

6. Open the Environment Manager and update the Global Environment to:
   { "access_token": "YOUR_TOKEN", "database_id": "PASTE_YOUR_DATABASE_ID_HERE" } and click Save.
   

7. Ensure the X-palletsRunContext-key header is set and ticked green. The databaseId can be accessed from the environment variables or pasted in here directly.
   

8. Return to the Pallets tab and run the GetLocations query. A list of locations in that database will be successfully returned.

Browse the Pallets API documentation

1. Click the Docs button on the right-end of the address bar. A panel will appear with the links Query and Mutation shown. If not, click the Reload Docs button to the left of the Docs button.
2. Explore Query and Mutation to see the range of read and write operations available for the Pallets API.

Getting Started with Postman link

Postman is a useful GraphQL client that can be used for development with the 2ic APIs. Postman can be installed as a desktop app on MacOS, Linux and Windows. The walk-through below assumes the use of Windows OS, but other operating systems can be used.

Download Postman

1. Navigate to Postman's download page and follow the steps.

Import the 2ic API GraphQL request examples collection into Postman

1. Open the Postman app and click import.

2. Download and unzip:

get_app 2ic Postman Example 2ic-postman-collection.postman_collection.zip

3. Select file and open the file from the example collection above.

4. The 2ic API GraphQL Request Examples collection should now be visible and contain the items Pallets API and Accounts API.

Setup database ID and bearer tokens

1. In Postman, open 2ic API GraphQL request examples and open the authorisation tab.
2. Replace <your-bearer-token> with your token, this can be found in the My Details page in 2ic Pallets.

1. Select the Variables tab, and replace <your-database-ID> with your database's ID, this can also be found in the My Details page in 2ic Pallets.

Query a Pallets API database

1. Under the Pallets API folder, select accounts/read accounts.
2. Click send in the top right corner.
3. See the queried accounts in the output body tab.

Explore the example queries
The example queries include examples reading, creating, updating and deleting records, using the 2ic pallets and accounts APIs.
These can be adapted as necessary.

Additional Information link

info

• The 2ic Pallets Altair and Postman example collections include some examples of filtering and sorting, as well some create and update mutation examples. Note that these often include values particular to the database or user and may need to be adjusted before they can run successfully.
• Access tokens can only be used for testing and hand crafting GraphQL queries. For your app/script's full integration with 2ic pallets you will need to request a Machine Access from us. For more detail, see registering for API integration.