Galactus
On 31 January 2014 Marvel Comics put out a press release announcing an API connecting to Marvel's database of comics, characters, and creators.
Galactus provides a very simple wrapper for the Marvel API and attempts to make that API easily queryable by providing qualifier objects that allows a consumer of the API to drill down into specific details.
Galactus is a Marvel super-villain who was apparently the sole survivor of a universe that existed before the 'Big Bang' that created our own universe. As accomplishments go, that's moderately impressive, to say the least.
Installation
To get the latest stable release, add this line to your application's Gemfile:
gem 'galactus'
To get the latest code:
gem 'galactus', git: https://github.com/jnyman/galactus
After doing one of the above, execute the following command:
$ bundle
You can, of course, just install the gem directly like this:
$ gem install galactus
Contents
Usage
Setting Up the Client
You need API credentials, which is a public and private key pair. You can get yours at the Marvel Developer Portal. These are required to configure and instantiate a Galactus client.
require 'galactus'
client = Galactus::Client.new(
public_api_key: 'your public api key',
private_api_key: 'your private api key')
Make sure you put in your own public and private keys that you were assigned. The client variable will now hold a Galactus::Client instance that you can call endpoint methods on.
Endpoints
Most requests to the API, return a Galactus::Response object if there was a successful response or a Galactus::ErrorResponse if API response returns an error. These objects are the raw API response enhanced with Hashie methods.
Just about all endpoints can receive optional parameters to narrow down results and those will be documented below. Each endpoint described below links to the associated call in Marvel's interactive API tester. That link will show you a complete list of the parameters that you can pass to the relevant method.
Character Endpoints
Characters
Allows you to get a list of comic characters.
See GET /v1/public/characters.
client.characters
client.characters(name: 'Spider-Man')
client.characters(limit: 10, offset: 400, orderBy: 'name')
client.characters(name: 'Thanos')
client.characters(nameStartsWith: 'Th', orderBy: 'modified')
Character
Allows you to get a single character resource. This endpoint accepts an integer or string value as the character id.
See GET /v1/public/characters/{characterId}.
client.character(1009610)
client.character('Spider-Man')
Character Comics
Allows you to get a list of comics containing a specific character. This endpoint requires a character id value (integer or string).
See GET /v1/public/characters/{characterId}/comics.
client.character_comics(1009610)
client.character_comics('Spider-Man')
client.character_comics(1009610, { format: 'graphic novel', limit: 10, orderBy: 'title' })
client.character_comics('Spider-Man', { format: 'graphic novel', limit:, orderBy: 'title' } )
client.character_comics(1009652, titleStartsWith: 'Infinity', hasDigitalIssue: true)
Character Events
Allows you to get a list of events in which a specific character appears. This endpoint requires a character id value (integer or string).
See GET /v1/public/characters/{characterId}/events.
client.character_events(1009610)
client.character_events('Spider-Man')
client.character_events(1009610, { limit: 10, orderBy: 'name' })
client.character_events('Spider-Man', { limit: 10, orderBy: 'name' })
client.character_events(1009652, name: 'Infinity Gauntlet')
Character Series
Allows you to get a list of comic series in which a specific character appears. This endpoint requires a character id value (integer or string).
See GET /v1/public/characters/{characterId}/series.
client.character_series(1009610)
client.character_series('Spider-Man')
client.character_series(1009610, { seriesType: 'ongoing', limit: 10, orderBy: 'title' })
client.character_series('Spider-Man', { seriesType: 'ongoing', limit: 10, orderBy: 'title' }
client.character_series(1009652, contains: 'hardcover')
Character Stories
Allows you to get a list of comic stories featuring a specific character. This endpoint requires a character id value (integer or string).
See GET /v1/public/characters/{characterId}/stories.
client.character_stories(1009610)
client.character_stories('Spider-Man')
client.character_stories(1009610, { limit: 10, offset: 20 })
client.character_stories('Spider-Man', { limit:, offset: 20 })
client.character_stories(1009652, limit: 50)
Comic Endpoints
Comics
Allows you to get a list of comics.
client.comics
client.comics(format: 'graphic novel', limit: 10, offset: 20 })
client.comics(title: 'Daredevil')
client.comics(startYear: 1950, issueNumber: 1)
Comic
Allows you to get a a single comic resource. This endpoint requires a comic id value, which must be an integer.
See GET /v1/public/comics/{comicId}.
client.comic(40128)
Comic Characters
Allows you to get a list of characters which appear in a specific comic. This endpoint requires a comic id value, which must be an integer.
See GET /v1/public/comics/{comicId}/characters.
client.comic_characters(40128)
client.comic_characters(40128, orderBy: 'name', limit:, offset: 20)
client.comic_characters(34249, orderBy: 'name')
Comic Creators
Allows you to get a list of comic creators whose work appears in a specific comic. This endpoint requires a comic id value, which must be an integer.
See GET /v1/public/comics/{comicId}/creators.
client.comic_creators(40128)
client.comic_creators(40128, lastName: 'Romita')
client.comic_creators(34249, lastNameStartsWith: 'V')
Comic Events
Allows you to get a list of events in which a comic appears. This endpoint requires a comic id value, which must be an integer.
See GET /v1/public/comics/{comicId}/events.
client.comic_events(40128)
client.comic_events(40128, orderBy: 'name', limit: 10)
client.comic_events(27272, orderBy: '-startDate')
Comic Stories
Allows you to get a list of comic stories in a specific comic issue. This endpoint requires a comic id value, which must be an integer.
See GET /v1/public/comics/{comicId}/stories.
client.comic_stories(40128)
client.comic_stories(40128, orderBy: 'name', limit: 10)
client.comic_stories(27272, creators: [600, 801])
Creator Endpoints
Creators
Allows you to get a lists of creators.
client.creators
client.creators(firstName: 'Frank', lastName: 'Miller')
client.creators(lastNameStartsWith: 'Mo', limit: 20, offset: 20)
Creator
Allows you to get a single creator resource. This endpoint requires a creator id value, which must be an integer.
See GET /v1/public/creators/{creatorId}.
client.creator(15)
Creator Comics
Allows you to get a list of comics from a given creator. This endpoint requires a creator id value, which must be an integer.
See GET /v1/public/creators/{creatorId}/comics.
client.creator_comics(15)
client.creator_comics(15, format: 'trade paperback')
Creator Events
Allows you to get a list of events from a given creator. This endpoint requires a creator id value, which must be an integer.
See GET /v1/public/creators/{creatorId}/events.
client.creator_events(30)
client.creator_events(30, nameStartsWith: 'Civil')
Creator Series
Allows you to get a list of series from a given creator. This endpoint requires a creator id value, which must be an integer.
See GET /v1/public/creators/{creatorId}/series.
client.creator_series(30)
client.creator_series(30, seriesType: 'limited')
Creator Stories
Allows you to get a list of stories from a given creator. This endpoint requires a creator id value, which must be an integer.
See GET /v1/public/creators/{creatorId}/stories.
client.creator_stories(30)
client.creator_stories(30, limit: 40, offset: 7750)
Event Endpoints
Events
Allows you to get a list of events.
client.events
client.events(name: 'Acts of Vengeance')
client.events(orderBy: 'name')
client.events(name: 'Infinity Gauntlet')
client.events(characters: [1009156, 1009652])
Event
Allows you to get a single comic resource. This endpoint requires an event id value (integer or string).
See GET /v1/public/events/{eventId}.
client.event(116)
client.event('Acts of Vengeance!')
Event Characters
Allows you to get a list of characters which appear in a specific event. This endpoint requires an event id value (integer or string).
See GET /v1/public/events/{eventId}/characters.
client.event_characters(116)
client.event_characters('Acts of Vengeance!')
client.event_characters(116, orderBy: 'name', limit: 30, offset: 20)
client.event_characters('Acts of Vengeance!', orderBy: 'name', limit: 30, offset: 20)
client.event_characters(227, modifiedSince: '2014-04-29')
Event Comics
Allows you to get a list of comics which take place during a specific event. This endpoint requires an event id value (integer or string).
See GET /v1/public/events/{eventId}/comics.
client.event_comics(116)
client.event_comics('Acts of Vengeance!')
client.event_comics(116, format: 'graphic novel', orderBy: 'title', limit: 10)
client.event_comics('Acts of Vengeance!', format: 'graphic novel', orderBy: 'title', limit: 10)
client.event_comics(227, hasDigitalIssue: true, orderBy: 'onsaleDate')
Event Creators
Allows you to get a list of comic creators whose work appears in a specific event. This endpoint requires an event id value (integer or string).
See GET /v1/public/events/{eventId}/creators.
client.event_creators(116)
client.event_creators('Acts of Vengeance!')
client.event_creators(116, lastName: 'Albrecht')
client.event_creators('Acts of Vengeance!', lastName: 'Albrecht')
client.event_creators(227, lastNameStartsWith: 'Lar')
Event Series
Allows you to get a list of comic series in which a specific event takes place. This endpoint requires an event id value (integer or string).
See GET /v1/public/events/{eventId}/series.
client.event_series(116)
client.event_series('Acts of Vengeance!')
client.event_series(116, orderBy: 'title', limit: 10)
client.event_series('Acts of Vengeance!', orderBy: 'title', limit: 10)
client.event_series(227, startYear: 1995, seriesType: 'limited')
Event Stories
Allows you to get a list of comic stories from a specific event. This endpoint requires an event id value (integer or string).
See GET /v1/public/events/{eventId}/stories.
client.event_stories(116)
client.event_stories(116, limit: 10)
client.event_stories('Acts of Vengeance!')
client.event_stories('Acts of Vengeance!', limit: 10)
client.event_stories(227, orderBy: 'id', limit: 30, offset: 20)
Series Endpoints
Series
Allows you to get a list of series.
client.series
client.series(name: 'Spider-Man')
client.series(orderBy: 'title')
client.series(title: 'Uncanny X-Men')
client.series(titleStartsWith: 'Astonishing', orderBy: 'startDate', limit: 100)
Serie
Do note the particular spelling here!
Allows you to get a single series resource. This endpoint requires an serie id value (integer).
See GET /v1/public/series/{seriesId}.
client.serie(2069)
Series Characters
Allows you to get a list of characters which appear in a specific series. This endpoint requires an serie id value (integer).
See GET /v1/public/series/{seriesId}/characters.
client.series_characters(2069)
client.series_characters(2069, orderBy: 'name', limit: 30, offset: 20)
client.series_characters(354, nameStartsWith: 'Iron')
Series Comics
Allows you to get a list of comics which are published as part of a specific series. This endpoint requires an serie id value (integer).
See GET /v1/public/series/{seriesId}/comics.
client.series_comics(2069)
client.series_comics(2069, format: 'graphic novel', orderBy: 'title', limit: 10)
client.series_comics(354, issueNumber: 1)
Series Creators
Allows you to get a list of comic creators whose work appears in a specific series. This endpoint requires an serie id value (integer).
See GET /v1/public/series/{seriesId}/creators.
client.series_creators(354)
client.series_creators(354, lastName: 'Kirby')
Series Events
Allows you to get a list of comic events which occur in a specific series. This endpoint requires an serie id value (integer).
See GET /v1/public/series/{seriesId}/events.
client.series_events(2069)
client.series_events(2069, orderBy: 'name', limit: 10)
client.series_events(354, orderBy: 'startDate')
Series Stories
Allows you to get a list of comic stories from a specific series. This endpoint requires an serie id value (integer).
See GET /v1/public/series/{seriesId}/stories.
client.series_stories(2069)
client.series_stories(2069, limit: 10)
client.series_stories(354, modifiedSince: '2013-06-01')
Story Endpoints
Stories
Allows you to get a list of stories.
client.stories
client.stories(limit: 50, offset: 100)
client.stories(orderBy: 'id')
client.stories(creators: 15)
client.stories(characters: [1009156, 1009652], orderBy: '-modified')
Story
Allows you to get a single story resource. This endpoint requires an story id value (integer).
See GET /v1/public/stories/{storyId}.
client.story(2210)
Story Characters
Allows you to get a list of characters which appear in a specific story. This endpoint requires a story id value (integer).
See GET /v1/public/stories/{storyId}/characters.
client.story_characters(2210)
client.story_characters(2210, orderBy: 'name', limit: 30, offset: 20)
client.story_characters(14410, nameStartsWith: 'D')
Story Comics
Allows you to get a list of comics in which a specific story appears. This endpoint requires an story id value (integer).
See GET /v1/public/stories/{storyId}/comics.
client.story_comics(2210)
client.story_comics(2210, format: 'graphic novel', orderBy: 'title', limit: 10)
client.story_comics(126, format: 'trade paperback')
Story Creators
Allows you to get a list of comic creators whose work appears in a specific story. This endpoint requires an story id value (integer).
See GET /v1/public/stories/{storyId}/creators.
client.story_creators(2210)
client.story_creators(2210, lastName: 'Albrecht')
client.story_creators(126, lastNameStartsWith: 'S')
Story Events
Allows you to get a list of comic events in which a specific story appears. This endpoint requires an story id value (integer).
See GET /v1/public/stories/{storyId}/events.
client.story_events(2210)
client.story_events(2210, orderBy: 'name', limit: 10)
Story Series
Allows you to get a list of comic series in which the specified story takes place. This endpoint requires a story id value (integer).
See GET /v1/public/stories/{storyId}/series.
client.story_series(2210)
client.story_series(2210, orderBy: 'title', limit: 10)
client.story_series(126, titleStartsWith: 'Infinity')
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/jnyman/galactus. Just as superheroes try to work together for the better good, this project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
To contribute to Galactus:
- Fork the project.
- Create a feature branch. (
git checkout -b my-new-feature) - Commit your changes. (
git commit -am 'new feature') - Push the branch. (
git push origin my-new-feature) - Create a new pull request.
Author
License
The gem is available as open source under the terms of the MIT License.