![Galactus](http://static.comicvine.com/uploads/square_medium/3/31666/3230561-tumblr_mqd1qnuvu71qknht2o2_1280.jpg)

# Galactus

On 31 January 2014 Marvel Comics [put out a press release](http://marvel.com/news/comics/21871/marvel_announces_the_release_of_the_api_program) announcing an API connecting to Marvel's database of comics, characters, and creators.

Galactus provides a very simple wrapper for the [Marvel API](http://developer.marvel.com/) 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](https://en.wikipedia.org/wiki/Galactus) 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:

```ruby
gem 'galactus'
```

To get the latest code:

```ruby
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](#usage)
* [Endpoints](#endpoints)

## 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](http://developer.marvel.com). These are required to configure and instantiate a Galactus client.

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_0).

```ruby
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}`](http://developer.marvel.com/docs#!/public/getCharacterIndividual_get_1). 

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicsCharacterCollection_get_2).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCharacterEventsCollection_get_3).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCharacterSeriesCollection_get_4).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCharacterStoryCollection_get_5).

```ruby
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.

See [`GET /v1/public/comics`](http://developer.marvel.com/docs#!/public/getComicsCollection_get_6).

```ruby
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}`](http://developer.marvel.com/docs#!/public/getComicIndividual_get_7).

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicCharacterCollection_get_8).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_9).

```ruby
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`](http://developer.marvel.com/docs#!/public/getIssueEventsCollection_get_10).

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicStoryCollection_get_11).

```ruby
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.

See [`GET /v1/public/creators`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_12).

```ruby
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}`](http://developer.marvel.com/docs#!/public/getCreatorIndividual_get_13).

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicsCollection_get_14).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorEventsCollection_get_15).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorSeriesCollection_get_16).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorStoryCollection_get_17).

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

### Event Endpoints

#### Events

Allows you to get a list of events.

See [`GET /v1/public/events`](http://developer.marvel.com/docs#!/public/getEventsCollection_get_18).

```ruby
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}`](http://developer.marvel.com/docs#!/public/getEventIndividual_get_19).

```ruby
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`](http://developer.marvel.com/docs#!/public/getEventCharacterCollection_get_20).

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicsCollection_get_21).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_22).

```ruby
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`](http://developer.marvel.com/docs#!/public/getEventSeriesCollection_get_23).

```ruby
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`](http://developer.marvel.com/docs#!/public/getEventStoryCollection_get_24).

```ruby
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.

See [`GET /v1/public/series`](http://developer.marvel.com/docs#!/public/getSeriesCollection_get_25).

```ruby
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}`](http://developer.marvel.com/docs#!/public/getSeriesIndividual_get_26).

```ruby
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`](http://developer.marvel.com/docs#!/public/getSeriesCharacterWrapper_get_27).

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicsCollection_get_28).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_29).

```ruby
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`](http://developer.marvel.com/docs#!/public/getEventsCollection_get_30).

```ruby
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`](http://developer.marvel.com/docs#!/public/getSeriesStoryCollection_get_31).

```ruby
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.

See [`GET /v1/public/stories`](http://developer.marvel.com/docs#!/public/getStoryCollection_get_32).

```ruby
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}`](http://developer.marvel.com/docs#!/public/getStoryIndividual_get_33).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_34).

```ruby
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`](http://developer.marvel.com/docs#!/public/getComicsCollection_get_35).

```ruby
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`](http://developer.marvel.com/docs#!/public/getCreatorCollection_get_36).

```ruby
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`](http://developer.marvel.com/docs#!/public/getEventsCollection_get_37).

```ruby
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`](http://developer.marvel.com/docs#!/public/getStorySeriesCollection_get_38).

```ruby
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](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](contributor-covenant.org) code of conduct.

To contribute to Galactus:

1. [Fork the project](http://gun.io/blog/how-to-github-fork-branch-and-pull-request/).
2. Create a feature branch. (`git checkout -b my-new-feature`)
3. Commit your changes. (`git commit -am 'new feature'`)
4. Push the branch. (`git push origin my-new-feature`)
5. Create a new [pull request](https://help.github.com/articles/using-pull-requests).

## Author

* [Jeff Nyman](http://testerstories.com)

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).