Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: bfde29a94a
Fetching contributors…

Cannot retrieve contributors at this time

83 lines (55 sloc) 3.01 kb


Parameter Contracts for Sinatra

REST conventions takes the guesswork out of designing and consuming web APIs. GET / POST / PATCH / DELETE resource endpoints and you get what you'd expect.

But figuring out what parameters are expected... well, all bets are off. This Sinatra extension takes a first step to solving this problem on the developer side

sinatra-param allows you to declare, validate, and transform endpoint parameters as you would in frameworks like DataMapper or ActiveModel.


require 'sinatra/param'
class App < Sinatra::Base
  helpers Sinatra::Param

  before do
    content_type :json

  # GET /search?q=example
  # GET /search?q=example&categories=news
  # GET /search?q=example&sort=created_at&order=ASC
  get '/search' do
    param :q,           String, required: true
    param :categories,  Array
    param :sort,        String, default: "title"
    param :order,       String, in: ["ASC", "DESC"], transform: :upcase, default: "ASC"


Parameter Types

By declaring parameter types, incoming parameters will automatically be transformed into an object of that type. For instance, if a param is Boolean, values of '1', 'true', 't', 'yes', and 'y' will be automatically transformed into true.

  • String
  • Integer
  • Float
  • Boolean ("1/0", "true/false", "t/f", "yes/no", "y/n")
  • Array ("1,2,3,4,5")
  • Hash (key1:value1,key2:value2)


Encapsulate business logic in a consistent way with validations. If a parameter does not satisfy a particular condition, a 406 error is returned with a message explaining the failure.

  • required
  • blank
  • is
  • in, within, range
  • min / max

Defaults and Transformations

Passing a default option will provide a default value for a parameter if none is passed.

Use the transform option to take even more of the business logic of parameter I/O out of your code. Anything that responds to to_proc (including Procs and symbols) will do.

Next Steps

  • Design by contract like this is great for developers, and with a little meta-programming, it could probably be exposed to users as well. The self-documenting dream of Hypermedia folks could well be within reach.

  • Another pain point is the awkward way parameters are passed as JSON in HTTP bodies. I'd love to see an elegant, unobtrusive way to do this automatically.

  • Support for Rails-style Arrays ('key[]=value1&key[]=value2') and Hashes ('key[a]=value1&key[b]=value2). /via @manton

  • Testing. This will happen soon.


Mattt Thompson


sinatra-param is available under the MIT license. See the LICENSE file for more info.

Jump to Line
Something went wrong with that request. Please try again.