When you write a web API, you make a promise to the world. RSpec API helps you keep your promise
Ruby Logos
Switch branches/tags
Clone or download
Pull request Compare This branch is 33 commits ahead of claudiob:master.
claudiob Support Ruby 1.9.2
The specs will still only run with Ruby >= 1.9.3 because of the
local specs written in Rails 4. However the gem can be used also
by projects stuck with Ruby 1.9.2.
Latest commit 26dd56b Nov 25, 2013
Permalink
Failed to load latest commit information.
lib
log
spec
.gitignore
.rspec
.travis.yml
Gemfile
Gemfile.lock
HISTORY.md
MIT-LICENSE
README.md
Rakefile
TODO.md
WHY.md
rspec-api.gemspec

README.md

RSpec API

RSpec API aims to make it easy to document and test pragmatic RESTful web APIs.

It is still under development, and you can follow its progress by checking out the code on Github.

More documentation and examples are available at http://rspec-api.github.io

Build Status Code Climate Coverage Status Dependency Status

A basic example

RSpec API can help develop and document your own web APIs. A basic example of running RSpec API locally is provided, comprised of:

  • a Ruby on Rails app that provides a RESTful API for concerts (in spec/dummy)
  • a test suite that verifies the expected behavior of the API (in spec/features/local/)

Run the basic example with the following commands:

git clone https://github.com/rspec-api/rspec-api.git
cd rspec-api
bundle
bundle exec rake db:migrate
bundle exec rspec spec/features/local

And you should see all the successful promises matched by the concerts API:

Concerts
  GET /concerts
    by default
      responds with a status code that
        should be 200
      responds with headers that
        should include 'Content-Type': 'application/json; charset=utf-8'
        should include 'Link' (for pagination)
  ...
  DELETE /concerts/:id
    given an existing id
      responds with a status code that
        should be 204

Finished in 0.73864 seconds
151 examples, 0 failures

The GitHub API example

RSpec API can help specify and verify promises for remote APIs. An example of running RSpec API for a remote API is provided in spec/features/remote. The code verifies the expected behavior of a number of endpoints of the GitHub API:

  • Activity resources (events, feeds, notifications, starring, watching)
  • Gists resources (gists, gist comments)
  • Git data resources (blobs, commits)
  • Repository resources (repos)

Before running the example, get a GitHub Personal Access Token:

  • Browse to your GitHub settings
  • Click on 'Create new token' under 'Personal Access Token' (name it as you want)
  • Copy the generated token and store it on your machine as the environment variable called RSPEC_API_GITHUB_TOKEN:
    • On OSX and bash, accomplish this by running the command export RSPEC_API_GITHUB_TOKEN= followed by your pasted key (no spaces after =)

Now, run the GitHub API example with the following commands:

git clone https://github.com/rspec-api/rspec-api.git
cd rspec-api
bundle
bundle exec rspec spec/features/remote

And you should see all the successful promises matched by the GitHub API:

Events
  GET https://api.github.com/events
    by default
      responds with a status code that
        should be 200
      responds with headers that
        should include 'Content-Type': 'application/json; charset=utf-8'
        should include 'Link' (for pagination)
  ...
  DELETE https://api.github.com/gists/:id/star
    given an existing id 0d7b597d822102148810
      responds with a status code that
        should be 204

Finished in 1 minute 19.74 seconds
1237 examples, 1 failure, 4 pending

How to contribute

Don’t hesitate to send me code comments, issues or pull requests through GitHub! All feedback is appreciated. Thanks :)