Intro to GraphQL APIs
API OverviewCopy
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.
PLEASE NOTE: The Tray GraphQL API is a backend API only and calls must be invoked server-side. Client-side Javascript calls to the API should not be made as they will be blocked by CORS. Our demo app (built using https://www.apollographql.com/ ) is a good illustration of how you can create a UI which presents an End User with their available Solutions while making all API calls server-side - using a button to hand over the Solution Instance configuration to our End User Config Wizard in a pop-up or iframe.
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 conventionsCopy
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.