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 our Schema.
  • You can see how all of the data fields are connected by exploring the GraphQL Voyager tool.

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 for Mutation 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:

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 the HotelBookInput 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.