{"id":13493150,"url":"https://github.com/mattt/sinatra-param","last_synced_at":"2025-05-15T10:01:50.992Z","repository":{"id":3141289,"uuid":"4170384","full_name":"mattt/sinatra-param","owner":"mattt","description":"Parameter Validation \u0026 Type Coercion for Sinatra","archived":false,"fork":false,"pushed_at":"2022-03-09T15:15:16.000Z","size":130,"stargazers_count":518,"open_issues_count":18,"forks_count":71,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-14T16:53:38.042Z","etag":null,"topics":["coercion","parameters","ruby","sinatra","validation"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-04-28T21:20:53.000Z","updated_at":"2025-01-05T16:14:45.000Z","dependencies_parsed_at":"2022-08-20T11:40:29.006Z","dependency_job_id":null,"html_url":"https://github.com/mattt/sinatra-param","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattt%2Fsinatra-param","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattt%2Fsinatra-param/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattt%2Fsinatra-param/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattt%2Fsinatra-param/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattt","download_url":"https://codeload.github.com/mattt/sinatra-param/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319715,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coercion","parameters","ruby","sinatra","validation"],"created_at":"2024-07-31T19:01:12.723Z","updated_at":"2025-05-15T10:01:50.089Z","avatar_url":"https://github.com/mattt.png","language":"Ruby","readme":"# sinatra-param\n\n_Parameter Validation \u0026 Type Coercion for Sinatra_\n\nREST conventions take the guesswork out of designing and consuming web APIs. Simply `GET`, `POST`, `PATCH`, or `DELETE` resource endpoints, and you get what you'd expect.\n\nHowever, when it comes to figuring out what parameters are expected... well, all bets are off.\n\nThis Sinatra extension takes a first step to solving this problem on the developer side\n\n**`sinatra-param` allows you to declare, validate, and transform endpoint parameters as you would in frameworks like [ActiveModel](http://rubydoc.info/gems/activemodel/3.2.3/frames) or [DataMapper](http://datamapper.org/).**\n\n\u003e Use `sinatra-param` in combination with [`Rack::PostBodyContentTypeParser` and `Rack::NestedParams`](https://github.com/rack/rack-contrib) to automatically parameterize JSON `POST` bodies and nested parameters.\n\n## Install\n\nYou can install `sinatra-param` from the command line with the following:\n\n```bash\n$ gem install sinatra-param\n```\n\nAlternatively, you can specify `sinatra-param` as a dependency in your `Gemfile` and run `$ bundle install`:\n\n```ruby\ngem \"sinatra-param\", require: \"sinatra/param\"\n```\n\n## Example\n\n```ruby\nrequire 'sinatra/base'\nrequire 'sinatra/param'\nrequire 'json'\n\nclass App \u003c Sinatra::Base\n  helpers Sinatra::Param\n\n  before do\n    content_type :json\n  end\n\n  # GET /search?q=example\n  # GET /search?q=example\u0026categories=news\n  # GET /search?q=example\u0026sort=created_at\u0026order=ASC\n  get '/search' do\n    param :q,           String, required: true\n    param :categories,  Array\n    param :sort,        String, default: \"title\"\n    param :order,       String, in: [\"ASC\", \"DESC\"], transform: :upcase, default: \"ASC\"\n    param :price,       String, format: /[\u003c\\=\u003e]\\s*\\$\\d+/\n\n    one_of :q, :categories\n\n    {...}.to_json\n  end\nend\n```\n\n### Parameter Types\n\nBy 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`.\n\n* `String`\n* `Integer`\n* `Float`\n* `Boolean` _(\"1/0\", \"true/false\", \"t/f\", \"yes/no\", \"y/n\")_\n* `Array` _(\"1,2,3,4,5\")_\n* `Hash` _(key1:value1,key2:value2)_\n* `Date`, `Time`, \u0026 `DateTime`\n\n### Validations\n\nEncapsulate business logic in a consistent way with validations. If a parameter does not satisfy a particular condition, a `400` error is returned with a message explaining the failure.\n\n* `required`\n* `blank`\n* `is`\n* `in`, `within`, `range`\n* `min` / `max`\n* `min_length` / `max_length`\n* `format`\n\n### Custom Error Messages\n\nPassing a `message` option allows you to customize the message\nfor any validation error that occurs.\n\n```ruby\nparam :spelling,\n      format: /\\b(?![a-z]*cie)[a-z]*(?:cei|ie)[a-z]*/i,\n      message: \"'i' before 'e', except after 'c'\"\n```\n\n### Defaults and Transformations\n\nPassing a `default` option will provide a default value for a parameter if none is passed. A `default` can defined as either a default or as a `Proc`:\n\n```ruby\nparam :attribution, String, default: \"©\"\nparam :year, Integer, default: lambda { Time.now.year }\n```\n\nUse 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 `Proc` and symbols) will do.\n\n```ruby\nparam :order, String, in: [\"ASC\", \"DESC\"], transform: :upcase, default: \"ASC\"\nparam :offset, Integer, min: 0, transform: lambda {|n| n - (n % 10)}\n```\n\n## One Of\n\nUsing `one_of`, routes can specify two or more parameters to be mutually exclusive, and fail if _more than one_ of those parameters is provided:\n\n```ruby\nparam :a, String\nparam :b, String\nparam :c, String\n\none_of :a, :b, :c\n```\n\n## Any Of\n\nUsing `any_of`, a route can specify that _at least one of_ two or more parameters are required, and fail if _none of them_ are provided:\n\n```ruby\nparam :x, String\nparam :y, String\n\nany_of :x, :y\n```\n\n## All Or None Of\n\nUsing `all_or_none_of`, a router can specify that _all_ or _none_ of a set of parameters are required, and fail if _some_ are provided:\n\n```ruby\nparam :x, String\nparam :y, String\n\nall_or_none_of :x,:y\n```\n\n### Exceptions\n\nBy default, when a parameter precondition fails, `Sinatra::Param` will `halt 400` with an error message:\n\n```json\n{\n  \"message\": \"Parameter must be within [\\\"ASC\\\", \\\"DESC\\\"]\",\n  \"errors\": {\n    \"order\": \"Parameter must be within [\\\"ASC\\\", \\\"DESC\\\"]\"\n  }\n}\n```\n\nTo change this, you can set `:raise_sinatra_param_exceptions` to `true`, and intercept `Sinatra::Param::InvalidParameterError` with a Sinatra `error do...end` block. (To make this work in development, set `:show_exceptions` to `false` and `:raise_errors` to `true`):\n\n```ruby\nset :raise_sinatra_param_exceptions, true\n\nerror Sinatra::Param::InvalidParameterError do\n    { error: \"#{env['sinatra.error'].param} is invalid\" }.to_json\nend\n```\n\nCustom exception handling can also be enabled on an individual parameter basis, by passing the `raise` option:\n\n```ruby\nparam :order, String, in: [\"ASC\", \"DESC\"], raise: true\n\none_of :q, :categories, raise: true\n```\n\n## Contact\n\nMattt ([@mattt](http://twitter.com/mattt))\n\n## License\n\nsinatra-param is released under an MIT license. See LICENSE for more information.\n","funding_links":[],"categories":["Validation \u0026 Type Coercion"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattt%2Fsinatra-param","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattt%2Fsinatra-param","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattt%2Fsinatra-param/lists"}