Thinking in GraphQL
A Paradigm Shift
GraphQL is a query language, and as such it does exactly that: it queries servers in order to get results back. With GraphQL, you can choose exactly what data you want to retrieve. GraphQL is a typed query language. That means that it has a lot of predictability, as each piece of data has its own type, so we know what sort of data we will be getting back. This is something we really appreciate, especially since we deal with so many third party APIs, and often we have no control of what’s going on on the other side! At TravelgateX we take away all of those headaches, by offering you an integration platform to 600+ suppliers, all accessible via a single GraphQL endpoint.
Understanding GraphQL Schemas
In GraphQL, the API specifications are called schemas. A GraphQL Schema
is a contract between the client and the server. It defines how clients and servers can talk to each other and sets out what they expect from each other. This way, both know exactly what they can and cannot send to each other and what they’ll get in response to that.
There are a number of ways you can understand our Schema
:
- You can see all elements of our data model by clicking on the green
Schema
button on the right hand side of our API playground. - You can review our Reference Documentation which provides a page by page analysis of all
Objects
and fields used in ourSchema
. - You can see how all of the data fields are connected by exploring the GraphQL Voyager tool.
Schema
.Building Queries
You can test a Query
in the API playground
A query has the following components:
- Operation type: When searching data in GraphQL, we use
Query
to indicate the operation type (see below forMutation
operation type) - Operation name: (optional) You can give your
Query
a name so that it is easy to find in later code. This is the similar to creating a function in other programming languages. - Variable definitions: You can set what variables need to be completed in order to run your query. You declare a name for the variables you will use by using a $. A common variable name we use is $criteriaSearch. After declaring a variable name, use the colon and then describe what inputs are needed. You can choose from some of the input objects we have already created. For example, we often use the
HotelCriteriaSearchInput
input object. This input object requires the following fields as mandatory (indicate by a!
): Check in date, check out date, number of hotels to be returned in a response, and number of people to occupy the rooms. You can also add language, currency, nationality and market fields as variables to this input object, for more filtered responses. - Selection set: After the variables have been defined, you can use the
{
brackets to start listing what objects you want to query to get the data you need. Each selection set starts with a{
and ends with a}
. You can nest (indent) these selection sets so it is easier to read a query. - Response: Once you have completed defining your query, you will receive a response in JSON format. This will be nested as well, so it is easier to read.
Further reading
We recommend the following resources to learn more about making GraphQL queries:
- The Anatomy of a GraphQL query by Sashko Stubailo
- GraphQL explained by Jonas Helfer
- Queries and Mutations by GraphQL.org
Building Mutations
You can test a Mutation
in the API playground. We recommend that you work through our example HotelX mutation to book a hotel.
A query has the following components:
- Operation type: When searching data in GraphQL, we use
Mutation
to indicate the operation type, that is, we are going to change some data on the server - Operation name: (optional) You can give your
Mutation
a name so that it is easy to find in later code. This is similar to creating a function in other programming languages. - Variable definitions: You can set what variables need to be completed in order to run your mutation. You declare a name for the variables you will use by using a $. A common variable name we use is $bookInput. After declaring a variable name, use the colon and then describe what inputs are needed. You can choose from some of the input objects we have already created. For example, we often use the
HotelBookInput
input object. We added an!
in our example. The!
in GraphQL means it is mandatory. So while only three fields of theHotelBookInput
are usually mandatory, by adding the!
to our variable definition, we have made all input object fields mandatory. - Selection set: After the variables have been defined, you can use the
{
brackets to start listing what objects you want to query to get the data you need. Each selection set starts with a{
and ends with a}
. You can nest (indent) these selection sets so it is easier to read a query. - Response: Once you have completed defining your mutation, you will receive a response in JSON format. This will be nested as well, so it is easier to read. Look for the field
Status
and make sure it has OK to confirm that the data has been added/updated/deleted.