@duffel/api

Duffel API Javascript Client

The Duffel JavaScript client library - sometimes known as an SDK - makes it easy to interact with the Duffel API from your server-side JavaScript applications.

Content

• Requirements
• Installation
• Usage
• Configuration
• Contributing
• Documentation

Requirements

To use the Duffel JavaScript client library, you'll need to be using Node.js v12 (LTS) or later.

You can only use the library in server-side JavaScript applications developed in Node.js. It won't work in frontend applications that run in your users' browsers.

Usage

To get started, import the Duffel module into your code and initialise it using your access token, which you can get from the "Access tokens" page in your Duffel dashboard:

import { Duffel } from '@duffel/api'

const duffel = new Duffel({
  // Store your access token in an environment variable, keep it secret and only readable on your server
  token: process.env.DUFFEL_ACCESS_TOKEN,
})

// To quickly test whether your integration is working, you can get a single aircraft by its Duffel ID
const aircraft = await duffel.aircraft.get('arc_00009VMF8AhXSSRnQDI6Hi')
console.log(aircraft)

TypeScript

The Duffel JavaScript client library is written in TypeScript and comes with types for Duffel API objects, which you can easily import.

import { Aircraft } from '@duffel/api'

const response = await duffel.aircraft.get('arc_00009VMF8AhXSSRnQDI6Hi')
const aircraft: Aircraft = response.data

Getting a single object

As a general rule, you get a single object from the API by its ID.

const aircraft = await duffel.aircraft.get('arc_00009VMF8AhXSSRnQDI6Hi')

Sometimes, you can pass in optional query parameters:

duffel.offers.get(offer_id, {
  return_available_services: true,
})

If your request was successful, the get function will return the response body as an object. Inside the data field, you'll find the resource you requested.

const aircraft = await duffel.aircraft.get('arc_00009VMF8AhXSSRnQDI6Hi')
console.log(aircraft)

Expected output from console.log(aircraft):

{
  "data": [
    {
      "name": "Airbus Industries A380",
      "id": "arc_00009UhD4ongolulWd91Ky",
      "iata_code": "380"
    }
  ]
}

Errors

If there are any errors with your request, the client library will throw an error which you can catch. The error object will expose all of the error information returned by the API.

You'll find information about what was wrong in the errors field, and useful context like the status and request_id (which you should use when contacting the Duffel support team) inside the meta field.

try {
  const test = await duffel.aircraft.get('nonexistent_id')
  // The request failed, so we won't hit this
  console.log(test)
} catch (error) {
  console.log(error)
}

Expecting output from console.log(error) similar to:

{
  "meta": { "status": 404, "request_id": "Fn6SwqLT_Isf3CAAAEah" },
  "errors": [
    {
      "type": "invalid_request_error",
      "title": "Not found",
      "message": "The resource you are trying to access does not exist.",
      "documentation_url": "https://duffel.com/docs/api/overview/errors",
      "code": "not_found"
    }
  ]
}

Listing objects

Our "List" APIs only return a set number of results by default. You can find out more about pagination in the Duffel API in general here. In the client library, we provide two ways to use list endpoints - one that allows you to take advantage of automatic pagination, and one that allows you to paginate manually.

Automatic Pagination

We recommend automatic pagination. You can use async iterators to auto-paginate through all the results with our listWithGenerator method. If you're not familiar with it, you can read more about async iteration and generators here.

// This is how you can iterate over all the objects using the generator
const airlines = duffel.airlines.listWithGenerator()
for await (const airline of airlines) {
  console.log(airline)
  /* Expecting output similar to:
   * {
   *   "data": {
   *     "name": "British Airways",
   *     "id": "aln_00001876aqC8c5umZmrRds",
   *     "iata_code": "BA"
   *   }
   * }
   */
}

// Alternatively, you can go through the objects one by one
const aircraft = duffel.aircraft.listWithGenerator()
const firstAircraft = await aircraft.next()
console.log(firstAircraft.value)
/* Expecting output similar to
 * {
 *   "data": {
 *     name: "Airbus Industries A380",
 *     id: "arc_00009UhD4ongolulWd91Ky",
 *     iata_code: "380"
 *   }
 * }
 */
if (!firstAircraft.done) {
  const secondAircraft = await aircraft.next()
  console.log(secondAircraft.value)
}

Manual pagination

Alternatively, you can paginate manually. The list method simply returns the page of the API you've requested, with the metadata that you need to then request the next (or previous) page inside meta.

const firstPage = await duffel.airlines.list()
console.log(firstPage)
/* Expected output:
 * {
 *   data: [{
 *     name: "Airbus Industries A380",
 *     id: "arc_00009UhD4ongolulWd91Ky",
 *     iata_code: "380"
 *   }, ...],
 *   meta: {
 *     limit: 50,
 *     before: null,
 *     after: 'g3QAAAACZAACaWRtAAAAGmFybF8wMDAwOVZNRTdEQUdpSmp3b21odjJ6ZAAEbmFtZW0AAAAPQWJlbGFnIEF2aWF0aW9u'
 *   }
 * }
 */

// You can then manually paginate by passing in the relevant query parameters
const nextPage = await duffel.airlines.list({
  limit: firstPage.meta.limit,
  after: firstPage.meta.after,
})
console.log(nextPage)

Creating objects

Typically, you'll create a resource by passing in the relevant body. In some cases, you can pass in relevant query parameters too.

const offerRequestResponse = await duffel.offerRequests.create({
  slices: [
    {
      origin: 'NYC',
      destination: 'ATL',
      departure_date: '2021-06-21',
    },
  ],
  passengers: [{ type: 'adult' }],
  cabin_class: 'economy',
  return_offers: false,
})

console.log(offerRequestResponse.data.id)

Actions

On certain endpoints you can perform actions, such as confirming an order cancellation. Usually you'll do that by just passing in the ID, but sometimes you can also pass in optional query parameters.

const orderCancellationResponse = await duffel.orderCancellations.confirm(
  order_cancellation_id,
)
console.log(orderCancellationResponse.data.id)

Update

On certain endpoints you can perform updates, such as updating an order. Usually you'll do that by passing the object ID with the object data changes.

const orderUpdateResponse = await duffel.orders.update(
  'ord_00009hthhsUZ8W4LxQgkjo',
  {
    metadata: {
      payment_intent_id: 'pit_00009htYpSCXrwaB9DnUm2',
    },
  },
)

console.log(orderUpdateResponse.data.id)

And if you want to clear metadata:

const orderUpdateResponse = await duffel.orders.update(
  'ord_00009hthhsUZ8W4LxQgkjo',
  {
    metadata: {},
  },
)

console.log(orderUpdateResponse.data.id)

Configuration

Test and live modes

To use the Duffel test mode, make sure you're using a "test" token. And for live mode, make sure to use a "live" token.

Timeouts

In the future we plan to make timeouts configurable, but at the moment the library does not yet support that. You can read more about the API response times here.

Logging

We currently provide some basic logging in the library, and there are plans to add more telemetry options in the future. You can turn on verbose debug mode if you want to check what endpoints are being called and with what arguments.

const duffel = new Duffel({
  // We recommend storing your access token in an environment variable for security
  token: process.env.DUFFEL_ACCESS_TOKEN,
  debug: { verbose: true },
})

Documentation

You can learn more about the Duffel API and the library in our documentation.