Use helpers body and format to define content of http message, and how it should be formatted.

We support several formats, namely: :json (default), :text, :form, :yaml, and :multipart.

Plain Formats

With default :json format, the body should be a hash:

class CatsAPI < Evil::Client
  format { :json }
  # ...
  scope :cats do
    # ...
    operation :create do
      option :species
      option :name

      body { { species: species, name: name } }
    end
  end
end

Before sending to the stack of middleware, it will be dumped:

CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
# sends a request with a body: '{"species":"Acinonyx jubatus","name":"Cheetah"}'
# and a header "Content-Type": "application/json"

The same content, but formatted as :yaml will send another body and header:

class CatsAPI < Evil::Client
  format { :yaml }
end

CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
# sends a request with a body: "---\n:species: Acinonyx jubatus\n:name: Cheetah\n'
# and a header "Content-Type": "application/yaml"

The :form format will make body url encoded:

class CatsAPI < Evil::Client
  format { :form }
end

CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
# sends a request with a body: "species=Acinonyx jubatus&name=Cheetah"
# and a header "Content-Type": "application/x-www-form-urlencoded"

The :text just stringifies it as is:

class CatsAPI < Evil::Client
  format { :text }
end

CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
# sends a request with a body: '{:species=>"Acionyx jubatus",:name=>"Cheetah"}'
# and a header "Content-Type": "text/plain"

This format doesn't require the body to be hash. It can be anything.

Multipart Formats

When you need sending files you should select the :multipart format. This time the whole body is formatted as form/multipart. Depending on its type (hash, file, StringIO), the content will be formatted correspondingly. Arrays are treated as several parts of the body. All other objects will be stringified.

class CatsAPI < Evil::Client
  # ...
  scope :cats do
    # ...
    operation :upload do
      option :files, method(:Array)

      format { :multipart }
      body   { files }
    end
  end
end

CatsAPI.cats.upload files: [StringIO.new("Cheetah"), StrinIO.new("Lion")]