duffel_api 0.1.0 → 0.2.0

data/lib/duffel_api/request.rb

@@ -3,20 +3,24 @@
 require "json"
 
 module DuffelAPI
-  # A class that wraps an API request
+  # An internal class used within the library that represents a request to be made to
+  # the Duffel API, and which is able to dispatch that request
   class Request
     # Initialize a request class, which makes calls to the API
-    # @param connection
-    # @param method [Symbol] the method to make the request with
+    #
+    # @param connection [Faraday] a Faraday connection
+    # @param method [Symbol] the HTTP method to make the request with
     # @param path [String] the path to make the request to
-    # @param options [hash] options for the request
-    # @param headers [hash] headers to send with the request
-    def initialize(connection, method, path, options)
+    # @param headers [Hash] the HTTP request headers to send with the request
+    # @param params [Hash] Any paramters to include in the HTTP body
+    # @param query_params [Hash] Any parameters to include in the HTTP querystring
+    def initialize(connection, method, path, headers: {}, params: {}, query_params: {})
       @connection = connection
       @method = method
       @path = path
-      @headers = (options.delete(:headers) || {}).transform_keys(&:to_s)
-      @given_options = options
+      @headers = headers.transform_keys(&:to_s)
+      @option = params
+      @query_params = query_params
 
       @request_body = request_body
 
@@ -26,12 +30,18 @@ module DuffelAPI
       end
     end
 
-    # Make the request and wrap it in a Response object
-    def request
+    # Dispatches the request and returns the response
+    #
+    # @return [Response] the response from the request
+    def call
       Response.new(make_request)
     end
 
-    # Make the API request
+    private
+
+    # Actually makes the request to the API
+    #
+    # @return [Faraday::Response]
     def make_request
       @connection.send(@method) do |request|
         request.url @path
@@ -41,23 +51,29 @@ module DuffelAPI
       end
     end
 
-    # Fetch the body to send with the request
+    # Fetches the appropriate parameters to put into the request body, based on the HTTP
+    # method
+    #
+    # @return [Hash] the parameters to put into the request body, not yet JSON-encoded
     def request_body
       if @method == :get
         nil
       elsif %i[post put delete patch].include?(@method)
-        @given_options.fetch(:params, {})
+        @option
       else
         raise "Unknown request method #{@method}"
       end
     end
 
-    # Get the query params to send with the request
+    # Fetches the appropriate parameters to put into the request querystring, based on
+    # the HTTP method
+    #
+    # @return [Hash] the parameters to put into the request querystring
     def request_query
       if @method == :get
-        @given_options.fetch(:params, {})
+        @option
       else
-        @given_options.fetch(:query_params, {})
+        @query_params
       end
     end
   end

data/lib/duffel_api/resources/aircraft.rb

@@ -3,9 +3,14 @@
 
 module DuffelAPI
   module Resources
-    class Aircraft
+    class Aircraft < BaseResource
+      # @return [String]
       attr_reader :iata_code
+
+      # @return [String]
       attr_reader :id
+
+      # @return [String]
       attr_reader :name
 
       def initialize(object, response = nil)
@@ -15,11 +20,7 @@ module DuffelAPI
         @id = object["id"]
         @name = object["name"]
 
-        @response = response
-      end
-
-      def api_response
-        APIResponse.new(@response)
+        super(object, response)
       end
     end
   end

data/lib/duffel_api/resources/airline.rb

@@ -3,9 +3,14 @@
 
 module DuffelAPI
   module Resources
-    class Airline
+    class Airline < BaseResource
+      # @return [String, nil]
       attr_reader :iata_code
+
+      # @return [String]
       attr_reader :id
+
+      # @return [String]
       attr_reader :name
 
       def initialize(object, response = nil)
@@ -15,11 +20,7 @@ module DuffelAPI
         @id = object["id"]
         @name = object["name"]
 
-        @response = response
-      end
-
-      def api_response
-        APIResponse.new(@response)
+        super(object, response)
       end
     end
   end

data/lib/duffel_api/resources/airport.rb

@@ -3,16 +3,35 @@
 
 module DuffelAPI
   module Resources
-    class Airport
+    class Airport < BaseResource
+      # @return [Hash, nil]
       attr_reader :city
+
+      # @return [String]
       attr_reader :city_name
+
+      # @return [String]
       attr_reader :iata_code
+
+      # @return [String]
       attr_reader :iata_country_code
+
+      # @return [String]
       attr_reader :icao_code
+
+      # @return [String]
       attr_reader :id
+
+      # @return [Float]
       attr_reader :latitude
+
+      # @return [Float]
       attr_reader :longitude
