GraphQL

GraphQL reads the same trips, departures, guides and destinations as the booking API. Use it when one page needs several things at once, such as the organisation, a trip and the destinations menu, in a single request.

https://app.bifrostorbit.com/travel/api/cdn/graphql

GraphQL only reads. It can price a booking with quote, which saves and holds nothing; making bookings and the traveller account stay in the booking API.

Requests

GraphQL has one address for every organisation, so it needs to know whose trips to read. Either:

• send an API key as Authorization: Bearer <key> or x-api-key: <key>. The key says which organisation it belongs to, and a key that reads drafts (trv_sk_) adds draft trips, as in REST.
• or add ?organisation= and your booking name from Booking settings to the address, such as ?organisation=northwilds. Like the booking API, this needs no key.

With both, the key must belong to that organisation.

POST a JSON body:

1curl 'https://app.bifrostorbit.com/travel/api/cdn/graphql' \2  -H 'Authorization: Bearer trv_pk_…' \3  -H 'Content-Type: application/json' \4  -d '{"query":"query ($slug: String!) { trip(slug: $slug, locale: \"nb\") { name priceFrom currency } }","variables":{"slug":"lofoten-ridge-walk"}}'

GET works too, with query, variables (as JSON text) and operationName in the query string. URL-encode them:

curl -G 'https://app.bifrostorbit.com/travel/api/cdn/graphql' \  --data-urlencode 'organisation=northwilds' \  --data-urlencode 'query={ trips(country: "NO") { slug name nextDeparture } }'

Answers are JSON with data, and errors when something went wrong:

{ "data": { "trip": { "name": "Eggevandring i Lofoten", "priceFrom": 124000, "currency": "EUR" } } }

Any website may call it from a browser, as it may read the booking API. A key that reads drafts works only from a server; from another website it gets 403.

Queries

Every query takes locale, such as nb, which works as in the booking API. Leave it out for your main language. Each answer has its own locale and fallback.

Types

JSON holds data that keeps the booking API's shape, such as a trip's itinerary, packages and addOns, prices by currency and a country's facts. It cannot be selected into. See the booking API for what is inside.

Amounts are whole minor units, as in REST: 124000 with EUR is €1,240.00. seatsLeft and capacity are null for no limit.

Examples

A trip page

1query TripPage($slug: String!, $locale: String) {2  organisation(locale: $locale) {3    brandName4    payments {5      online6      publishableKey7    }8  }9  trip(slug: $slug, locale: $locale) {10    name11    description12    images {13      url14      alt15      width16      height17    }18    currency19    priceFrom20    departures {21      id22      startDate23      endDate24      status25      seatsLeft26      priceFrom27    }28    itinerary29    packages30    guides {31      name32      role33      image {34        url35      }36    }37  }38}

{ "slug": "lofoten-ridge-walk", "locale": "nb" }

Trips in a country with the destinations menu

1{2  trips(country: "NO") {3    slug4    name5    nextDeparture6    pricesFrom7  }8  destinations {9    key10    name11    countries {12      slug13      name14      tripCount15    }16  }17}

Errors

Errors come in errors, each with a message, a code under extensions, and the path and locations of the field that failed when there is one. The codes are the same as in REST:

1{2  "data": { "trip": null },3  "errors": [4    {5      "message": "Trip was not found",6      "locations": [{ "line": 1, "column": 3 }],7      "path": ["trip"],8      "extensions": { "code": "not_found" }9    }10  ]11}

• When trip, guide, continent or country fails, it is null and the other fields still answer.
• organisation, trips, guides and destinations never answer null, so when one of them fails the whole data is null.
• When several fields fail, the HTTP status comes from the first error.

Limits

• A query may be at most 20,000 characters long, nest at most 10 levels and ask for at most 300 fields. Each alias and each use of a fragment counts.
• Introspection is on and needs no key, so GraphQL tools can read the schema from the address. Introspection fields do not count towards the limits.
• Each calling address may make 120 requests a minute per organisation, and 30 quotes a minute. With ?organisation=, the 120 are shared with the booking API's reads; with a key, they are counted per key. Over that, the answer is 429.
• Persisted queries are not supported. Send the full query each time.

Caching

Every GraphQL answer has Cache-Control: no-store and Vary: Origin, Authorization, so nothing between your website and the API keeps it. Cache in your website instead, for as long as prices and places may be out of date. Travel Orbit doesn't send webhooks to your website (see Events). For pages a CDN should cache, the REST endpoints carry cache headers.