evri / EvriApi

EvriApi
-------
The EvriApi is a Cocoa library for connecting to the Evri web API,
written in Objective-C. This is not a comprehensive wrapper for the
entire Evri Web API, but encompasses much of its functionality. For
details on the Evri Web API, see http://api.evri.com.

This project is intended to be built as a static library and included
in other projects. We built this initially for our iPhone application
so no effort has been made to make it a dynamic framework.

Getting Started
---------------
If you've gotten this far, you probably already have the source
code. The way we use it in our iPhone application is to import the
source (without copying the files) into the iPhone project and build
from there.

Everything starts with the "EvriApi" class. You need to instantiate
one and provide a handful of parameters, like so:

  EvriApi *api = [[EvriApi alloc] initWithAppID:appId];

Here, the "appId" parameter should be some string identifier for your
application.

Interaction Style
-----------------
All calls to the EvriApi class are asynchronous. As a result each
method requires a target and a selector to callback when the result
returns from the API. These callback methods must accept a single
parameter, which is an instance of EvriApiResponse*. For example:

  - (void)handlePopularityList:(EvriApiResponse *response) {
    if ([response success]) {
      // do happy-path stuff
      Entity *entity = (Entity *)[response responseObject];
    }
    else {
      // make a sad-face
    }
  }

Successful response usually contain a model object which can be
retrieved by calling the "responseObject" method. The entity classes
are in the Model group.

Because requests are asynchronous, there may be times where a
user-interaction would remove the target object before the EvriApi can
call back with results. In general the API is pretty robust at
handling these, but it's a good practice to cancel any outstanding
requests while cleaning up.

For example, in an iPhone application, when the view is loaded the
request is initiated in the -viewDidLoad method. The request
identifier is stored as an ivar and in the -viewWillDisappear method
the request is cancelled by calling -cancelRequest on the EvriApi
instance. You may want to store the API as a member field of your
application delegate so all of your controllers can find it.

Compiler Flags
--------------
There are a handful of compiler flags that affect the behavior of
the API library. They are:

  EVRI_API_LOG
  If set, the URLs for all HTTP requests will be logged via NSLog.

  EVRI_API_METRICS
  If set, a dictionary of request and parsing metrics will be dumped
  via NSLog for each HTTP request.