Intro to GraphQL APIs
The Tray Embedded APIs are based on GraphQL - a data query language which 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:
There are also popular Go and Python clients available.
Note on conventions
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.