mikevoets / flexirest

Flexirest - The really flexible REST API client for Ruby

Flexirest

Access your REST APIs in a flexible way.

Write your API classes in an ActiveRecord-style; like ActiveResource but Flexirest works where the resource naming doesn't follow Rails conventions, it has built-in caching and is much more flexible.

Background

If you are a previous user of ActiveRestClient, there's some more information on why I created this fork and how to upgrade - but long story short, I wrote most of the code as a previous gem for a client, they agreed to open-source it, then it was abandoned and I relaunched it and now support it myself (and the owners of ActiveRestClient have acknowledged their gem is deprecated in favour of Flexirest).

Quickstart

Assuming you're using Bundler, to use Flexirest add this line to your application's Gemfile:

gem 'flexirest'

And then execute:

$ bundle

To use it, let's create a new model class:

# app/models/person.rb
class Person < Flexirest::Base
  base_url "https://www.example.com/api/v1"

  get :all, "/people"
  get :find, "/people/:id"
  put :save, "/people/:id"
  post :create, "/people"
  delete :remove, "/people/:id"
end

You can then use your new class like this:

# Create a new person
@person = Person.create(
  first_name:"John"
  last_name:"Smith"
)

# Find a person (not needed after creating)
id = @person.id
@person = Person.find(id)

# Update a person
@person.last_name = "Jones"
@person.save

# Get all people
@people = Person.all
@people.each do |person|
  puts "Hi " + person.first_name
end

Reading further

I've written a TON of documentation on how to use Flexirest and a LITTLE bit on how it works internally. For more information see the following pages:

• Basic Usage
• Ruby on Rails integration
• Faraday configuration
• Associations
• Combined example
• Caching
• Using callbacks
• Lazy loading
• Authentication
• Body types
• Parallel requests
• Faking calls
• Per-request timeouts
• Per-request parameter encoding
• Automatic conversion of fields to Date/DateTime
• Raw requests
• Plain requests
• JSON API
• Proxying APIs
• Translating APIs - DEPRECATED
• Default parameters
• Root elements
• Required parameters
• Updating only changed/dirty attributes
• HTTP/parse error handling
• Validation
• Filtering result lists
• Debugging
• XML responses

Licence

Code originally copyright© 2013 Which? Ltd, released with an MIT License and now this fork is released under the same licence by Andy Jeffries.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

If you want to generate a reproducible bug report, here are some steps to follow in your bug report:

1. Clone the Flexirest repo (git clone https://github.com/flexirest/flexirest.git)
2. Change to the flexirest folder (cd flexirest)
3. Install any dependencies (bundle install)
4. Run an interactive console (rake c)
5. Paste the following:

class MyObject < Flexirest::Base
  base_url "https://requestb.in"
  post :create, "/{CREATE_A_PASTEBIN_ID}"
end

my_object = MyObject.new(params: "something")
my_object.create
# => something is output to the terminal

Working on the codebase

The general steps are the same as for almost all codebases on GitHub:

1. Fork it and clone your fork
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request on GitHub.com

We have a guide written about Flexirest Internals if you want to know how it all hangs together. We also have lots of RSpec specifications, tested with Travis CI.