Friday, April 17, 2015

New client libraries, PHP client bindings, contributed applications and other significant improvements released to the beta site

A few days ago we released a substantial update to our beta site.  Many improvements have been made to the back end to make things more efficient, and a few creature comforts have been added to the front end as well.  We'll likely reflect these changes to the main site sometime this week.

I'll cover the minor changes at the end of the blog.  There are three big changes that I need to describe in more detail.  Without further ado:

Client Libraries Now Class Based

What this means is that the various client bindings we offer are now encapsulated in classes rather than exposed as top level functions which required all arguments to be passed on every call.  We made this change to make it easier to manage credentials and also in support of the new "contributed applications" functionality described below.  There is one exception: we didn't change the Java client library.  We'll do that eventually, be we left it for last because no one is really using that library at the moment.

Each client library now provides four classes:
  • CapsuleerAPI: this class exposes all methods used to access capsuleer data from a synchronized account.
  • CorporationAPI: this class exposes all methods used to access corporation data from a synchronized account.
  • ReferenceAPI: this class exposes methods for retrieving EVE server reference information (e.g. the current skill tree).
  • SDEAPI: this is actually two classes, one for each of the two latest EVE Online releases.  These classes expose methods for retrieving Static Data Export (SDE) information.
To use the new API, you first instantiate one of these classes and pass EveKit API key information into the constructor.  You can then call the methods of the class without having to present your EveKit API key on every call.  The SDE API also allows you to specify the name of the release you'd like.  If you don't specify a release, then you'll get the API for the latest release.  If you're release agnostic, then upgrading your code just got easier: just never pass a release string into the SDE API constructor and you'll always use the latest release.

NOTE: this change does not actually change the underlying REST calls.  Instead, this change repackages how the various client bindings are exposed.  If you're making direct REST calls, you won't be affected by this change.  Likewise, if you've downloaded an older version of the client, then that client will continue to work until you need a feature only present in a newer release.

Let's look at a few examples in Google App Script (essentially, Javascript without requiring callbacks) to see how your code will change.  Before the change, getting your corporation assets might look like this:

var apikey = 1234;
var apihash =  'FA8EB656E23C0AE73796F9D17E7A0290B2BA3952BF89C3B1E4A35FDE480E6E06';
var assetResponse = commGetAssets(apikey, apihash);

In the new code, there is one extra step:

var apikey = 1234;
var apihash =  'FA8EB656E23C0AE73796F9D17E7A0290B2BA3952BF89C3B1E4A35FDE480E6E06';
var corpAPI = new CorporationAPI(apikey, apihash);
var assetResponse = corpAPI.getAssets();

However, once you've created the CorporationAPI instance, you don't need to worry about API credentials any more unless someone changes the credentials on the EVE Online support page.  The same pattern works for the SDE API.  Before the change (retrieving list of agent types here):

var sdekey = 1234;
var sdehash =  'FA8EB656E23C0AE73796F9D17E7A0290B2BA3952BF89C3B1E4A35FDE480E6E06';
var agentTypesResponse = scylla_agtGetAllAgentType(sdekey, sdehash);

In the new code, you now instantiate an appropriate SDE class and make the call on that:

var sdekey = 1234;
var sdehash =  'FA8EB656E23C0AE73796F9D17E7A0290B2BA3952BF89C3B1E4A35FDE480E6E06';
var sdeAPI = new SDEAPI(sdekey, sdehash, 'scylla');
var agentTypesResponse = sdeAPI.agtGetAllAgentType();

If you leave the release name off of the call to "new SDEAPI" then you'll get the latest release.  Regardless, this normalizes the calls across versions so most of your code won't have to change when a new SDE comes out.

PHP Client API released

To accompany the change in how we present the client API, we've also released PHP client bindings.  You can download the code straight from the GitHub site or if you're using composer you can pull the package from packagist using the package name "dark-planet-labs/evekit-php".  The GitHub page contains complete instructions for how to integrate the code.

The PHP bindings are used in the same manner as the other bindings.  For example, the two code snippets above look as follows with the PHP bindings:

// See the GitHub site for details on how to ensure the bindings are in your path
use EveKit\EveKit;
// EveKit API key and hashcode.
$apikey = 1234;
$apihash = 'FA8EB656E23C0AE73796F9D17E7A0290B2BA3952BF89C3B1E4A35FDE480E6E06';
// Create an appropriate API instance
$api = EveKit::getCorporationAPI($apikey, $apihash);
// Retrieve and echo asset tree
echo $api->getAssets();
// Now let's pull something from the SDE
$sdekey = 5678;
$sdehash = 'FA8EB656E23C0AE73796F9D17E7A0290B2BA3952BF89C3B1E4A35FDE480E6E06';
// If we omit the last argument in this next call, then we'll get the API for the
// most recent release.
$sde = EveKit::getSDEAPI($sdekey, $sdehash, 'scylla');
// Retrieve and echo the list of agent types
echo $sde->getAllAgentTypes();
PHP calls return instances of EveKit\API\Response or EveKit\API\ResponseList as appropriate.  The structure of these objects follows the structure of similar objects in the other client bindings (e.g. Javascript).  One difference is that the PHP bindings throw exceptions on errors (like the Java bindings) as opposed to returning an error type (like the Javascript or GAS bindings).  Data types for API calls are defined in the EveKit\Types package.

