Harkness
A full-featured and painstakingly documented library for working (playing) with the Marvel API.
Installation
Install the gem and add to the application's Gemfile by executing:
bundle add harkness
If bundler is not being used to manage dependencies, install the gem by executing:
gem install harkness
Usage
-
Get your Marvel API public key and private key on your Marvel developer account.
-
Set your public key and private key as environment variables using your preferred method.
export MARVEL_PUBLIC_KEY=my_public_key
export MARVEL_PRIVATE_KEY=my_private_key
- Create a Harkness client.
require "harkness"
client = Harkness::Client.new(public_key: ENV["MARVEL_PUBLIC_KEY"], private_key: ENV["MARVEL_PRIVATE_KEY"])
-
Use the client to access API resources.
-
Use
list
on any resource to get all, paginated, items for that resource.- Pass any valid parameters to the
list
method.
client.characters.list(nameStartsWith: "Ant-", limit: 10, orderBy: "-modified")
- Pass any valid parameters to the
-
Use
retrieve
to get a single resource by ID. -
Get related resources, too!
- Ex.
client.comics.characters(comic_id: 1234)
will get all characters for the comic with ID1234
.
- Ex.
-
-
All resources are classes in the
Harkness
module and attributes can be easily accessed just as you would access them normally.
irb(main):001:0> client = Harkness::Client.new(public_key: ENV["MARVEL_PUBLIC_KEY"], private_key: ENV["MARVEL_PRIVATE_KEY"])
=>
#<Harkness::Client:0x00000001083a93d8
...
irb(main):002:0> character = client.characters.list(nameStartsWith: "Ant-", limit: 1, orderBy: "modified")
=>
#<Harkness::CharacterDataWrapper:0x0000000108c740f8
...
irb(main):003:0> character.data.results[0].name
=> "Ant-Man (Eric O'Grady)"
Resources
Characters
client.characters.list
client.characters.retrieve(character_id: 1234)
client.characters.comics(character_id: 1234)
client.characters.events(character_id: 1234)
client.characters.series(character_id: 1234)
client.characters.stories(character_id: 1234)
Comics
client.comics.list
client.comics.retrieve(comic_id: 1234)
client.comics.characters(comic_id: 1234)
client.comics.creators(comic_id: 1234)
client.comics.events(comic_id: 1234)
client.comics.stories(comic_id: 1234)
Creators
client.creators.list
client.creators.retrieve(comic_id: 1234)
client.creators.comics(creator_id: 1234)
client.creators.events(creator_id: 1234)
client.creators.series(creator_id: 1234)
client.creators.stories(creator_id: 1234)
Events
client.events.list
client.events.retrieve(event_id: 1234)
client.events.comics(event_id: 1234)
client.events.series(event_id: 1234)
client.events.creators(event_id: 1234)
client.events.characters(event_id: 1234)
client.events.stories(event_id: 1234)
Series
client.series.list
client.series.retrieve(series_id: 1234)
client.series.comics(series_id: 1234)
client.series.events(series_id: 1234)
client.series.creators(series_id: 1234)
client.series.characters(series_id: 1234)
client.series.stories(series_id: 1234)
Stories
client.stories.list
client.stories.retrieve(story_id: 1234)
client.stories.comics(story_id: 1234)
client.stories.events(story_id: 1234)
client.stories.creators(story_id: 1234)
client.stories.characters(story_id: 1234)
client.stories.series(story_id: 1234)
Docs
- Browse the painstakingly documented code.
- View the interactive API tester at Marvel.
Contributing
See contributing.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting with the Harkness project is expected to follow the code of conduct.