Prerequisites

GraphQL basics and tips

Although there is a lot more about GraphQL, we hereby list the very basics you should bear in mind when starting the integration.

Access

Endpoint

Production server endpoint: https://www.3rpms.de/graphql (please make sure you use www.)

Sandbox server endpoint: https://demo.3rpms.de/graphql

Authentication

All requests require an API key in the header Authorization: Bearer <myapikey> where

API key

Create an API key in 3RPMS® under Settings -> Integrations access or ask the administrator of the hotel to do it if you do not have access.

Each hotel can have multiple API keys, each of which can have the following restrictions:

• API Key has read-only access
• API Key has write access
• API Key has been disabled (when you want to restrict access temporary)

Advantages of GraphQL

Here are several advantages of GraphQL protocol relevant to API clients integrating with a GraphQL endpoint.

1. Speed

GraphQL is faster than other communication APIs because it facilitates you to cut down your request query by choosing only the specific fields you want to query.

2. No over-fetching and under-fetching problems

The main advantage of GraphQl over REST is that REST responses contain too much data or sometimes not enough data, which creates the need for another request. GraphQL solves this problem by fetching only the exact and specific data in a single request.

3. Hierarchical Structure

GraphQL follows a hierarchical structure where relationships between objects are defined in a graphical structure. Here, every object type represents a component, and every related field from an object type to another object type represents a component wrapping another component.

4. Defines a data shape

When we request GraphQL queries to the server, the server returns the response in a simple, secure, and predictable shape. So, it facilitates you to write a specific query according to your requirement. This makes GraphQL really easy to learn and use.

Examples

Let's say, you want to get room stays with arrival, departure dates, and a list of arriving guest names

GraphQL

query ArrivingPrimaryGuests($date: Date!) {
  room_stays(
    filter: { reservation_from: { gt: $date } }
  ) {
    edges {
      node {
        id
        arrival: reservation_from
        departure: reservation_to
        first_guest {
          firstname
          lastname
        }
      }
    }
  }
}

{
  "data": {
    "room_stays": {
      "edges": [
        {
          "node": {
            "id": 1,
            "arrival": "2022-02-21",
            "departure": "2022-02-28",
            "first_guest": {
              "firstname": "Matt",
              "lastname": "Luis"
            }
          }
        },
        {
          "node": {
            "id": 2,
            "arrival": "2022-02-22",
            "departure": "2022-02-26",
            "guests": {
              "firstname": "Linda",
              "lastname": "Webber"
            }
          }
        }
      ]
    }
  }
}

Rate Limits

There's a limit of 200 requests per minute per IP. Exceeding this limit will block further connections for a period of 20 minutes.

Optimisation

Reducing queries

When querying for multiple records by id at the same time, often the queries can be combined:

{
 room_stays(filter: {id: {eq: "<room stay id 1>"}}) {
  ...
 }
}

{
 room_stays(filter: {id: {eq: "<room stay id 2>"}}) {
  ...
 }
}

{
 room_stays(filter: {id: {in: ["<room stay id 1>", "<room stay id 2>"]}}) {
  ...
 } 
}

Batching queries

See Query Batches

Fields with a filter argument allow, as the name implies, filtering the result-set items.

Operator reference

Some fields may support only a subset of operators.

Logical Operators

In addition to comparisons, the following logical operators are also supported:

Examples

In these example we'll be using root room_stays field:

room_stays(filter: RoomStayFilter): RoomStayConnection!

Filter one field

{
    room_stays(
        filter: {
            id: { in: ["nQZA3P1U1", "J0lZ3H4Ml"] }
        }
    ) {
        ...
    }
}

Here we look up specific RoomStay items by id

Filter multiple fields

When multiple fields are used, they all must match.

{
    room_stays(
        filter: {
            reservation_from: { lt: "2022-02-28" }
            reservation_to: { ge: "2022-02-18" }
        }
    ) {
        ...
    }
}

Here we look up RoomStay items that are staying between Feb 18th and Feb 28th.

Filter using multiple operators