Contributed Applications and the AppBridge

It's long been the goal to make EveKit a platform for others to develop their own third party apps.  The new "contributed application" feature is an attempt to further this goal.  A contributed application is just a third party website that you register with EveKit.  An EveKit user can then choose to "instantiate" a contributed application, in which case EveKit makes it possible for the contribute application to access EveKit data on behalf of the instantiating user.  The goal here is to simplify and standardize the way one builds applications designed to work with EveKit.

The details of this feature were described in a previous post, but here it is again with more careful explanation.  There are two logical parties involved in any contributed application: the application contributor, and the application user.  The application contributor is responsible for creating the contributed application, which consists of the following:
  • A unique name and description;
  • A URL pointing to the application web site;
  • An indication of whether the application should launch in a new page (this is needed for certain websites which don't allow authentication from a frame); 
  • A public or private designation; and,
  • One or more key-value pairs which represent the initial state of the app (these are strings).
Contributed applications are associated with the EveKit screen name you authenticated as at the time the application was contributed.  If you choose to make a contributed application public, then it can be searched and used by any other EveKit user.

An application user can choose to instantiate a contributed application.  An application instance has the following features:
  • A unique name;
  • An indication as to whether the application is allowed to use the user's SDE key; and,
  • A list of capsuleer or corporation access keys that should be made available to the instantiated application.
An instantiated application will appear in the "Apps" menu when the instantiating user is logged into EveKit.  When a user selects an instantiated application, a new frame or tab is opened using the URL of the contributed application.  The query string of this URL will contain two special parameters "evekitkey" and "evekithash" which represent a key-value pair the application can use to access the private key-value store of the application (including any API keys that have been shared with this application).  Through this mechanism, the contributed application can then access the exposed data of the application user.

The new EveKit client libraries include an "AppBridge" class which simplifies implementing contributed application websites.  This class is instantiated with the values of "evekitkey" and "evekithash", and provides convenience methods for interacting with the private key-value store of the instantiated application (including retrieving API keys).  Here's a snippet of code showing how the AppBridge class can be used in a PHP based contributed application:

// Pull in the EveKit client bindings
use EveKit\EveKit; 
// Extract evekitkey and evekithash from the URL
parse_str($_SERVER['QUERY_STRING'], $qstring);
$ekey = $qstring['evekitkey'];
$ehash = $qstring['evekithash'];
// Create the AppBridge.
$bridge = EveKit::getAppBridge($ekey, $ehash);
// Contributed applications may have a limited set of configuration data.
// You can read a configuration value as follows:
$val = $bridge->getConfig("somekey");
// You can save a configuration value like this:
$bridge->setConfig("somekey", "somevalue");
// For this example, let's assume the user assigned the SDE key and a corp
// key to this application.  You can get all the appropriate Corporation APIs
// like this:
$corpAPIs = $bridge->getCorporationAPIs();
// You can then make an API call as in the example above, e.g.
// (in this example, there is only one corp key)
$assets = $corpAPIs[0]->getAssets();
// The SDE API is equally easy to use, e.g.
$agentTypes = $bridge->getSDEAPI()->getAllAgentTypes();
// If you want a particular SDE release, you can also use this form:
$agentTypes = $bridge->getSDEAPI('scylla')->getAllAgentTypes();

The AppBridge provides raw access to the underlying API keys if needed, but in most cases you should only need to use the API convenience functions provided by this class.

Fine Print

And now some fine print around the contributed application feature:
  • Application names (both contributed and instantiated) must be alphanumeric (including underscore) and at least two characters in length;
  • Contributed application names must be unique among all applications contributed by the same user.  Likewise, instantiated application names must be unique among all applications instantiated by the same user;
  • The URL for a third party app must be less than 1000 character in length.  You're free to embed a query string but avoid the reserved strings "evekitkey" and "evekithash" which are used by EveKit to pass credentials to the instantiated application;
  • You can change most features of a contributed application at any time after it is submitted (if you were the original contributor);
  • Users "capture" a snapshot of your contributed application when they choose to use it.  This means that you can't break existing users if you decide to modify or remove a contributed application after one or more users have decided to use it.  You'll need to use other means to communicate with existing users of your application (e.g. if you need to make upgrades);
  • The private key-value store for an instantiated application has the following limits:
    • Keys must be alphanumeric (including underscore and period), must be at least one character long, and no longer than 300 characters;
    • Values must be strings no longer than 2048 characters;
    • Keys may not start with the reserved prefix 'evekit_';
    • The initial key-value store for an application may not have more than 200 key-value entries; and
    • An instantiated application may not have more than 300 key-value entries.  Note that any API keys assigned to the instantiated application consume one entry per key.

Other Improvements

There are a few other quality of life changes on the beta site.  For example, accounts are now clearly marked with red text when their XML API key has expired.  Likewise, the account synchronization history view uses a new color scheme to make it clear when certain data was not sync'd because the XML API key doesn't allow access.

1 comment:

  1. Thank you so much for sharing this informative blog. Your technical information is really useful for me. Keep update your blog.


    PHP Training in Chennai