marvel_api

Build Status Coverage Status

Ruby bindings for the Marvel API. In active development. Feel free to contribute! Need Ruby 1.9.2 support or don't like Faraday? Check out the marvelite gem for an alternative. (-:

Installation

gem install 'marvel_api' or add gem 'marvel_api' to your Gemfile and bundle.

Configuration

You'll need an API key — get yours here. Configure like so:

@client = Marvel::Client.new

@client.configure do |config|
  config.api_key = 'YOUR_API_KEY'
  config.private_key = 'YOUR_PRIVATE_KEY'
end

Usage

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. Each method described below links to the associated call in Marvel's interactive API tester.

Characters

@client.characters
@client.characters(name: 'Thanos')
@client.characters(nameStartsWith: 'Th', orderBy: 'modified')

@client.character(1009652)

@client.character_comics(1009652)
@client.character_comics(1009652, titleStartsWith: 'Infinity', hasDigitalIssue: true)

@client.character_events(1009652)
@client.character_events(1009652, name: 'Infinity Gauntlet')

@client.character_series(1009652)
@client.character_series(1009652, contains: 'hardcover')

@client.character_stories(1009652)
@client.character_stories(1009652, limit: 50)

Comics

@client.comics
@client.comics(title: 'Daredevil')
@client.comics(startYear: 1950, issueNumber: 1)

@client.comic(29380)

@client.comic_characters(34249)
@client.comic_characters(34249, orderBy: 'name')

@client.comic_creators(34249)
@client.comic_creators(34249, lastNameStartsWith: 'V')

@client.comic_events(27272)
@client.comic_events(27272, orderBy: '-startDate')

@client.comic_stories(27272)
@client.comic_stories(27272, creators: [600, 801])

Creators

@client.creators
@client.creators(firstName: 'Frank', lastName: 'Miller')
@client.creators(lastNameStartsWith: 'Mo', limit: 20, offset: 20)

@client.creator(15)

@client.creator_comics(15)
@client.creator_comics(15, format: 'trade paperback')

@client.creator_events(30)
@client.creator_events(30, nameStartsWith: 'Civil')

@client.creator_series(30)
@client.creator_series(30, seriesType: 'limited')

@client.creator_stories(30)
@client.creator_stories(30, limit: 40, offset: 7750)

Events

@client.events
@client.events(name: 'Infinity Gauntlet')
@client.events(characters: [1009156, 1009652])

@client.event(227)

@client.event_characters(227)
@client.event_characters(227, modifiedSince: '2014-04-29')

@client.event_comics(227)
@client.event_comics(227, hasDigitalIssue: true, orderBy: 'onsaleDate')

@client.event_creators(227)
@@client.event_creators(227, lastNameStartsWith: 'Lar')

@client.event_series(227)
@client.event_series(227, startYear: 1995, seriesType: 'limited')

@client.event_stories(227)
@client.event_stories(227, orderBy: 'id', limit: 30, offset: 20)

Series

@client.series
@client.series(title: 'Uncanny X-Men')
@client.series(titleStartsWith: 'Astonishing', orderBy: 'startDate', limit: 100)

@client.serie(354)

@client.series_characters(354)
@client.series_characters(354, nameStartsWith: 'Iron')

@client.series_comics(354)
@client.series_comics(354, issueNumber: 1)

@client.series_creators(354)
@client.series_creators(354, lastName: 'Kirby')

@client.series_events(354)
@client.series_events(354, orderBy: 'startDate')

@client.series_stories(354)
@client.series_stories(354, modifiedSince: '2013-06-01')

Stories

@client.stories
@client.stories(creators: 15)
@client.stories(characters: [1009156, 1009652], orderBy: '-modified')

@client.story(6320)

@client.story_characters(14410)
@client.story_characters(14410, nameStartsWith: 'D')

@client.story_comics(126)
@client.story_comics(126, format: 'trade paperback')

@client.story_creators(126)
@client.story_creators(126, lastNameStartsWith: 'S')

@client.story_events(12964)
@client.story_events(12964, orderBy: 'name')

@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. 

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.
  • Fork the project.
  • Start a feature/bugfix branch.
  • Commit and push until you are happy with your contribution.
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright (c) 2014 Rahul Horé. See LICENSE.txt for further details.