Project

harkness

0.0
No release in over a year
Dive into the Marvel universe with this comprehensive Ruby library for the Marvel API at https://developer.marvel.com.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 3.6
~> 3.12
~> 0.6.0
~> 0.22.0
~> 0.9.6
~> 6.1
~> 3.18
~> 0.9.28

Runtime

~> 2.7
~> 0.9.0
 Project Readme

Harkness

A full-featured and painstakingly documented library for working (playing) with the Marvel API.

main codecov Gem Version

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.

      client.characters.list(nameStartsWith: "Ant-", limit: 10, orderBy: "-modified")
    • 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 ID 1234.
  • 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

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.