Filters are not limited to using just one operator - any subset of the allowed operators can be used at the same time.

{
    room_stays(
        filter: {
            reservation_from: {
                le: "2022-02-27"
                ge: "2022-02-21"                
            }
        }
    ) {
        ...
    }
}

Here we look up RoomStay items that arrived between Feb 21st and Feb 27th.

Negation

Negation is done by using the reserved not field.

{
    room_stays(
        filter: {
            reservation_from: { gt: "2022-02-18" }
            not: {
                reservationStatus: { eq: CANCELLED }
            }
        }
    ) {
        ...
    }
}

Here we find all RoomStay with arrival after Feb 18th that have not been cancelled.

Disjunction

Logical Disjunction can be done by using the reserved or field:

{
    room_stays(
        filter: {
            or: [
                {reservation_from: { eq: "2022-02-04" }},
                {reservation_from: { eq: "2022-02-11" }},
                {reservation_from: { eq: "2022-02-18" }},
                {reservation_from: { eq: "2022-02-25" }},
            ]
        }
    ) {
        ...
    }
}

Here we find all RoomStay items that arrive on any friday in February 2022

GraphQL allows you to fetch only the fields you need, with no unnecessary overhead. This helps keep network responses small and fast.

However, GraphQL doesn't automatically guarantee small responses. This is especially apparent when a field contains a list. To avoid enormous response from a seemingly small query, lists, containing unbounded maximum amount of items, use pagination:

query RoomStays($cursor: String = null) {
    reservations(first:10 after:$cursor) {
        edges {
            node {
                # reservation fields
            }
        }
        pageInfo {
            hasNextPage
            endCursor
        }
    }
}

Here, when no $cursor is provided, only the first 10 reservations are returned. To retrieve the next 10 reservations, the same query can be sent with $cursor set to value from endCursor field; and so on for the next 10 reservations. When there are no more results, hasNextPage will be set to false.

While the example uses reservations, it works the same for all connections.

The response to the previous example would look like this:

{
  "data": {
    "reservations": {
      "edges": [
        {"node": {...}},
        {"node": {...}},
        ... 8 more results       
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "bWFkZSB5b3UgbG9vaw=="
      }
    }
  }
}

Defaults

When no cursor arguments are provided, by default first:20 will be used, that is, only the first 20 items will be returned.

Unless otherwise specified on the field, maximum number of items a connection can return is 100.

Backward pagination

In addition to previously described forward pagination, 3RPMS also supports backwards pagination using last and before arguments, and startCursor and hasPreviousPage fields.

query RoomStays($cursor: String = null) {
    reservations(last:10 before:$cursor) {
        edges {
            node {
                # reservation fields
            }
        }
        pageInfo {
            hasPreviousPage
            startCursor
        }
    }
}

Here the last 10 reservations are returned. Similarly to before, to retrieve the previous 10 reservations, same query can be sent with $cursor set to value from $startCursor. When there are no previous reservations, hasPreviousPage will be false

GraphQL requests cannot be fully executed in some cases - malformed query, insufficient access, or validation errors. For schema and query errors, refer to GraphQL's specification https://spec.graphql.org/June2018/#sec-Errors. This section will cover only errors not part of the graphql specification.

Error Structure

In case of an error, a top-level error field will be returned by 3RPMS and will contain one or more errors. Each error will always have, at minimum, a message field.

In addition to graphql errors, 3RPMS will return the following errors:

• Configuration Errors - Errors that require hotel staff, or 3RPMS support intervention to resolve and will fail with any provided input. For example, some functionality has not been enabled for the hotel.
• Validation Errors - Errors that user is expected to be able to recover from by inputting different data. For example, value outside of expected range or some record not found.
• Auth Errors - Api token is not provided or is incorrect

Configuration

Configuration errors will have the extension.category field set to "configuration".

Configuration errors must not be shown to hotel guests, but may be shown to hotel staff and can be logged by your integration. These errors can be resolved only by hotel staff in 3RPMS system, or by contacting 3RPMS support. For example, some functionality has not been enabled for the hotel.

