HTTP Rest Client

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 URI
• path('/resource') - defines the API path of the resource
• content_type('application/json') - sets up the content type of the request
• accept('application/json') - sets up the response media type
• basic_auth(user: 'username', pass: 'password') - sets up the basic authentication user and password
• auth('AUTH_TOKEN') - sets up the authentication token
• request('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 resources
• find(id, params) - returns the available resource based on the id
• create(params) - creates and returns the new resource using the passed data
• update(id, params) - updates and returns the resource using the passed data
• delete(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.