README.md in rspec-api-0.2.0 vs README.md in rspec-api-0.4.0
- old
+ new
@@ -1,16 +1,102 @@
RSpec API
=========
-More info at [http://rspec-api.github.io](http://rspec-api.github.io)
+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).
-[](https://travis-ci.org/rspec-api/rspec-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)
-How to test
-===========
+A basic example
+---------------
-* Create a new [GitHub personal authentication token](https://github.com/settings/applications)
-* Store it in an environment variable called `RSPEC_API_GITHUB_TOKEN` (e.g., on OS X, type `export RSPEC_API_GITHUB_TOKEN=...`)
-* Run `rspec`
\ No newline at end of file
+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 :)
+