HomeAway API

A Ruby SDK to interact with the HomeAway API

Installation

Add this line to your application's Gemfile:

gem 'homeaway-api'

And then execute in the checked out directory to install into your system gems:

$ rake install

or to install into your bundle:

$ bundle exec rake install

Usage

Authenticating

In order to use this gem, you must first have a HomeAway API client ID and client secret. Both of these can be obtained by registering yourself as an API developer at https://www.homeaway.com/platform/myClients

Once you have these credentials, to use this gem:

require 'homeaway_api'
client = HomeAway::API::Client.new(client_id: 'your_client_id', client_secret: 'your_client_secret')

This will automatically have your client authenticate with HomeAway. If you wish to have your application be able to access the personal HomeAway data of the user of your application, you need to call:

client.auth_url

which will return back a URL as a String that the user of your application must be sent to. It is up to you to define how that takes place.

Note: You are recommended to save the client.state value. It is used to prevent your application from CSRF attacks ([http://homakov.blogspot.pt/2012/07/saferweb-most-common-oauth2.html](more details)). Saving it in the session is one way to achieve this, you will need to access this value again once the user is redirected back to your application and to ensure it's identicity with the one given then.

Example with a RubyOnRails controller:

session["homeaway-api.state"] = client.state

Once your user goes to that url they will be prompted to login with their HomeAway credentials. As soon as they do that and authorize your application to access their HomeAway data, the client's web browser will be redirected back to the redirect url that you specified when you created your client above. This url will have the code and state parameters appended to it.

It's now time to ensure that this state parameter is present and identical to the previously saved state value. If this value have changed, it as then been tempered and certainly the reason of a CSRF attack, and should not perform the next step.

Once the state validated and you are able to grab that code, you can use it with this gem:

client.oauth_code = code_received_from_redirect_url

As soon as you make that assignment, the client will contact HomeAway and obtain a token that can be used for interacting with the HomeAway account of that user. By default, this token has a 6 month expiration time.

Using an existing token

If you have a token string saved from a previous use of the HomeAway API it can be reused with this SDK to avoid having your user login to HomeAway again.

client = HomeAway::API::Client.new(
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    token: 'saved_token_value'
)

Custom configuring the client

You will usually not need to do this often as the defaults will be sufficient for most use cases, but if necessary, you can specify any subset of the fields below:

client.configure do |c|
    site: <site>, #override the hostname of the api
    port: <port>, #defaults to 443
    logger: <logger_instance>, #supply your own custom logger instance
    cache_control: <value>, #set a custom cache control header to be sent on each request
    auto_pagination: <true or false>, #will paginated resources automatically traverse their pages when being iterated over
    connection_opts: <opts>, #set any connection options to the underlying Faraday connection object, must be a hash
    page_size: <size>, #overwrite the default page size (10)
    test_mode: <true or false> #enable or disable test mode, default disabled
end

Operations

Each of the operations is detailed in the generated Yard documentation for this gem.

Quickstart

require 'homeaway_api'
client = HomeAway::API::Client.new(client_id: your_client_id, client_secret: your_client_secret)
response = @client.listing '123456', ['AVAILABILITY', 'RATES']
paginator = @client.search '4 bathrooms new york'
paginator.each do |search_result|
  listing =  @client.listing search_result.listing_id, ['DETAILS', 'RATES', 'LOCATION']
  puts listing
end

hacurl

If you install this gem, it will also install a command line utility named hacurl. hacurl is a tool that allows developers to easily interact with the HomeAway API without writing a single line of code. The available options:

$ Usage: hacurl [options] url
    -i, --client-id CLIENT_ID        your client id
    -s CLIENT_SECRET,                your client secret
        --client-secret
    -e, --email EMAIL                optional email address to use for operations that require 3-legged-oauth
    -p, --password PASSWORD          optional password to use for operations that require 3-legged-oauth
    -d, --data FILE                  path to file for any operations that require a body (PUT OR POST)
    -X, --method METHOD              method to send (GET, PUT, POST)
    -a, --get-auth                   only output the bearer authorization
    -v, --verbose                    print verbose information
    -t, --traveler                   login as a traveler
    -o, --owner                      login as an owner (the default)

An example invocation would be:

$ hacurl -i <your_client_id> -s <your_client_secret> /public/listing?id=123456

Other

The full API documentation is located at: https://www.homeaway.com/platform/documentation

Running tests

Create a file internal/spec_helper_extensions.rb with:

def client_id
  "your-application-client-id"
end

def client_secret
  "your-application-client-secret"
end

def test_email
  "your-homeaway-email"
end

def test_password
  "your-homeaway_password"
end

Run specs with bundle exec rspec spec.

Contributing

1. Fork it https://github.com/homeaway/homeaway_api_ruby
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request