README.md
RSpec API
=========
RSpec API aims to make it easy to document and test [pragmatic RESTful web APIs](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api).
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](http://rspec-api.github.io)
[](https://travis-ci.org/rspec-api/rspec-api)
[](https://codeclimate.com/github/rspec-api/rspec-api)
[](https://coveralls.io/r/rspec-api/rspec-api)
[](https://gemnasium.com/rspec-api/rspec-api)
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](https://github.com/rspec-api/rspec-api/tree/master/spec/dummy))
* a *test suite* that verifies the expected behavior of the API (in [spec/features/local/](https://github.com/rspec-api/rspec-api/blob/master/spec/features/local/gigs/gigs_spec.rb))
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](https://github.com/rspec-api/rspec-api/blob/master/spec/features/remote).
The code verifies the expected behavior of a number of endpoints of the [GitHub API](http://developer.github.com):
* 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](https://github.com/settings/applications)
* 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 :)