marvel_api

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

Fetches lists of characters. GET /v1/public/characters

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

Fetches a single character by id. GET /v1/public/characters/{characterId}

@client.character(1009652)

Fetches lists of comics filtered by a character id. GET /v1/public/characters/{characterId}/comics

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

Fetches lists of events filtered by a character id. GET /v1/public/characters/{characterId}/events

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

Fetches lists of series filtered by a character id. GET /v1/public/characters/{characterId}/series

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

Fetches lists of stories filtered by a character id. GET /v1/public/characters/{characterId}/stories

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

Comics

Fetches lists of comics. GET /v1/public/comics

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

Fetches a single comic by id. GET /v1/public/comics/{comicId}

@client.comic(29380)

Fetches lists of characters filtered by a comic id. GET /v1/public/comics/{comicId}/characters

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

Fetches lists of creators filtered by a comic id. GET /v1/public/comics/{comicId}/creators

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

Fetches lists of events filtered by a comic id. GET /v1/public/comics/{comicId}/events

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

Fetches lists of stories filtered by a comic id. GET /v1/public/comics/{comicId}/stories

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

Creators

Fetches lists of creators. GET /v1/public/creators

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

@client.creator(15)

Fetches lists of comics filtered by a creator id. GET /v1/public/creators/{creatorId}/comics

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

Fetches lists of events filtered by a creator id. GET /v1/public/creators/{creatorId}/events

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

Fetches lists of series filtered by a creator id. GET /v1/public/creators/{creatorId}/series

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

Fetches lists of stories filtered by a creator id. GET /v1/public/creators/{creatorId}/stories

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

Events

Fetches lists of events. GET /v1/public/events

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

Fetches a single event by id. GET /v1/public/events/{eventId}

@client.event(227)

Fetches lists of characters filtered by an event id. GET /v1/public/events/{eventId}/characters

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

Fetches lists of comics filtered by an event id. GET /v1/public/events/{eventId}/comics

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

Fetches lists of creators filtered by an event id. GET /v1/public/events/{eventId}/creators

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

Fetches lists of series filtered by an event id. GET /v1/public/events/{eventId}/series

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

Fetches lists of stories filtered by an event id. GET /v1/public/events/{eventId}/stories

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

Series

Fetches lists of series. GET /v1/public/series

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

Fetches a single comic series by id. GET /v1/public/series/{seriesId}

@client.serie(354)

Fetches lists of characters filtered by a series id. GET /v1/public/series/{seriesId}/characters

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

Fetches lists of comics filtered by a series id. GET /v1/public/series/{seriesId}/comics

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

Fetches lists of creators filtered by a series id. GET /v1/public/series/{seriesId}/creators

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

Fetches lists of events filtered by a series id. GET /v1/public/series/{seriesId}/events

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

Fetches lists of stories filtered by a series id. GET /v1/public/series/{seriesId}/stories

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

Stories

Fetches lists of stories. GET /v1/public/stories

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

Fetches a single comic story by id. GET /v1/public/stories/{storyId}

@client.story(6320)

Fetches lists of characters filtered by a story id. GET /v1/public/stories/{storyId}/characters

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

Fetches lists of comics filtered by a story id. GET /v1/public/stories/{storyId}/comics

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

Fetches lists of creators filtered by a story id. GET /v1/public/stories/{storyId}/creators

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

Fetches lists of events filtered by a story id. GET /v1/public/stories/{storyId}/events

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

Fetches lists of series filtered by a story id. GET /v1/public/stories/{storyId}/series

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

O-I / marvel

readme