A Ruby SDK to interact with the HomeAway API
Add this line to your application's Gemfile:
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
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 = ::::.(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:
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). 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
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.
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 = ::::.( 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
Each of the operations is detailed in the generated Yard documentation for this gem.
require 'homeaway_api' client = ::::.(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
If you install this gem, it will also install a command line utility named
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
The full API documentation is located at: https://www.homeaway.com/platform/documentation
Create a file
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.
- Fork it https://github.com/homeaway/homeaway_api_ruby
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create a new Pull Request