{
  "errors": [
    {
      "message": "This hotel has not beet set up to support Room Access Key api",
      "extensions": {
        "category": "configuration"
      },
    }
  ]
}

Validation

Validation errors always will have the extensions.category field set to "validation".

Validation errors are meant to be resolvable by end-users, for example, by modifying the form in your application, and attempting again. These errors are safe to show to hotel guests, and usually can be recovered from.

Argument errors

For errors related to input arguments, extensions.argumentPath field will contain a path to the field that caused an error (similar to path in GraphQL schema errors).

Request

query AvailableRooms {
    inventory(filter: {
        period: {
            start:"2022-09-08"
            end:"2022-09-08"
        }
        categories:["a", "b", "c"]
    }) {
        # ...
    }
}

In this example, filter has invalid data - a requested category ("c") does not exist.

Response

{
  "errors": [
    {
      "message": "Sorry, Property Category not found",
      "extensions": {
        "argumentPath": [
          "filter",
          "categories",
          2
        ],
        "category": "validation"
      },
      "path": [
        "inventory"
      ],
    }
  ]
}

extensions.argumentPath can be followed to find the field that caused an error.

Non-argument errors

For validation errors that cannot be attributed to any specific input input argument, extensions.argumentPath will not be added

Request

In this example, provided data is correct, but room cannot be updated for other reasons.

mutation CheckIn {
    updateRoomStay(input:{id:"119157" check_in:"2022-09-08T16:00:00+00:00"}) {
        roomStay {
            check_in
            check_out
        }
    }
}

Response

{
  "errors": [
    {
      "message": "This reservation was cancelled",
      "extensions": {
        "category": "validation"
      },
      "path": [
        "updateRoomStay"
      ]
    }
  ]
}

Validation message language

By default, validation error messages are in German. To see errors in English, add a Accept-Language header to each graphql request:

Accept-Language: en

Besides german de and english en no other language is supported at the moment.

Auth

"category": "auth" errors will be returned in the following cases:

• Missing api token (Authorization: Bearer api_... header)
• Api token incorrect
  • Token might have been disabled, or rotated
• Running a mutation with read-only permissions.

This error must not be shown to end-guests, but might be relevant for hotel staff.

Response

{
  "errors": [
    {
      "message": "Operation \"query\" not allowed",
      "extensions": {
        "category": "auth"
      }
    }
  ]
}

GraphQL Error

When a malformed query, non-existent field or other graphql-specific error is returned, there will be no extensions.category field:

{
  “errors”: [
    {
      “message”: “Syntax Error”
    }
  ]
}

GraphQL errors must not be shown to end-guests or hotel staff. These errors may require a change in your integration.

Query Fragments

You can encapsulate common data structures in Fragments and reuse them.

Without Fragments

In the following example, you will immediately notice that the data structure of guests and first_guest are identical due to the fact they both return objects of type Person. Scroll to the With Fragments section to see how this can be optimized.

query RoomStays {
  room_stays(filter: { date: "2022-10-27" }, first: 2) {
    edges {
      node {
        id
        room_setup {
          name
        }
        guests {
          clientTitle {
            name
          }
          firstname
          lastname
          language
          email
          telephone
          mobile
          carPlateNumber
        }
        first_guest {
          clientTitle {
            name
          }
          firstname
          lastname
          language
          email
          telephone
          mobile
          carPlateNumber
        }
      }
    }
  }
}

With Fragments

The previously redundant guests and first_guest data structure blocks now have been encapsulated in a reusable Fragment called Guest, so instead of repeating the complete list of attributes, it is enough to reuse the fragment by specifying it as ...Guest

query RoomStays {
                    room_stays(filter: { date: "2022-10-27" }, first: 2) {
                      edges {
                        node {
                          id
                          room_setup {
                            name
                          }
                          guests {
                            ...Guest
                          }
                          first_guest {
                            ...Guest
                          }
                        }
                      }
                    }
                  }
                  
                  fragment Guest on Person {
                    clientTitle {
                      name
                    }
                    firstname
                    lastname
                    language
                    email
                    telephone
                    mobile
                    carPlateNumber
                  }
                  

