LearnPromotions

GraphQL concepts

As an integrated partner, you are familiar with our current API formats and standards:

  • XML - Markup language that is used to encode documents in human-readable and extensible format.
  • REST - Architecture used for exchanging structured data that is performant and ubiquitous, which means partners can easily adopt our APIs to send requests and responses that meet performance metrics crucial to the nature of the traveler business.
  • JSON - Lightweight format for structured data that is easy to read and parse. It is used primarily to transmit data between a server and web application as an alternative to XML. (This format will continue to be used. GraphQL queries use the JSON content type and responses are returned in JSON.)

Now, we are offering new capabilities as part of a GraphQL API. Why introduce GraphQL into the mix?

GraphQL is a query language that enables you to fetch data efficiently, and it offers these advantages:

  • Single endpoint - GraphQL is typically served over HTTP via a single endpoint, which provides access to the full set of capabilities of the service. You can issue one query to retrieve all of the data that is needed. This differs from REST APIs, which often necessitate multiple queries to multiple endpoints to retrieve the desired data. GraphQL also eliminates over- and underfetching because the structure of the data that’s returned is not fixed. Instead, it is flexible and enables the client to decide what data is needed.
  • Versioning - GraphQL returns only the data that's explicitly requested, so new types and new fields on those types can be added without creating a breaking change. With REST APIs, there's limited control over the data that's returned from an endpoint. Any change can be considered a breaking change, and breaking changes require a new version.
  • GraphQL explorer - Also referred to as a "GraphQL playground," this is a graphical integrated development environment (IDE) that enables you to test requests and view responses. We provide an explorer for you that uses test data to query data. Or, you can install a third-party IDE (desktop app), such as Prisma or Insomnia. After installing the IDE, be sure to generate your authorization token and set it as an HTTP header.

As a developer using a GraphQL API, how does using this type of API differ from using our existing formats and standards?

  • The verbs are different: To retrieve data, you will issue a query, and to modify data, you will issue a mutation. (If using a client to issue queries, you can use the GET or POST method.)
  • Access is the same: You will continue to issue requests over HTTP and you can continue to use clients such as cURL or Postman.
  • Response format is the same: Responses are returned in JSON.

Pagination

For queries that return large result sets, the API provides a way to paginate results (as defined by the GraphQL spec). When issuing a query, you can specify how many results are included in a page. Several fields are available to enable this functionality:

  • pageSize refers to the number of results returned per page
  • totalCount specifies the total number of results
  • hasNextPage indicates that at least one more page of results is available (when set to true)
  • endCursor provides a marker for the end of the current page; this marker is specified in the after field in the next query request

​​Here is a promotions query example that sets pageSize to 3, which means three promotions are returned per page. The response indicates that there are 10 promotions (totalCount) in the result set, which means that you must retrieve four pages of results. Note the values of totalCount, hasNextPage, and endCursor in the response.

1query {
2 property(id: "12345", idSource: EXPEDIA){
3 promotions(pageSize: 3) {
4 totalCount
5 pageInfo {
6 hasNextPage
7 endCursor
8 }
9 edges {
10 ...

To retrieve the next page of results, issue a request similar to the following. Take the value of endCursor from the previous response and specify it in the after field of the next request. Continue to issue requests and update the after field with the value of endCursor until the response returns "hasNextPage": false and "endCursor": null.

1query {
2 property(id: "12345", idSource: EXPEDIA){
3 promotions(
4 pageSize: 10,
5 after: "L3Jlc2VydmF0aW9ucy9zZWFyY2gZW50aXR5Q29sbGVjdGlvbj1yZXNlcnZhdGlvbnMmcGFnZXNpemU9MiZwYWdlPTImaHlkcmF0ZT1mYWxzZSZpbm") {
6 totalCount
7 pageInfo {
8 hasNextPage
9 endCursor
10 }
11 edges {
12 ...

Resources

To fully understand the benefits of GraphQL, check out these learning resources: