EAAL

From EVEDev
Jump to: navigation, search
Api.pngAPI Resources - Category Home - API Libraries - API Usage Examples - API Method Reference
EAAL
Maintainer: Peter Petermann (eve: Peter Powers)
Stable release: 0.1.7
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

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.

Usage

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

Request Information

  result = api.ApiPage

this will return an Object of type ScopeApiPageResult which then can be used to do read the api result

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
  }

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

Example 3, Example 2 in short

  require 'eaal'
  puts EAAL::Api.new("my userid", "my API key", "eve").CharacterID(:names => "Peter Powers").characters.name

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)

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

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

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.

Bugs

please report bugs at http://rubyforge.org/tracker/?group_id=7466

ISK

feel free to send ISK ingame to "Peter Powers" cafe24 faq view api

Retrieved from "?title=EAAL&oldid=5693"
Personal tools