Evil::Client

Services & Skills

Share on

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).

The following example gives an idea of how a client to remote API looks like when written on top of Evil::Client.

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}.example.com/api" }
  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) { options.select { |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
        Cat.new JSON.parse(body)
      end

      # 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" }
    end
  end
end

# Instantiate a client with a concrete settings
cat_client = CatClient.new 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 https://awesome-cats.example.com/api/v2/cats/4`
# with a specified body and headers (authorization via basic_auth)
Author

Explore more OSS projects

Contact us

We’d love to hear from you! We’re not really all that evil, and we love discussing potential projects, intriguing ideas, and new opportunities. Complete the form below or drop us a line at surrender@evilmartians.com.

Martians at a glance
16
years in business

A product development consultancy that works with startups and established businesses, while also creating open source-based products and services