Ultron

Ruby bindings for the Marvel Comics API

git clone https://github.com/pikesley/ultron
cd ultron
bundle
rake

Or just

gem install ultron

To actually use it you need an API keypair which you can get from here, put them into ~/.ultronrc or .env like this

PUBLIC_KEY: this_r_public_key
PRIVATE_KEY: this_one_r_private_key

I’ve built another gem which uses Ultron to explore the data.

API

I’ve tried to follow the Marvel API as closely as possible. It’s probably best illustrated with some examples from the specs:

Get a thing by its ID

it 'should find a comic', :vcr do
  comic = Comics.find 12518
  expect(comic.title).to eq ('Uncanny X-Men (1963) #67')
end

Get a set of things filtered by some other thing

it 'should find a list of comics featuring the character', :vcr do
  character = Characters.find 1009610
  expect(character.name).to eq ('Spider-Man')
  comics = Comics.by_character 1009610
  expect(comics.first.title).to eq ('Superior Spider-Man (2013) #22')
  expect(comics.class).to eq (Comics)
  expect(comics.count).to eq (20)
end

Get a set of things using query-string parameters

it 'should let us search with parameters', :vcr do
  comics = Comics.where sharedAppearances: '1009351,1009718' # Hulk and Wolverine
  expect(comics[7].title).to eq ('Deadpool (2008) #37')
end

Get a set of things using multiple query-string parameters

it 'should let us search with multiple parameters', :vcr do
  comics = Comics.where sharedAppearances: '1009610,1009718', events: 302 # Spider-Man and Wolverine, Fear Itself
  expect(comics.first.title).to eq ('Fear Itself (2010) #7')
end

Get a set of things filtered by another thing and with a query-string

it 'should let us get comics by a creator *with params*', :vcr do
  comics = Comics.by_creator_and_with 214, dateRange: '1980-01-01,1989-12-31'
  expect(comics.first.resourceURI).to eq ('http://gateway.marvel.com/v1/public/comics/8268')
end

Get a random thing

Something like this works, but it’s proving very difficult to test it:

Characters.sample
  it 'should give us a random comic', :vcr do
    set = Comics.by_character 1009610
    set.stub(:random_offset).and_return(512)
    expect(set.sample.title).to eq ('Amazing Spider-Man (1999) #590')
  end

  it 'should give us a random comic for a more complex search', :vcr do
    set = Comics.by_creator_and_with 214, dateRange: '1980-01-01,1989-12-31'
    set.stub(:random_offset).and_return(99)
    expect(set.sample.title).to eq ('Dazzler (1981) #19')
  end

Pre-baked custom searches

There’s a lot of noise in the data, and I found myself applying the same filters again and again. So:

it 'should give us regular comics filtered by character', :vcr do
  comics = Comics.by_character_and_vanilla_comics 1009685
  expect(comics.first.title).to eq ('AGE OF ULTRON (2013) #1')
end

This applies the following search params:

format: 'comic', formatType: 'comic', noVariants: true

which purges all sorts of hardbacks and reprints and so on from the results.

Exceptions

Catch and re-raise a 404

it 'should throw a 404 (wrapped in a Marvel exception) on a 404', :vcr do
  begin
    comic = Comics.find 1000000 # there are not a million comics
  rescue MarvelException => e
    expect(e.code).to eq (404)
    expect(e.status).to eq ("We couldn't find that comic_issue")
  end
end

Raise a custom exception when we do something dumb

it 'should throw a Resource Not Found exception when we search for something nonsensical', :vcr do
  begin
    characters = Characters.by_creator 186 # characters by creator is a nonsense concept in the Marvel API
  rescue UltronException => e
    expect(e.status).to eq ('Resource does not exist. Check http://developer.marvel.com/docs')
  end
end

This all got a lot more elegant after a chat over a fry-up with @floppy at the always-superb First-Step Cafe in Shoreditch.

And here’s a Gource video of the project as of 2014-02-17.

Back to top