<commit_before>h1. Xero API wrapper

h2. Introduction

This library is designed to help ruby / rails based applications communicate with the publicly available API for Xero.  If you are unfamiliar with the API, you should first read the documentation, located here "http://blog.xero.com/developer/":http://blog.xero.com/developer/

h2. Usage

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
</code></pre>

h2. Authenticating with OAuth

OAuth is built into this library in a very similar manner to the Twitter gem by <NAME> ("http://github.com/jnunemaker/twitter":http://github.com/jnunemaker/twitter). So if you've used that before this will all seem familiar.

h3. Consumer Key & Secret

First off, you'll need to get a Consumer Key/Secret pair for your application from Xero. 
Head to "http://api.xero.com":http://api.xero.com, log in and then click My Applications > Add Application. 

If you want to create a private application (that accesses your own Xero account rather than your users), you'll need to generate an RSA keypair and an X509 certificate.  This can be done with OpenSSL as below:
<pre><code>    openssl genrsa –out privatekey.pem 1024
    openssl req –newkey rsa:1024 –x509 –key privatekey.pem –out publickey.cer –days 365
    openssl pkcs12 –export –out public_privatekey.pfx –inkey privatekey.pem –in publickey.cer
</code></pre>

On the right-hand-side of your application's page there's a box titled "OAuth Credentials". Use the Key and Secret from this box in order to set up a new Gateway instance.

(If you're unsure about the Callback URL, specify nothing - it will become clear a bit later)

h3. Xero Gateway Initialization

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
</code></pre>

or for private applications

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::PrivateApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
</code></pre>


h3. Request Token

You'll then need to get a Request Token from Xero.

<pre><code>
    request_token = gateway.request_token
</code></pre>

You should keep this around - you'll need it to exchange for an Access Token later. (If you're using Rails, this means storing it in the session or something similar)

Next, you need to redirect your user to the authorisation url for this request token. In Rails, that looks something like this:

<pre><code>
    redirect_to request_token.authorize_url
</code></pre>

(Note that Xero doesn't support the OAuth Callback parameter here)

h3. Retrieving an Access Token

If you've specified a Callback URL when setting up your application, your user will be redirected to that URL with an OAuth Verifier as a GET parameter. You can then exchange your Request Token for an Access Token like this (assuming Rails, once again):

<pre><code>
    gateway.authorize_from_request(request_token.token, request_token.secret, :oauth_verifier => params[:oauth_verifier])
</code></pre>

(If you haven't specified a Callback URL, the user will be presented with a numeric verifier which they must copy+paste into your application; see examples/oauth.rb for an example)

Now you can access Xero API methods:

<pre><code>
    gateway.get_contacts
</code></pre>

h3. Storing Access Tokens

You can also store the Access Token/Secret pair so that you can access the API without user intervention. Currently, these access tokens are only valid for 30 minutes, and will raise a XeroGateway::OAuth::TokenExpired exception if you attempt to access the API beyond the token's expiry time.

<pre><code><commit_msg>Updated README to recognize that oauth_callback is now available in the Xero API.<commit_after>h1. Xero API wrapper

h2. Introduction

This library is designed to help ruby / rails based applications communicate with the publicly available API for Xero.  If you are unfamiliar with the API, you should first read the documentation, located here "http://blog.xero.com/developer/":http://blog.xero.com/developer/

h2. Usage

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
</code></pre>

h2. Authenticating with OAuth

OAuth is built into this library in a very similar manner to the Twitter gem by <NAME> ("http://github.com/jnunemaker/twitter":http://github.com/jnunemaker/twitter). So if you've used that before this will all seem familiar.

h3. Consumer Key & Secret

First off, you'll need to get a Consumer Key/Secret pair for your application from Xero. 
Head to "http://api.xero.com":http://api.xero.com, log in and then click My Applications > Add Application. 

If you want to create a private application (that accesses your own Xero account rather than your users), you'll need to generate an RSA keypair and an X509 certificate.  This can be done with OpenSSL as below:
<pre><code>    openssl genrsa –out privatekey.pem 1024
    openssl req –newkey rsa:1024 –x509 –key privatekey.pem –out publickey.cer –days 365
    openssl pkcs12 –export –out public_privatekey.pfx –inkey privatekey.pem –in publickey.cer
</code></pre>

On the right-hand-side of your application's page there's a box titled "OAuth Credentials". Use the Key and Secret from this box in order to set up a new Gateway instance.

(If you're unsure about the Callback URL, specify nothing - it will become clear a bit later)

h3. Xero Gateway Initialization

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
</code></pre>

or for private applications

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::PrivateApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
</code></pre>


h3. Request Token

You'll then need to get a Request Token from Xero.

<pre><code>
    request_token = gateway.request_token
</code></pre>

You should keep this around - you'll need it to exchange for an Access Token later. (If you're using Rails, this means storing it in the session or something similar)

Next, you need to redirect your user to the authorisation url for this request token. In Rails, that looks something like this:

<pre><code>
    redirect_to request_token.authorize_url
</code></pre>

You may also provide a callback parameter, which is the URL within your app the user will be redirected to. See next section for more information on what Xero sends in this request.

<pre><code>
    redirect_to request_token.authorize_url(:oauth_callback = "http://www.something.com/xero/complete")
</code></pre>

h3. Retrieving an Access Token

If you've specified a Callback URL when setting up your application or provided an oauth_callback parameter on your request token, your user will be redirected to that URL with an OAuth Verifier as a GET parameter. You can then exchange your Request Token for an Access Token like this (assuming Rails, once again):

<pre><code>
    gateway.authorize_from_request(request_token.token, request_token.secret, :oauth_verifier => params[:oauth_verifier])
</code></pre>

(If you haven't specified a Callback URL, the user will be presented with a numeric verifier which they must copy+paste into your application; see examples/oauth.rb for an example)

Now you can access Xero API methods:

<pre><code>
    gateway.get_contacts
</code></pre>

h3. Storing Access Tokens

You can also store the Access Token/Secret pair so that you can access the API without user intervention. Currently, these access tokens are only valid for 30 minutes, and will raise a XeroGateway::OAuth::TokenExpired exception if you attempt to access the API beyond the token's expiry time.

<pre><code>
{'fraction_non_alphanumeric': 0.07574980774160471, 'fraction_numerical': 0.007690335811330428, 'mean_word_length': 4.638005780346821, 'pattern_counts': {'":': 6, '<': 77, '<?xml version=': 0, '>': 81, 'https://': 0, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3339711', 'n_tokens_mistral': 2398, 'n_tokens_neox': 2262, 'n_words': 992}