README.md in galactus-0.1.0 vs README.md in galactus-0.2.0

- old
+ new

@@ -1,32 +1,571 @@ +![Galactus](http://static.comicvine.com/uploads/square_medium/3/31666/3230561-tumblr_mqd1qnuvu71qknht2o2_1280.jpg) + # Galactus -Galactus provides a simple wrapper for the [Marvel API](http://developer.marvel.com/). +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 -Add this line to your application's Gemfile: +To get the latest stable release, add this line to your application's Gemfile: ```ruby gem 'galactus' ``` -And then execute: +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 -Or install it yourself as: +You can, of course, just install the gem directly like this: $ gem install galactus +## Contents + +* [Usage](#usage) +* [Endpoints](#endpoints) + ## Usage -Usage instructions will be coming soon. +### 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). 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. +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).