+
+      # @return [String]
       attr_reader :name
+
+      # @return [String]
       attr_reader :time_zone
 
       def initialize(object, response = nil)
@@ -29,11 +48,7 @@ module DuffelAPI
         @name = object["name"]
         @time_zone = object["time_zone"]
 
-        @response = response
-      end
-
-      def api_response
-        APIResponse.new(@response)
+        super(object, response)
       end
     end
   end

data/lib/duffel_api/resources/base_resource.rb

@@ -8,6 +8,9 @@ module DuffelAPI
         @response = response
       end
 
+      # Returns the raw API response where this resource originated from
+      #
+      # @return [APIResponse]
       def api_response
         APIResponse.new(@response)
       end

data/lib/duffel_api/resources/offer_passenger.rb

@@ -4,11 +4,22 @@
 module DuffelAPI
   module Resources
     class OfferPassenger < BaseResource
+      # @return [String, nil]
       attr_reader :type
+
+      # @return [Array<Hash>]
       attr_reader :loyalty_programme_accounts
+
+      # @return [String]
       attr_reader :id
+
+      # @return [String, nil]
       attr_reader :given_name
+
+      # @return [String, nil]
       attr_reader :family_name
+
+      # @return [String, nil]
       attr_reader :age
 
       def initialize(object, response = nil)

data/lib/duffel_api/resources/offer_request.rb

@@ -3,13 +3,26 @@
 
 module DuffelAPI
   module Resources
-    class OfferRequest
+    class OfferRequest < BaseResource
+      # @return [String, nil]
       attr_reader :cabin_class
+
+      # @return [String]
       attr_reader :created_at
+
+      # @return [String]
       attr_reader :id
+
+      # @return [Boolean]
       attr_reader :live_mode
+
+      # @return [Array<Hash>]
       attr_reader :offers
+
+      # @return [Array<Hash>]
       attr_reader :passengers
+
+      # @return [Array<Hash>]
       attr_reader :slices
 
       def initialize(object, response = nil)
@@ -23,11 +36,7 @@ module DuffelAPI
         @passengers = object["passengers"]
         @slices = object["slices"]
 
-        @response = response
-      end
-
-      def api_response
-        APIResponse.new(@response)
+        super(object, response)
       end
     end
   end

data/lib/duffel_api/response.rb

@@ -1,26 +1,40 @@
 # frozen_string_literal: true
 
 module DuffelAPI
+  # An internal class used within the library to represent a response from the Duffel
+  # API
   class Response
     extend Forwardable
 
     def_delegator :@response, :headers
     def_delegator :@response, :status, :status_code
 
+    # Wraps a `Faraday::Response` in the library's own internal response class
+    #
+    # @param [Faraday::Response] response
+    # @return [Response]
     def initialize(response)
       @response = response
     end
 
+    # Returns the raw body of the HTTP response
+    #
+    # @return [String]
     def raw_body
       @response.body
     end
 
-    # Return the body of parsed JSON body of the API response
+    # Return the parsed JSON body of the API response, if a body was returned
+    #
+    # @return [Hash, nil]
     def parsed_body
       JSON.parse(raw_body) unless raw_body.empty?
     end
 
-    # Returns the meta hash of the response
+    # Returns the `meta` data returned from the Duffel API, if present. If not present,
+    # returns an empty hash (`{}`).
+    #
+    # @return [Hash]
     def meta
       return {} if parsed_body.nil?
 
@@ -29,17 +43,22 @@ module DuffelAPI
       {}
     end
 
-    # Returns the request ID from the response headers
+    # Returns the request ID from the Duffel API, included in the response headers.
+    # This could be `nil` if the response didn't make it to the Duffel API itself and,
+    # for example, only reached a load balancer.
+    #
+    # @return [String, nil]
     def request_id
       normalised_headers["x-request-id"]
     end
 
     private
 
+    # Returns the HTTP response headers, with all of their keys in lower case
+    #
+    # @return [Hash]
     def normalised_headers
       headers.transform_keys(&:downcase)
     end
-
-    def json?; end
   end
 end

data/lib/duffel_api/services/aircraft_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class AircraftService < BaseService
+      # Lists aircraft, returning a single page of results
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/aircraft"
 
