Gavel HTTP Validator specification and documentation
Pull request Compare This branch is 59 commits behind apiaryio:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Gavel—HTTP validator

Gavel logo

What is Gavel?

Gavel is a tool for deciding which HTTP API call is valid and which is not.

It's useful for:

  • Specification by example and BDD for HTTP (RESTful) APIs
  • Diff HTTP Requests and Responses
  • Testing API documentation
  • DRY test assertion engine for REST API's HTTP request and response
  • API client (SDK) validations


$ curl --trace - | curl-trace-parser  > expected
$ curl --trace - | curl-trace-parser  > real
$ cat real | gavel expected_message
$ echo $?

How does it work?

Gavel` filters out boring noise in API communication and helps you understand important differences between real and expected HTTP messages (HTTP request and response). You can use Gavel with examples for:

Brief behavior description

  • Headers can't miss
  • Header values metters
  • JSON keys in bodies can't miss
  • Textual body must match exactly

See detailed expectation behavior specification

Known implementations

Platform independent documentation and specification

Gavel is fair to everyone!

Gavel specification and documentation is written in Gherkin, laguage used by Cucumber, popular BDD tool and lives here on Relish.

Relish radically changed point of view on Cucumber from BDD tool to documentation-oriented acceptance testing platform for collaboration. Examples are made on raw HTTP, in order to focus on implementation independence. It means, thanks to Cucumber, each example in Gavel specification is tested against each Gavel implementation in continous integration. So Gavel's behavior documentation can never be outdated and Gavel's behavior is consistent across all languages.

Contribution to this specification

  1. Fork this repo
  2. Make change to existing features or add features
  3. Bump version (create tag)
  4. Open pull request

Use GitHub issues for discussion.

New language implementation (the BDD way)

  • Fork this repo
  • Assign implementation specific Cucumebr tag (e.g. @erlang) in this document
  • Add forked repo as git submodule to cucumber feature directory in your project
  • Setup your Cucumber-like test runner to use only this tag (-t option) to filter out other implementations
  • Tag features with your language tag as you implement
  • Implement Cucumber step definitions (glue code between Cucumber steps and your code)
  • Run Cucumber and see it failing
  • Implement scenario in your code
  • Run Cucumber and see examples passing (Make cukes green)
  • Do not forget to add Cucumber features for code exapmles for your implementation
  • Add your repository to Travis-CI and add badge in this document
  • Publish your repository

Cucumber tags

Untagged features and scenarios are considered mandatory in all imlpementations

General tags

@draft - feature sketch, aggregation thoughts @proposalt - proposal for stabilization

Implementation specific tags

@nodejs - Implemented in Node.js, tested

@nodejs-pending Planned to implement in Node.js, NOT tested