README.md in marvel_api-0.2.0 vs README.md in marvel_api-0.2.1
- old
+ new
@@ -1,12 +1,14 @@
# marvel_api
+[](https://travis-ci.org/O-I/marvel)
+[](https://coveralls.io/r/O-I/marvel)
-Ruby bindings for the [Marvel API](http://developer.marvel.com/). Still under construction... Feel free to contribute! In the meantime, check out the [marvelite](https://github.com/antillas21/marvelite/) gem for something that's further along in development (and likely a lot stabler :-).
+Ruby bindings for the [Marvel API](http://developer.marvel.com/). In active development. Feel free to contribute! Need Ruby 1.9.2 support or don't like Faraday? Check out the [marvelite](https://github.com/antillas21/marvelite/) gem for an alternative. (-:
## Installation
-`gem install 'marvel_api'` or add `gem 'marvel_api'` to your Gemfile.
+`gem install 'marvel_api'` or add `gem 'marvel_api'` to your Gemfile and `bundle`.
## Configuration
You'll need an API key — get yours [here](http://developer.marvel.com). Configure like so:
@@ -19,11 +21,11 @@
end
```
## Usage
-Descriptions and examples of the supported actions are below. Note, all methods currently return a `Hashie:Mash` object if successful. For a more detailed explanation of available actions and an exhaustive list of acceptable query parameters, see Marvel's own developer [documentation](http://developer.marvel.com/docs). Each method described below links to the associated call in Marvel's interactive API tester.
+Descriptions and examples of the supported actions are below. Note, all methods currently return an `Array` of `Hashie::Mash` objects if successful; otherwise, a `Marvel::Response::Error` is returned. For a more detailed explanation of available actions and an exhaustive list of acceptable query parameters, see Marvel's own developer [documentation](http://developer.marvel.com/docs). Each method described below links to the associated call in Marvel's interactive API tester.
### Characters
- Fetches lists of characters. [`GET /v1/public/characters`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_0)
@@ -117,11 +119,10 @@
```ruby
@client.creators
@client.creators(firstName: 'Frank', lastName: 'Miller')
@client.creators(lastNameStartsWith: 'Mo', limit: 20, offset: 20)
-
```
- Fetches a single creator by id. [`GET /v1/public/creators/{creatorId}`](http://developer.marvel.com/docs#!/public/getCreatorIndividual_get_13)
```ruby
@@ -306,9 +307,20 @@
```ruby
@client.story_series(126)
@client.story_series(126, titleStartsWith: 'Infinity')
```
+
+### Etags
+
+Most successful responses contain an `etag` attribute that can be used to check whether the content of the requested resource has remained the same since the last request.
+
+```ruby
+thanos = @client.character(1009652)
+@client.character(1009652, etag: thanos.etag)
+```
+
+If the content has not changed, a `Marvel::Response::Error` with `code` 304 and `status` 'Not Modified' is returned and you can use your cached content knowing that it is up-to-date and that you saved some bandwidth. If the content has changed or the Etag is invalid, the resource you requested will be returned.
## Contributing to marvel_api
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
\ No newline at end of file