@@ -15,6 +21,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:Aircraft`
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         DuffelAPI::Paginator.new(
           service: self,
@@ -22,6 +35,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single aircraft by ID
+      #
+      # @param id [String]
+      # @return [Resources::Aircraft]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/aircraft/:id", "id" => id)
 

data/lib/duffel_api/services/airlines_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class AirlinesService < BaseService
+      # Lists airports, returning a single page of results
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/airlines"
 
@@ -15,6 +20,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:Airline`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         DuffelAPI::Paginator.new(
           service: self,
@@ -22,6 +34,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single airline by ID
+      #
+      # @param id [String]
+      # @return [Resources::Airline]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/airlines/:id", "id" => id)
 

data/lib/duffel_api/services/airports_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class AirportsService < BaseService
+      # Lists airports, returning a single page of results
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/airports"
 
@@ -15,6 +21,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:Airport`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         DuffelAPI::Paginator.new(
           service: self,
@@ -22,6 +35,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single airport by ID
+      #
+      # @param id [String]
+      # @return [Resources::Airport]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/airports/:id", "id" => id)
 

data/lib/duffel_api/services/base_service.rb

@@ -5,22 +5,35 @@ require "cgi"
 module DuffelAPI
   module Services
     class BaseService
+      extend Forwardable
+
+      # Sets up a resource-specific service based on an API service
+      #
+      # @param api_service [APIService]
+      # @return [BaseService]
       def initialize(api_service)
         @api_service = api_service
       end
 
-      def make_request(method, path, options = {})
-        @api_service.make_request(method, path, options)
-      end
-
       private
 
+      def_delegator :@api_service, :make_request
+
+      # Fills in variables in a patterned URL (e.g. `/widgets/:id`)
+      #
+      # @param url [String]
+      # @param param_map [Hash]
+      # @return [String]
       def substitute_url_pattern(url, param_map)
         param_map.reduce(url) do |new_url, (param, value)|
           new_url.gsub(":#{param}", CGI.escape(value))
         end
       end
 
+      # Extracts the data inside the `data` envelope from an API response
+      #
+      # @param parsed_body [Hash]
+      # @return [Hash]
       def unenvelope_body(parsed_body)
         parsed_body["data"]
       end

data/lib/duffel_api/services/offer_passengers_service.rb

@@ -3,6 +3,13 @@
 module DuffelAPI
   module Services
     class OfferPassengersService < BaseService
+      # Updates an offer passenger, based on the offer ID and passenger ID
+      #
+      # @param offer_id [String]
+      # @param passenger_id [String]
+      # @option [required, Hash] :params the payload for updating the passenger
+      # @return [Resources::OfferPassenger]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def update(offer_id, passenger_id, options = {})
         path = substitute_url_pattern(
           "/air/offers/:offer_id/passengers/:passenger_id",

data/lib/duffel_api/services/offer_requests_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class OfferRequestsService < BaseService
+      # Creates an offer request
+      #
+      # @option [required, Hash] :params the payload for creating the offer request,
+      #   including parameters to be sent in the querystring
+      # @return [Resources::OfferRequest]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/offer_requests"
 
@@ -34,6 +40,12 @@ module DuffelAPI
         Resources::OfferRequest.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Lists offer requests, returning a single page of results.
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/offer_requests"
 
@@ -46,6 +58,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:OfferRequest`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         Paginator.new(
           service: self,
@@ -53,6 +72,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single offer request by ID
+      #
+      # @param id [String]
+      # @return [Resources::OfferRequest]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/offer_requests/:id", "id" => id)
 

data/lib/duffel_api/services/offers_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class OffersService < BaseService
+      # Lists offers, returning a single page of results.
+      #
+      # @option [required, Hash] :params Parameters to include in the HTTP querystring,
+      #   including any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/offers"
 
@@ -15,6 +21,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:Offers`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         Paginator.new(
           service: self,
@@ -22,6 +35,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single offer by ID
+      #
+      # @param id [String]
+      # @return [Resources::Offer]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/offers/:id", "id" => id)
 

data/lib/duffel_api/services/order_cancellations_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class OrderCancellationsService < BaseService
+      # Creates an order cancellation
+      #
+      # @option [required, Hash] :params the payload for creating the order cancellation
+      # @return [Resources::OrderCancellation]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/order_cancellations"
 
@@ -22,6 +27,11 @@ module DuffelAPI
         Resources::OrderCancellation.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Confirms an order cancellation by ID
+      #
+      # @param id [String]
+      # @return [Resources::OrderCancellation]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def confirm(id, options = {})
         path = substitute_url_pattern("/air/order_cancellations/:id/actions/confirm",
                                       "id" => id)
@@ -42,6 +52,12 @@ module DuffelAPI
         Resources::OrderCancellation.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Lists offers, returning a single page of results.
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/order_cancellations"
 
@@ -54,6 +70,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:OrderCancellation`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         Paginator.new(
           service: self,
@@ -61,6 +84,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single order cancellation by ID
+      #
+      # @param id [String]
+      # @return [Resources::OrderCancellation]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/order_cancellations/:id", "id" => id)