#traxo_api

The 'traxo_api' gem is a Ruby wrapper meant to simplify the processes of both authorizing applications and creating interactions with the Traxo API.

Currently, methods for the member, accounts, trips, and air segments endpoints of Traxo's API have been implemented. More sections are hopefully soon to come.

###README Contents:

• Installation
• Usage
  • Authorization
  • CRUD
• Documentation
• License
• Contributing
• Links
• Contact

##Installation

Add this line to your application's Gemfile:

gem 'traxo_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install traxo_api

##Usage

###Authorization Traxo's API uses the OAuth 2.0 standard for authorization. Additionally, Traxo enforces two later security additions: a redirect URL and a state parameter.

To gain authorization from a Traxo user, you will need to register your application with Traxo. Once registered, you will need to retrieve your your client ID and client secret from the API's website where you will also need to register a redirect url for the application.

See the authorization documentation for a list and detailing of available authorization methods.

####Example of authorization controller flow

class TraxoController < ApplicationController
	def auth
	    t = Traxo::Auth.new('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URL')
	    state = 'SOME_STRING'
	    redirect_to t.request_code_url(state)
	end
	
	def auth_success
	    t = Traxo::Auth.new('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URL')
	    
	    # this conditional is not required, but uses CSRF protection made possible 
	    # by Traxo's enforcement of a state parameter in authorization requests
	    if params[:state] == 'SOME_STRING'
	      code = params[:code]
	      response = t.exchange_request_code(code)
	    
	      access_token = response[:access_token] # used to authorize requests
	      lifetime = response[:expires_in] # seconds until access_token expires
	      refresh_token = response[:refresh_token] # used to request new tokens
	      
	      # store tokens (and use elsewhere for CRUD requests)...
	    end
	end
end

###CRUD Once a user has authorized your application and you have a valid access token, you can start making CRUD (create, read, update, delete) requests to the Traxo API on their behalf. There are a multiple response formats available (by default, a Hash of the parsed JSON body). HTTP errors/failures can be configured to be ignored (default; will still return the response as in the format configured), raise exceptions, or to return false for the CRUD method being called.

See the endpoint documentation for response formatting and error handling. Individual endpoint methods are also detailed in the documentation.

####Example of getting user's Traxo details and creating a trip

t = Traxo::Client.new('ACCESS_TOKEN', 'CLIENT_ID', 'CLIENT_SECRET')
t.get_member # => Hash of properties for user's Traxo account

args = {
  begin_datetime: '2015-06-01', # can be String or Date or Datetime
  end_datetime: '2015-06-08', # can be String or Date or Datetime
  destination: 'Little Rock, AR',
  headline: 'Good times in the Rock',
  personal: true
}
t.create_trip(args) # => Hash of properties for the user's freshly created trip

View the documentation
Covers more in-depth usage and the public methods available within this gem.

##License View MIT License

If you find a bug, please feel free to open an issue. I aim to actively maintain this project for now as I continue to work towards implementing the remaining endpoint sections.

If you would like to contribute code of your own (whether to fix a bug or to add a feature), please feel free to do the following:

1. Fork it ( https://github.com/wilchandler/traxo_api/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Make sure previous tests are passing (some are currently pending from my removing features). Additional tests for new code would also be appreciated.
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

• Traxo's user website
• Traxo's developer website

Website | Email | Twitter | LinkedIn | GitHub Note: the creator of this gem is not affiliated with Traxo.