Skip to content
Human-friendly DSL for writing HTTP(s) clients in Ruby
Branch: master
Clone or download
nepalez Bump v3.0.3
Support dry-initializer v3+
Latest commit e0e0813 May 6, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Allow to pass response handling to parent scopes Dec 13, 2017
lib Bump v3.0.3 May 6, 2019
spec Bump v3.0.3 May 6, 2019
.codeclimate.yml Fix linter settings Aug 6, 2017
.rspec Prepare v1.0.0 Jul 31, 2017
.rubocop.yml Bump v3.0.3 May 6, 2019
.travis.yml Bump v3.0.3 May 6, 2019 Bump v3.0.3 May 6, 2019
Gemfile Drop dependency from dry-memoizer Aug 6, 2017
LICENSE.txt Prepare v1.0.0 Jul 31, 2017 Bump v3.0.3 May 6, 2019
Rakefile Rewrite the gem from scratch Oct 27, 2016
evil-client.gemspec Bump v3.0.3 May 6, 2019
mkdocs.yml Fix mkdocs.yml Aug 10, 2017


Human-friendly DSL for writing HTTP(s) clients in Ruby

Sponsored by Evil Martians

Gem Version Build Status Code Climate Inline docs Documentation Status


The gem allows writing http(s) clients in a way inspired by Swagger specifications. It stands away from mutable states and monkey patching when possible. To support multithreading all instances are immutable (though not frozen to avoid performance loss).


Add this line to your application's Gemfile:

gem 'evil-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install evil-client


The following example gives an idea of how a client to remote API looks like when written on top of Evil::Client. See full documentation for more details.

require "evil-client"

class CatsClient < Evil::Client
  # Define options for the client's initializer
  option :domain,   proc(&:to_s)
  option :user,     proc(&:to_s)
  option :password, proc(&:to_s)

  # Definitions shared by all operations
  path     { "https://#{domain}" }
  security { basic_auth settings.user, settings.password }

  scope :cats do
    # Scope-specific definitions
    option :version,  default: proc { 1 }
    path { "v#{version}" } # subpath added to root path

    # Operation-specific definitions to update a cat by id
    operation :update do
      option :id,    proc(&:to_i)
      option :name,  optional: true
      option :color, optional: true
      option :age,   optional: true

      let(:data) { { |key, _| %i(name color age).include? key } }
      validate   { errors.add :no_filters if data.empty? }

      path        { "cats/#{id}" } # added to root path
      http_method :patch # you can use plain syntax instead of a block
      format      "json"
      body        { options.except(:id, :version) } # [#slice] is available too

      # Parses json response and wraps it into Cat instance with additional
      # parameter
      response 200 do |(status, headers, body)|
        # Suppose you define a model for cats JSON.parse(body)

      # Parses json response, wraps it into model with [#error] and raises
      # an exception where [ResponseError#response] contains the model istance
      response(400, 422) { |(status, *)| raise "#{status}: Record invalid" }

# Instantiate a client with a concrete settings
cat_client = domain:   "awesome-cats",
                           user:     "cat_lover",
                           password: "purr"

# Use verbose low-level DSL to send requests
cat_client.scopes[:cats].new(version: 2)
          .operations[:update].new(id: 4, age: 10, color: "tabby")
          .call # sends request

# Use top-level DSL for the same request
cat_client.cats(version: 2).update(id: 4, age: 10, color: "tabby")

# Both the methods send `PATCH`
# with a specified body and headers (authorization via basic_auth)


The gem is available as open source under the terms of the MIT License.

You can’t perform that action at this time.