README.md in onfido-0.3.0 vs README.md in onfido-0.4.0
- old
+ new
@@ -1,172 +1,153 @@
# Onfido
-A wrapper for Onfido's [API](https://onfido.com/documentation#introduction). You should always refer to the documentation for valid API calls.
+A thin wrapper for Onfido's API.
[](http://badge.fury.io/rb/onfido)
[](https://travis-ci.org/hvssle/onfido)
+This gem supports both `v1` and `v2` of the Onfido API. Refer to Onfido's [API documentation](https://onfido.com/documentation#introduction) for details of the expected requests and responses for both.
- [1]: https://gitter.im/hvssle/onfido
- [2]: https://badges.gitter.im/gitterHQ/developers.png
-
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'onfido'
```
-And then execute:
+## Configuration
- $ bundle
+There are 5 configuration options:
-Or install it yourself as:
+```ruby
+Onfido.configure do |config|
+ config.api_key = 'MY_API_KEY'
+ config.api_version = 'v2'
+ config.logger = Logger.new(STDOUT)
+ config.open_timeout = 30
+ config.read_timeout = 80
+end
+```
- $ gem install onfido
-
-
## Usage
-There are 4 configuration options for Onfido, including your `api_key`, timeout details and logging.
+You can make API calls by using an instance of the `API` class:
```ruby
- Onfido.configure do |config|
- config.api_key = 'MY_API_KEY'
- config.logger = Logger.new(STDOUT)
- config.open_timeout = 30
- config.read_timeout = 80
- end
+api = Onfido::API.new
```
-Assuming you have a valid key, you can conveniently make API calls by using an instance of the `API` class.
+### Resources
-```ruby
- api = Onfido::API.new
-```
+All resources share the same interface when making API calls. Use `.create` to create a resource, `.find` to find one, and `.all` to fetch all resources.
-### Making calls to Onfido's resources
-
-All resources share the same interface when making API calls. For creating a resource you can use `.create`, for finding one `.find` and for fetching all records for a resource `.all`.
-
**Note:** *All param keys should be a symbol e.g. `{ type: 'express', reports: [{ name: 'identity' }] }`*
+#### Applicants
-### Applicant
+Applicants are the object upon which Onfido checks are performed.
-To create an applicant, you can simply use
-
```ruby
- api.applicant.create(params)
+api.applicant.create(params) # => Creates an applicant
+api.applicant.find('applicant_id') # => Finds a single applicant
+api.applicant.all # => Returns all applicants
```
-To find an existing applicant
+#### Documents
-```ruby
- api.applicant.find('applicant_id')
-```
+Documents provide supporting evidence for Onfido checks. They can only be
+created - the Onfido does not support finding or listing them.
-To get all applicants
-
```ruby
- api.applicant.all
+api.document.create('applicant_id', file: 'http://example.com', type: 'passport')
```
-### Document
+**Note:** The file parameter can be either a `File` object or a link to an image.
-To upload a document for an applicant, you can simply use
+#### Live Photos
+Live Photos, like documents, can provide supporting evidence for Onfido checks.
+They can only be created - the Onfido does not support finding or listing them.
+
```ruby
- api.document.create('applicant_id', file: 'http://example.com', type: 'passport')
+api.live_photo.create('applicant_id', file: 'http://example.com')
```
-The file can both be a `File` object or a link to an image.
+**Note:** The file parameter can be either a `File` object or a link to an image.
-### Check
+#### Checks
-To create a check for an applicant, you can simply use
+Checks are requests for Onfido to check an applicant, by commissioning one or
+more "reports" on them.
```ruby
- api.check.create('applicant_id', type: 'express', reports: [{ name: 'identity' }])
+api.check.create('applicant_id', type: 'express', reports: [{ name: 'identity' }])
+api.check.find('applicant_id', 'check_id')
+api.check.all('applicant_id')
```
-To find an existing check for an applicant
+#### Reports
-```ruby
- api.check.find('applicant_id', 'check_id')
-```
+Reports provide details of the results of some part of a "check". They are
+created when a check is created, so the Onfido API only provides support for
+finding and listing them.
-To get all checks for an applicant
-
```ruby
- api.check.all('applicant_id')
+api.report.find('check_id', 'report_id')
+api.report.all('check_id')
```
-### Report
+#### Address Lookups
-To find an existing report for a check
+Onfido provides an address lookup service, to help ensure well-formatted
+addresses are provided when creating "applicants". To search for addresses
+by postcode, use:
```ruby
- api.report.find('check_id', 'report_id')
+api.address.all('SE1 4NG')
```
-To get all reports for a check
+#### Webhook Endpoints
-```ruby
- api.report.all('check_id')
-```
+Onfido allows you to set up and view your webhook endpoints via the API, as well
+as through the dashboard.
-### Address Picker
-
-To search for addresses by postcode
-
```ruby
- api.address.all('SE1 4NG')
+api.webhook.create(params) # => Creates a webhook endpoint
+api.webhook.find('webhook_id') # => Finds a single webhook endpoint
+api.webhook.all # => Returns all webhook endpoints
```
### Pagination
-Currently, you can paginate over the *applicant* and *check* resources. However, since you can only create 1 check per applicant therefore paginating on the check resource might prove impractical.
+All resources that support an `all` method also support pagination. By default,
+the first 20 records are fetched.
-By default, both endpoints are fetching records the first 20 records. That is the maximum amount of records you can request per page.
+### Error Handling
-To paginate over *applicants*:
-```ruby
-api = Onfido::API.new
-api.applicant.all(page: 2, per_page: 10)
-```
-
-To paginate over *checks*:
-```
-api = Onfido::API.new
-api.check.all('applicant_id', page: 2, per_page: 10)
-```
-
-## Error Handling
-
-There are three classes of errors raised by the library, all of which subclass `Onfido::Error`.
+There are three classes of errors raised by the library, all of which subclass `Onfido::Error`:
- `Onfido::ServerError` is raised whenever Onfido returns a `5xx` response
- `Onfido::RequestError` is raised whenever Onfido returns any other kind of error
- `Onfido::ConnectionError` is raised whenever a network error occurs (e.g., a timeout)
All three error classes provide the `response_code`, `response_body`, `json_body`, `type` and `fields` of the error (although for `Onfido::ServerError` and `Onfido::ConnectionError` the last three are likely to be `nil`).
```ruby
- def create_applicant
- api.applicant.create(params)
- rescue Onfido::RequestError => e
- e.type # => 'validation_error'
- e.fields # => { "email": { "messages": ["invalid format"] } }
- e.response_code # => '422'
- end
+def create_applicant
+ api.applicant.create(params)
+rescue Onfido::RequestError => e
+ e.type # => 'validation_error'
+ e.fields # => { "email": { "messages": ["invalid format"] } }
+ e.response_code # => '422'
+end
```
-### Roadmap
+## Roadmap
- Improve test coverage with more scenarios
-- Add custom errors based on the response code.
-- Improve documentation
+- Add custom errors based on the response code
+- Improve pagination handling (use information passed in link header)
## Contributing
1. Fork it ( https://github.com/hvssle/onfido/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)