Query variables

A query without variables

In the following example, you will notice that a static value "2022-02-18" is provided for the date attribute:

query RoomStays {
    room_stays(
        filter: {
            date: "2022-02-18"
        }
    ) {
        edges {
            cursor
            node {
                id
                reservation {
                    code
                }
                room_setup {
                    expectedCleaningStatus(date: "2022-02-18")
                }
            }
        }
    }
}

A query with variables

This example demonstrates how the previously static value can be turned into a $date variable:

query RoomStays($date: Date!) {
    room_stays(
        filter: {
            date: $date
        }
    ) {
        edges {
            cursor
            node {
                id
                reservation {
                    code
                }
                room_setup {
                    expectedCleaningStatus(date: $date)
                }
            }
        }
    }
}

Now you can pass the value via $date variable and reuse it in the query if necessary.

Multiple queries within one request

Using aliases

You can perform multiple queries within one request using GrapQL aliases. In the following example, we will call performanceStatistics query twice but with different input arguments which very much makes sense if you want to get data for today and tomorrow, for example

Variables

{
    "today": "2022-03-01",
    "tomorrow": "2022-03-02"
}

Query

query PerformanceStatistics($today: Date!, $tomorrow: Date!) {
                    today: performanceStatistics(filter: { date: $today }) {
                      ...PerformanceStatistics
                    }
                    tomorrow: performanceStatistics(filter: { date: $tomorrow }) {
                      ...PerformanceStatistics
                    }
                  }
                  
                  fragment PerformanceStatistics on PerformanceStatistics {
                    occupancy
                    adr
                    revPAR
                  }
                  

Using batches

You can execute multiple GraphQL queries within one GraphQL request, like this:

Query

[
    {
        "query":"query PerformanceStatistics($date: Date!) { performanceStatistics(filter: { date: $date }) { occupancy } }",
        "variables": {
            "date": "2022-02-28"
        }
    }, 
    {
        "query":"query PerformanceStatistics($date: Date!) { performanceStatistics(filter: { date: $date }) { occupancy } }",
        "variables": {
            "date": "2022-02-27"
        }
    }
]

Chained Operations

The @chain(variable: [const]String!) directive enables passing data from one operation to the next, when sending batch operations. In the subsequent operation, the value is provided as a variable with the name specified in the directive.

This helps in cases, when a mutation depends on data returned by a previous mutation - using a @chain directive both mutations can be sent in one request instead of two

Example

An example, to create a guest and immediately reference it in the next mutation to add it to a room:

POST https://www.3rpms.de/graphql
                  Content-Type: application/json
                  Authorization: <your api token>
                  
                  [
                    {
                      "query": "mutation CreateGuest($createGuest: CreatePersonInput!) { createClient(input: {person: $createGuest}) { client { id @chain(variable:\"clientId\") } } }",
                      "variables": {
                        "createGuest": {
                          "lastname": "Přemyslid",
                          "country": "de",
                          "language": "de"
                        }
                      }
                    },
                    {
                      "query": "mutation AddGuestToRoom($roomStayId:ID! $clientId:ID!) { addRoomStayGuest(input:{roomStayId:$roomStayId clientId:$clientId}) { roomStay { guests { id } } } }",
                      "variables": {
                        "roomStayId": "<room id>"
                      }
                    }
                  ]
                  

Notice how the 2nd mutation AddGuestToRoom uses a variable $clientId that it does not provide - the variable comes from the previous mutation. However, if there were more operations, $clientId variable would not be available in the 3rd (or subsequent) operations - @chain directive provides variables only for the one subsequent operation.

According to GraphQL specification, queries and mutation selections can be executed in any order. To avoid determinism issues, there's the following restrictions on using @chain:

• @chain cannot be used on a field that is a descendant of a list [Type].
• Same variable name cannot be declared more than once.

In addition, to reduce accidental variable overwriting, there's also the following restrictions:

• @chain variable is not allowed to override a variable already sent in the request