Skip to content

Commit

Permalink
Merge pull request #29 from XeroAPI/oauth_2_and_faraday
Browse files Browse the repository at this point in the history 
Oauth 2 and faraday
  • Loading branch information
@SerKnight
SerKnight authored Apr 17, 2020
2 parents 9a40478 + 5d7cd70 commit a252806
Show file tree
Hide file tree
Showing 246 changed files with 879 additions and 679 deletions.
31 changes: 4 additions & 27 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,17 +37,6 @@ We have an official [message board](https://community.xero.com/developer) where

You can contribute by reporting bugs, suggesting enhancements, improving documentation i.e. [README](https://github.com/XeroAPI/xero-ruby/README.md) or submitting a pull request.


## Which version of the SDK are you using?

As of Sept 2019, support for oAuth 2 will be generally available for developers. During this transition period from oAuth 1.0a to oAuth 2, we will be supporting two versions of the SDK.


* 2.x code resides in `master` and supports oAuth 1.0a
* 3.x code resides in the `oauth2` branch and supports oAuth 2

Bugs and enhancements for version 3.x will be prioritized over 2.x.

## Reporting Bugs

Bugs are tracked as issues in this repository.
Expand Down Expand Up @@ -76,29 +65,17 @@ When opening an issue for a feature request:

## Pull requests

We welcome your feedback and pull requests. Be aware some code is generated and pull requests may not be the best solution - see below.
We welcome your feedback and pull requests. Be aware some code is generated and pull requests may not be the best solution - see below.

### We Use OpenAPI Generator
The best way to propose changes to the codebase is to open an [issue](https://github.com/XeroAPI/xero-ruby/issues) and discuss with our team.

We are using [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) and [our OpenAPI specs](https://github.com/XeroAPI/Xero-OpenAPI), to create and update our models and client classes. Improvements may require updates to our OAS or our customized mustache templates instead of modifying via pull request.
We are using [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) and [our OpenAPI specs](https://github.com/XeroAPI/Xero-OpenAPI), to create and update our models and client classes. Improvements may require updates to our OAS or our customized mustache templates instead of modifying via pull request.

### Submit a pull request

1. Fork and clone the repository
1. Create a new branch: `git checkout -b my-branch-name`
1. Make your change, add tests if needed
1. Make sure the tests pass on your machine
1. Push to your fork and submit a pull request
1. Pat your self on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

- Follow the [style guide](#style-guide).
- Write tests.
- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

Xero's supported SDK's are mostly auto-generated based on an [OpenAPISpec](https://github.com/XeroAPI/Xero-OpenAPI) that utilizes [openapi-generator](https://github.com/OpenAPITools/openapi-generator).
> You can read more about our process here: https://devblog.xero.com/building-sdks-for-the-future-b79ff726dfd6
### Style Guide

* 2 spaces for indentation rather than tabs
Expand Down
171 changes: 102 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,107 +5,140 @@ Xero Ruby SDK for OAuth 2.0 generated from [Xero API OpenAPI Spec](https://githu

## Current release of SDK with OAuth 2.0 support
Version 0.x.x of Xero Ruby SDK only supports OAuth 2.0 authentication and the following API sets.
* accounting
* identity
* [accounting](https://developer.xero.com/documentation/api/api-overview)

Coming soon
* [assets](https://developer.xero.com/documentation/assets-api/overview)
* bank feeds
* payroll au
* fixed asset
* payroll nz/uk
* files
* projects
* xero hq

## How to handle OAuth 2.0 authentication & authorization?
We have built an Omniauth strategy for Xero OAuth 2.0. Check out [omniauth-xero-oauth2](https://github.com/XeroAPI/xero-oauth2-omniauth-strategy)

[![RubyGem](https://img.shields.io/badge/omniauth--xero--oauth2%20gem-v0.9.3-brightgreen)](https://rubygems.org/gems/omniauth-xero-oauth2)

To learn more about how our OAuth 2.0 flow works and how to use our Omniauth strategy, check out our Xero developer blog post: [Xero OAuth 2.0 with Ruby](https://devblog.xero.com/xero-oauth-2-with-ruby-313a6ea37989)

![image](https://user-images.githubusercontent.com/41350731/70225201-b2324080-17a2-11ea-8966-23efafa6df52.png)

## Looking for OAuth 1.0a support?
Check out [Xeroizer](https://github.com/waynerobinson/xeroizer) gem built by Wayne Robinson and our community developers.
Check out the [Xeroizer](https://github.com/waynerobinson/xeroizer) gem (maintained by community)

---
## Installation
This SDK is published a gem on RubyGems.org as xero-ruby

Install on CLI from RubyGems.org:
This SDK is published as a gem on RubyGems as [xero-ruby](https://rubygems.org/gems/xero-ruby)

```gem install xero-ruby```

Include in Gemfile:
Include in Gemfile and run bundle install

```gem 'xero-ruby'```

Install from Git:

```gem 'xero-ruby', :git => 'https://github.com/XeroAPI/xero-ruby.git'```
## Getting Started
* Create a [free Xero user account](https://www.xero.com/us/signup/api/)
* Login to your Xero developer [/myapps](https://developer.xero.com/myapps) dashboard & create an API application

## Authorization & Callback
> Oauth2.0 auth flow is baked into this SDK. After a valid authentication a token_set will be returned which you should save and associate to the user who authorized it.
A token_set will look like the following give the scopes provided:
```json
{
"id_token" => "xxx.yyy.zz",
"access_token" => "xxx.yyy.zzz",
"expires_in" => 1800,
"token_type" => "Bearer",
"refresh_token"=> "xxxxxx",
"scope"=> "email profile openid accounting.transactions offline_access"
}

Or clone /Accounting and declare it as a local dependency:
```

```gem 'xero-ruby', :path => '../xeroapi-sdk-codegen/output/xero-ruby/accounting'```
So to return a valid token_set with this SDK from Xero:
```ruby
require 'xero-ruby'

To build the Ruby code into gem and install locally:
creds = {
client_id: ENV['CLIENT_ID'],
client_secret: ENV['CLIENT_SECRET'],
redirect_uri: ENV['REDIRECT_URI'],
scopes: ENV['SCOPES'] || "email profile openid accounting.transactions offline_access"
}

@xero_client = XeroRuby::ApiClient.new(credentials: creds)
@authorization_url = @xero_client.authorization_url
```
rake build
gem install ./pkg/xero-ruby-0.1.1.gem
Send the end user to the @authorization_url which will look like:
```json
https://login.xero.com/identity/connect/authorize?response_type=code&client_id=<xxx>&redirect_uri=<redirect_uri>&scope=<scopes>
```

## Getting Started

### Create a Xero App
Follow these steps to create your Xero app
```ruby
# /callback
token_set = @xero_client.get_token_set_from_callback(params)
token_set = @xero_client.token_set
...

* Create a [free Xero user account](https://www.xero.com/us/signup/api/) (if you don't have one)
* Login to [Xero developer center](https://developer.xero.com/myapps)
* Click "Try oAuth2" link
* Enter your App name, company url, privacy policy url.
* Enter the redirect URI (this is your callback url - localhost, etc)
* Agree to terms and condition and click "Create App".
* Click "Generate a secret" button.
* Copy your client id and client secret and save for use later.
* Click the "Save" button. Your secret is now hidden.

### How to use the xero-ruby SDK
This is a barebones example showing how to create an account from Xero via this SDK
# make api calls
accounting_api = XeroRuby::AccountingApi.new(@xero_client)
@invoices = accounting_api.get_invoices(current_user.active_tenant_id).invoices
```

## Token & SDK Helpers

```ruby
# `refresh_token_set` -> access_token valid 30 minutes / refresh_token valid 60 days
@token_set = @xero_client.refresh_token_set(current_user.token_set)

# `connections` -> (createdDateUtc will show you the most recently authorized tenant)
connections = @xero_client.connections
[{
"id"=>"xxx-yyy-zzz",
"tenantId"=>"xxx-yyy-zzz",
"tenantType"=>"ORGANISATION",
"tenantName"=>"Demo Company (US)",
"createdDateUtc"=>"2019-11-01T20:08:03.0766400",
"updatedDateUtc"=>"2020-04-15T22:37:10.4943410"
}]

# `disconnect` -> (pass ['id'] not 'tenantId')
remaining_connections = @xero_client.disconnect(params[:connection_id])
```
# Load the gem
require 'xero-ruby'

# Setup authorization
XeroRuby.configure do |config|
# Configure OAuth2 access token for authorization: OAuth2
config.access_token = 'YOUR ACCESS TOKEN'
end
api_instance = XeroRuby::AccountingApi.new
xero_tenant_id = 'xero_tenant_id_example' # String | Xero identifier for Tenant
account = { "Code":"123456", "Name":"Foobar", "Type":"EXPENSE", "Description":"Hello World" } # Account | Request of type Account
begin
#Allows you to create a new chart of accounts
result = api_instance.create_account(xero_tenant_id, account)
p result
rescue XeroRuby::ApiError => e
puts "Exception when calling AccountingApi->create_account: #{e}"
end
## API Usage
The `get_token_set_from_callback` method will set the `token_set` on the client, however you can also initialize an empty client and set the `token_set` explicitely using `set_token_set`.
> Useful for developers who don't need a full user login interface and already have a valid token set from something like our [CLI tool](https://github.com/XeroAPI/xoauth).
```ruby
xero_client ||= XeroRuby::ApiClient.new()

xero_client.set_token_set(current_user.token_set)

accounting_api = XeroRuby::AccountingApi.new(xero_client)

@invoices = accounting_api.get_invoices(current_user.active_tenant_id).invoices
@accounts = accounting_api.get_accounts(current_user.active_tenant_id).accounts
@contacts = accounting_api.get_contacts(current_user.active_tenant_id).contacts

# For full functionality reference https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/accounting_api.rb
```

### More details on how to use interact with each endpiont
Check out [full documentation](https://github.com/XeroAPI/xero-ruby/tree/master/accounting) under /accounting.
If you have use cases outside of these examples, please let us know!

## Sample App
* https://github.com/XeroAPI/xero-ruby-oauth2-app

The best resource to understanding how to best leverage this SDK is to clone down our Sample Rails application which showcases all the features of this project. The sample app can help you quickly understand how to:
* Complete the OAuth2.0 Authorization flow
* Store token_sets against a user object
* Store info about active connections
* Change the active tenant & make api calls to multiple orgs
* Refresh your token sets
* how to decode your token_set and strategy around how/when to refresh
* How to Disconnect from an org

---

## Contribution is welcome!
We love to get your input on how we can improve the SDK! Please read our [Contribuion Guide](https://github.com/XeroAPI/xero-ruby/CONTRIBUTING.md) before making an pull request!
### Other Documentation
We are working on a more consumable way to serve docs for this project. There is a /docs directory & other helpful [Documentation](https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/accounting_api.rb) can be found in each API's client file. Feedback welcome.

## TLS 1.0 deprecation
As of June 30, 2018, Xero's API will remove support for TLS 1.0.
## Contribution & Requests
Xero's supported SDK's are mostly auto-generated based on an [OpenAPISpec](https://github.com/XeroAPI/Xero-OpenAPI) that utilizes [openapi-generator](https://github.com/OpenAPITools/openapi-generator). Read about our SDK development: https://devblog.xero.com/building-sdks-for-the-future-b79ff726dfd6

The easiest way to force TLS 1.2 is to set the Runtime Environment for your server (Tomcat, etc) to Java 1.8 which defaults to TLS 1.2.
Please read our [Contribuion Guide](https://github.com/XeroAPI/xero-ruby/CONTRIBUTING.md) before making a pull request!

## License

Expand Down
2 changes: 1 addition & 1 deletion accounting/.openapi-generator/VERSION
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
4.2.0
4.3.0
2 changes: 1 addition & 1 deletion accounting/.travis.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ script:
- bundle install --path vendor/bundle
- bundle exec rspec
- gem build xero-ruby.gemspec
- gem install ./xero-ruby-0.2.4.gem
- gem install ./xero-ruby-0.4.0.gem
11 changes: 6 additions & 5 deletions accounting/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ No description provided (generated by Openapi Generator https://github.com/opena

This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:

- API version: 2.0.7
- Package version: 0.2.4
- API version: 2.0.9
- Package version: 0.4.0
- Build package: org.openapitools.codegen.languages.RubyClientCodegen
For more information, please visit [https://developer.xero.com](https://developer.xero.com)

Expand All @@ -24,16 +24,16 @@ gem build xero-ruby.gemspec
Then either install the gem locally:

```shell
gem install ./xero-ruby-0.2.4.gem
gem install ./xero-ruby-0.4.0.gem
```

(for development, run `gem install --dev ./xero-ruby-0.2.4.gem` to install the development dependencies)
(for development, run `gem install --dev ./xero-ruby-0.4.0.gem` to install the development dependencies)

or publish the gem to a gem hosting service, e.g. [RubyGems](https://rubygems.org/).

Finally add this to the Gemfile:

gem 'xero-ruby', '~> 0.2.4'
gem 'xero-ruby', '~> 0.4.0'

### Install from Git

Expand Down Expand Up @@ -223,6 +223,7 @@ Class | Method | HTTP request | Description
*XeroRuby::AccountingApi* | [**get_prepayment_history**](docs/AccountingApi.md#get_prepayment_history) | **GET** /Prepayments/{PrepaymentID}/History | Allows you to retrieve a history records of an Prepayment
*XeroRuby::AccountingApi* | [**get_prepayments**](docs/AccountingApi.md#get_prepayments) | **GET** /Prepayments | Allows you to retrieve prepayments
*XeroRuby::AccountingApi* | [**get_purchase_order**](docs/AccountingApi.md#get_purchase_order) | **GET** /PurchaseOrders/{PurchaseOrderID} | Allows you to retrieve a specified purchase orders
*XeroRuby::AccountingApi* | [**get_purchase_order_as_pdf**](docs/AccountingApi.md#get_purchase_order_as_pdf) | **GET** /PurchaseOrders/{PurchaseOrderID}/pdf | Allows you to retrieve purchase orders as PDF files
*XeroRuby::AccountingApi* | [**get_purchase_order_by_number**](docs/AccountingApi.md#get_purchase_order_by_number) | **GET** /PurchaseOrders/{PurchaseOrderNumber} | Allows you to retrieve a specified purchase orders
*XeroRuby::AccountingApi* | [**get_purchase_order_history**](docs/AccountingApi.md#get_purchase_order_history) | **GET** /PurchaseOrders/{PurchaseOrderID}/History | Allows you to retrieve history for PurchaseOrder
*XeroRuby::AccountingApi* | [**get_purchase_orders**](docs/AccountingApi.md#get_purchase_orders) | **GET** /PurchaseOrders | Allows you to retrieve purchase orders
Expand Down
53 changes: 53 additions & 0 deletions accounting/docs/AccountingApi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ Method | HTTP request | Description
[**get_prepayment_history**](AccountingApi.md#get_prepayment_history) | **GET** /Prepayments/{PrepaymentID}/History | Allows you to retrieve a history records of an Prepayment
[**get_prepayments**](AccountingApi.md#get_prepayments) | **GET** /Prepayments | Allows you to retrieve prepayments
[**get_purchase_order**](AccountingApi.md#get_purchase_order) | **GET** /PurchaseOrders/{PurchaseOrderID} | Allows you to retrieve a specified purchase orders
[**get_purchase_order_as_pdf**](AccountingApi.md#get_purchase_order_as_pdf) | **GET** /PurchaseOrders/{PurchaseOrderID}/pdf | Allows you to retrieve purchase orders as PDF files
[**get_purchase_order_by_number**](AccountingApi.md#get_purchase_order_by_number) | **GET** /PurchaseOrders/{PurchaseOrderNumber} | Allows you to retrieve a specified purchase orders
[**get_purchase_order_history**](AccountingApi.md#get_purchase_order_history) | **GET** /PurchaseOrders/{PurchaseOrderID}/History | Allows you to retrieve history for PurchaseOrder
[**get_purchase_orders**](AccountingApi.md#get_purchase_orders) | **GET** /PurchaseOrders | Allows you to retrieve purchase orders
Expand Down Expand Up @@ -7861,6 +7862,58 @@ Name | Type | Description | Notes
- **Accept**: application/json


## get_purchase_order_as_pdf

> File get_purchase_order_as_pdf(xero_tenant_id, purchase_order_id)
Allows you to retrieve purchase orders as PDF files

### Example

```ruby
# load the gem
require 'xero-ruby'
# setup authorization
XeroRuby.configure do |config|
# Configure OAuth2 access token for authorization: OAuth2
config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = XeroRuby::AccountingApi.new
xero_tenant_id = 'YOUR_XERO_TENANT_ID' # String | Xero identifier for Tenant
purchase_order_id = '00000000-0000-0000-000-000000000000' # String | Unique identifier for an Purchase Order

begin
#Allows you to retrieve purchase orders as PDF files
result = api_instance.get_purchase_order_as_pdf(xero_tenant_id, purchase_order_id)
p result
rescue XeroRuby::ApiError => e
puts "Exception when calling AccountingApi->get_purchase_order_as_pdf: #{e}"
end
```

### Parameters


Name | Type | Description | Notes
------------- | ------------- | ------------- | -------------
**xero_tenant_id** | **String**| Xero identifier for Tenant |
**purchase_order_id** | [**String**](.md)| Unique identifier for an Purchase Order |

### Return type

**File**

### Authorization

[OAuth2](../README.md#OAuth2)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: application/pdf


## get_purchase_order_by_number

> PurchaseOrders get_purchase_order_by_number(xero_tenant_id, purchase_order_number)
Expand Down
4 changes: 2 additions & 2 deletions accounting/docs/Quote.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Name | Type | Description | Notes
**title** | **String** | Title text for the quote | [optional]
**summary** | **String** | Summary text for the quote | [optional]
**branding_theme_id** | **String** | See BrandingThemes | [optional]
**updated_date_utc** | **String** | Last modified date UTC format | [optional]
**updated_date_utc** | **DateTime** | Last modified date UTC format | [optional]
**line_amount_types** | [**QuoteLineAmountTypes**](QuoteLineAmountTypes.md) | | [optional]

## Code Sample
Expand Down Expand Up @@ -52,7 +52,7 @@ instance = XeroRuby::Quote.new(quote_id: null,
title: null,
summary: null,
branding_theme_id: null,
updated_date_utc: /Date(1573755038314)/,
updated_date_utc: null,
line_amount_types: null)
```

Expand Down
Loading

0 comments on commit a252806

Please sign in to comment.