A Java client library for the Duffel API.
- Java 11+
- A Duffel API access token (get started here ✨)
In most cases, you'll want to add Duffel SDK to your project as a dependency by adding it to your build.gradle or pom.xml file.
dependencies {
implementation 'com.duffel:duffel-api:1.1.9'
}<dependency>
<groupId>com.duffel</groupId>
<artifactId>duffel-api</artifactId>
<version>1.1.9</version>
</dependency>You can see a complete end-to-end example of searching and booking using the client library in example/com.duffel.example.SearchAndBookIT.java.
The library's functionality is accessed from a com.duffel.DuffelApiClient instance.
To initialise a DuffelApiClient, all you'll need is your API access token:
import com.duffel.DuffelApiClient;
DuffelApiClient client = new DuffelApiClient("api_token");In this readme, we'll use the term "resources" to refer to the different Duffel concepts that you can act on in the API - for example airports, offers, orders and payment intents.
We'll refer to instances of each of these resources - an airport, an offer, a payment intent - as "records".
In the Duffel API reference, the resources are listed in the sidebar. For each resource, you'll find:
- a schema, which describes the data attributes we expose for each record from this resource
- a list of actions you can perform related to that resource (e.g. for Orders, you can "Get a single order", "Update a single order", "List orders" and "Create an order")
The Java client library is structured around these resources. Each resource has its own "service" which you use to perform actions. These services are accessible from your DuffelApiClient instance:
e.g.
client.aircraftService
...
client.orderService
client.seatMapsServiceTo see what actions are available for each resource, check out the definitions for the service classes here.
Most resources allow you to create a record. In fact, the most important flows in the Duffel API start with creating a record. You'll do this with the #post method exposed on a service.
For example, you'll search for flights by creating an offer request:
OfferRequest.Slice slice = new OfferRequest.Slice();
slice.setDepartureDate("2022-06-15");
slice.setOrigin("LHR");
slice.setDestination("STR");
Passenger passenger = new Passenger();
passenger.setType(PassengerType.adult);
passenger.setGivenName("Test");
passenger.setFamilyName("User");
OfferRequest request = new OfferRequest();
request.setMaxConnections(0);
request.setCabinClass(CabinClass.economy);
request.setSlices(List.of(slice));
request.setPassengers(List.of(passenger));
OfferResponse offerResponse = client.offerRequestService.post(request);
LOG.info(offerResponse.getId());The #post method returns the created record.
Many resources in the Duffel API (e.g. airports, orders and offers) allow you to list their records.
For example, you can get a list of all the airports that Duffel knows about - that is, a list of airport records.
For performance reasons, we paginate records in the API when listing. You can only see up to 200 at a time. You'll need to page through, like moving through pages of a book.
Clients can page through results by usage of the before and after parameters:
# Initial page
AircraftCollection page = client.aircraftService.getPage();
# Next page
page = client.aircraftService.getPage(null, page.getAfter(), null);
# Previous page
page = client.aircraftService.getPage(page.getBefore(), null, null);Watch out! There is one kind of list in the Duffel API which isn't paginated: seat maps.
When you call client.seatMapsService.getById("off_123"), all of the seat maps will be returned at once in a single List<SeatMap>.
Many resources in the Duffel API allow you fetch a single record (e.g. an airport, a payment intent) if you know its ID.
You do that using the #getById method on a resource like this:
Airline airline = client.airlineService.getById("arl_00009VME7DBKeMags5CliQ");
LOG.info(airline.getIataCode());The #getById method returns the record.
Some records in the Duffel API allow you to update them after they've been created, if you know their ID.
That works like this using the #update method on a resource:
OrderUpdate update = new OrderUpdate();
update.setMetadata(Map.of("myKey", "myValue"));
Order order = client.orderService.update("ord_0000AKY0JiKODHllshwjaq", update);The #update method returns the updated record.
Some resources allow you to perform special actions on their records - for example confirming an order cancellation or pinging a webhook.
The methods you'll use to do this aren't named consistently, because each resource has different actions. For example, you'll call #confirm to confirm an order cancellation but #ping to ping a webhook.
It'll look a bit like this:
client.orderCancellationService.confirm("ore_00009qzZWzjDipIkqpaUAj")In general, these action methods return the record you've acted on.
Watch out! There is one action in the API which doesn't return the record you've acted on.
When you ping a webhook with client.webhookService.ping("end_0000AMRu3m28KGtNP1o01Y"), it returns void or will throw an exception.
When the Duffel API returns an error, the library will raise an exception.
We have an exception class for each of the possible types of error which the API can return, documented here in the API reference. For example, if the API returns an error with type invalid_state_error, the library will throw a DuffelException exception, with errors containing a StandardError with type invalid_state_error.
You can catch these exceptions and inspect the various fields within the errors list and meta data: #message, #title, #code, #request_id, etc.