Embedded API

API Overview

Copy

The Tray Embedded APIs are based on GraphQL - a data query language that allows more control than a protocol such as REST. It allows API consumers to be much more specific in terms of the structure and content of the data that is returned.

GraphQL works with queries to get/fetch data and mutations to alter it (post/patch etc.)

Multiple queries and mutations can be made inside one HTTP request, making interactions faster and allowing you to replace multiple REST requests with a single call to fetch the data you specify.

So if you want to retrieve data associated with a particular user, rather than making a request to a /users/ endpoint followed by multiple requests to /users/<id>/ endpoints (all of which return more data than you need), you can make one request for a user and specify exactly what data you want in return.

More information on GraphQL can be found at https://graphql.org/learn/ We recommend using one of the clients dedicated to GraphQL:

• Apollo (our demo app is built using Apollo)

• GraphQL CLI can also be useful for local development

There are also popular Go and Python clients available.

Note on conventions

Copy

Tray Partner API uses standard conventions for pagination, compatible with Relay Pagination Container specification. Additionally, all mutations make use of clientMutationId - if this parameter is specified in the input to the mutation, it will be returned unchanged in the payload. This is also required by Relay.

Postman collection

Copy

You can find the Postman collection here.

We advise you to fork the collection to keep your collection updated with ours.

After forking, you need to select the environment to set environment variables.

Now, add the master_token as an environment variable.

Importing cURL in HTTP Client

Copy

The default formatting of cURL generated by postman is not valid with HTTP Client's cURL import feature.

To import cURL requests from Postman into HTTP Client connector, ensure `Follow original HTTP method` is switched on in cURL settings. Here's how you can verify this setting is turned on for you:

1. Click on settings icon for cURL code snippet.

2. Ensure your settings panel looks like the one shown:

Insomnia collection

Copy

Click here to download our collection for the Insomnia Http client

This will provide you with a local testing environment which allows you to very quickly run queries and mutations on your live data, before inspecting the results.

Import the Tray Embedded library

Copy

In your Insomnia Workspace click on the drop-down to import the above downloaded file:

Click on 'embedded tokens' followed by 'Manage Environments':

Then you can see that the base url is https://tray.io/graphql

Then enter your master token (you can enter tokens from different accounts if you are using the Import / Export project APIs) obtained from the Embedded Dashboard (don't worry about the user_token error here - it will be rectified when you first use it):

Creating a session with a user token

Copy

One of the main benefits of using Insomnia is that it has dynamic environment variables.

With the Tray Embedded Insomnia library, we have set up a dynamic variable for user token such that when you run the 'Create User Access Token' mutation with a valid userID, the user token will then automatically be available for all queries and mutations that require it.

For example we can create a user token for a user and then get that user's authentications. Here you will see that you do not have to copy and paste the access token, because once it is created it is automatically pulled in to the 'Get User Authentications' endpoint:

The steps taken were:

1. Use the 'Get Users' query to obtain the userId of an End User

2. Paste that userId into 'Query Variables' for the 'Create User Token' mutation

3. 'Send' to create the User Token

The User Token is then automatically available for all queries and mutations that require it.

Note that you can also switch between user and master token for queries that can use either.

Using fragments

Copy

Some queries have multiple data filtering and input options.

For example, with the 'Get Users' query you can get all users, filter by userId, get the first 5 users etc.

So for this endpoint we have created a fragment whereby we first specify fields we want to be returned. Then we can click on the request we want to make (e.g. Get user by ID) before clicking ‘send’:

Using autocomplete

Copy

Using a valid master or user token means that you are connected to the Tray Embedded API schema.

In Insomnia this means you can use 'ctrl + space' to bring up an auto-complete list of available fields to be returned:

GraphQL online playground

Copy

The Tray GraphQL Playground is a handy resource for beginning to explore the Tray Embedded API and try out different queries and mutations.

For the most user-friendly testing environment, however, we recommend you download our Postman or Insomnia collection:

Exploring the schema

Copy

Click on the green label on the right to open the current schema structure and documentation for each field.

Authentication

Copy

You can use the HTTP Headers section on the bottom to enter your credentials to be used with the queries:

{ "Authorization": "Bearer <your-token>" }

Depending on the call being made your bearer will either be a master token or a user token.

Our API docs indicate which token is required for each query / mutation.