EAAL
From EVEDev
 | API Resources - Category Home - API Libraries - API Usage Examples - API Method Reference |
| EAAL | |
|---|---|
| Maintainer: | Peter Petermann (eve: Peter Powers) |
| Stable release: | 0.1.6 |
| Development release: | git://github.com/ppetermann/eaal.git |
| OS: | Platform independant |
| License: | MIT |
| Website: | http://github.com/ppetermann/eaal/ |
EAAL is a Ruby library for accessing the EVE API. It comes with some metaprogramming-fu so it should be able to handle additions to the EVE API without changes to the library. It also comes with a built in cache mechanism that, once enabled, respects the API cache timers and caches data using either memcached or file storage.
Contents |
[edit] Installation
Installation is as simple as instlaling a ruby gem can be: (sudo) gem install eaal on your command line. (you need to have ruby & rubygems installed). EAAL has three dependencies: activesupport, memcache-client and hpricot, which should be installed by gem.
[edit] Usage
[edit] Initialize the API Object
require 'eaal'
api = EAAL::API.new("my Userid", "my API key"[, "scope for requests"])
the scope is the one used for the API requests, ex. account/char/corp/eve/map/server see API Reference the scope can be changed during runtime and defaults to account
[edit] Request Information
result = api.ApiPage
this will return an Object of type ScopeApiPageResult which then can be used to do read the api result
[edit] Example 1, getting a list of characters on the account:
require 'eaal'
api = EAAL::API.new("my userid", "my API key")
result = api.Characters
result.characters.each{|character|
puts character.name
}
[edit] Example 2, getting the id for a given character name
require 'eaal'
api = EAAL::API.new("my userid", "my API key")
api.scope = "eve"
result = api.CharacterID(:names => "Peter Powers")
puts result.characters.first.characterID
[edit] Example 3, Example 2 in short
require 'eaal'
puts EAAL::Api.new("my userid", "my API key", "eve").CharacterID(:names => "Peter Powers").characters.name
[edit] Exceptions
Errors returned by the EVE API are handled a bit unique, since i wanted to have them pretty much dynamic (so i dont need to hack EAAL whenever CCP adds a new Error) you have to use dynamic created classes to catch 'em (if you dont want to catch EAAL::Exception::EveAPIException in general that is)
[edit] Example 4, catching a specific EVE API Exception
require 'eaal'
api = EAAL::API.new("my userid", "my API key")
api.scope = "char"
begin
api.Killlog("characterID" => "12345") #this example offcourse
# assumes your not having the key for character 12345 loaded ;)
rescue EAAL::Exception.EveAPIException(201)
puts "i just caught myself an exception"
end
[edit] Using the cache
EAAL comes with a simple file cache, which can be used by doing
EAAL.cache = EAAL::Cache::FileCache.new(path)
if you dont give a path it defaults to $HOME/.eaal/cache
[edit] Example 5, doing a cached request
require 'eaal'
EAAL.cache = EAAL::Cache::FileCache.new # set cache
api = EAAL::API.new("my userid", "my API key") # initialize API object
charid = api.Characters.characters.first.characterID # get the characterID of the first character on account
api.scope = "char" # set scope to "char"
kills = api.Killlog("characterID" => charid).kills # request Killlog API Page
both requests in this example will check if the XML is allready available in the cache folder, if it is they will check if cachedUntil expired, if it did requests will be made to the API, if it didnt the XML file will be load.
[edit] Bugs
please report bugs at http://rubyforge.org/tracker/?group_id=7466
[edit] ISK
feel free to send ISK ingame to "Peter Powers"
