A simple HTTP API Client built on top of http.rb. The interface was borrowed from Nestful.
The library represents a thin wrapper (~100 lines of code) over the wonderful
http.rb
gem, allowing you to define and interact with a RESTful API in an
Active Record style using plain old Ruby objects.
Main goals:
- No magic please
- Clean and minimal DSL
- Less code, less maintenance
- Good docs and test coverage
- Keep it up-to-date (or at least tell people this is no longer maintained)
This library exists because similar projects are either:
- no longer maintained
- implement features which
http.rb
offers and thus have a higher complexity - have other very specific features (like relationships, xml or other flavour response types support)
Add this line to your application's Gemfile:
gem 'http-rest_client'
And then execute:
$ bundle
Or install it yourself as:
$ gem install http-rest_client
This library provides composable modules/mixins to allow you build flexible interfaces/wrappers for RESTful APIs.
The HTTP::RestClient::DSL
mixin provides a couple of helpers to define
the API endpoint, path and content type. It also takes care of the error
handling and the parsing of the responses.
The following class methods are provided by this mixin:
endpoint('http://api.tld')
- sets up the API URIpath('/resource')
- defines the API path of the resourcecontent_type('application/json')
- sets up the content type of the requestaccept('application/json')
- sets up the response media typebasic_auth(user: 'username', pass: 'password')
- sets up the basic authentication user and passwordauth('AUTH_TOKEN')
- sets up the authentication tokenrequest('get', uri, options)
- creates a request and handles the response
The HTTP::RestClient::CRUD
mixin provides the create-read-update-delete helpers
to help you define Active Record style classes representing the API resources.
The following class methods are provided by this mixin:
all(params)
- returns all available resourcesfind(id, params)
- returns the available resource based on theid
create(params)
- creates and returns the new resource using the passed dataupdate(id, params)
- updates and returns the resource using the passed datadelete(id)
- removes the resource
Let's take the example below as an API resource we want to work with:
require 'ostruct'
class MyResource < OpenStruct
extend HTTP::RestClient::DSL
extend HTTP::RestClient::CRUD
endpoint 'https://httpbin.org'
path 'anything'
content_type 'application/json'
accept 'application/json'
basic_auth user: 'user1', pass: 'pass1'
# Alternatively, define the token based authentication
# auth('MY_API_TOKEN')
end
The class inherits the OpenStruct
interface which allows an easy way to have
dynamic class attributes. And for testing purposes, we will use the HTTPBin
web service to mock any responses.
Now we can operate on the new resource endpoint in a pragmatic way:
> res_one = MyResource.create(attr: :attr_value)
> res_one.json
=> {"attr"=>"attr_value"}
> res_one['method']
=> "POST"
After checking out the repo, run bundle
to install dependencies.
Then, run rake
to run the tests.
To install this gem onto your local machine, run bundle exec rake install
.
To release a new version, update the version number in version.rb
, and then
run bundle exec rake release
, which will create a git tag for the version,
push git commits and tags, and push the .gem
file to
rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/stas/http-rest_client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting with this project codebase, issue tracker, chat rooms and mailing list is expected to follow the code of conduct.