Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stas/http-rest_client

A simple HTTP API Client built on top of http.rb gem
https://github.com/stas/http-rest_client

Last synced: 16 days ago
JSON representation

A simple HTTP API Client built on top of http.rb gem

Awesome Lists containing this project

README 

        
# HTTP Rest Client



A simple HTTP API Client built on top of

[http.rb](https://github.com/httprb/http). The interface was borrowed from Nestful.



## About



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)



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'http-rest_client'

```



And then execute:



```ruby

$ bundle

```



Or install it yourself as:



```ruby

$ gem install http-rest_client

```



## Usage



This library provides composable modules/mixins to allow you build flexible

interfaces/wrappers for RESTful APIs.



### DSL



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



### CRUD



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



#### Resource definition



Let's take the example below as an API resource we want to work with:

```ruby

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:



```ruby

> res_one = MyResource.create(attr: :attr_value)

> res_one.json

=> {"attr"=>"attr_value"}

> res_one['method']

=> "POST"

```



## Development



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](https://rubygems.org).



## Contributing



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](http://contributor-covenant.org) code of

conduct.



## License



The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).



## Code of Conduct



Everyone interacting with this project codebase, issue

tracker, chat rooms and mailing list is expected to follow the [code of

conduct](https://github.com/[USERNAME]/active_record_pgcrypto/blob/master/CODE_OF_CONDUCT.md).