Web API client for EVE-Online - ESI API

Originally written by Exodus4D, but has been recreated to support open-source forks since the oriiginal client is no longer maintained.

This Web API client library is used by Pathfinder and handles all ESI API requests.
Additional APIs can easily be added and can be used side by side with their own configuration. Included clients:

• CCP ESI API client: Esi.php
• CCP SSO API client: Sso.php
• GitHub basic API client: GitHub.php
• eve-scout "Thera" API client: EveScout.php

This Web client is build on Guzzle and makes much use of the build in Middleware concept in Guzzle.

Installation:

Use Composer for installation. In composer.json require section add:

{
  "require": {
    "php-64bit": ">=8.0",
    "mbroekman/pathfinder_esi": "v2.1.5"
  }
}

Pathfinder: This web API client lib is automatically installed through Composer along with all other required dependencies for the Pathfinder project. (→ see composer.json).

A newer version of Pathfinder may require a newer version of this repository as well. So running composer install after a Pathfinder update will upgrade/install a newer ESI client. Check Pathfinder release notes for further information.

Use Client:

1. Init client:

// New web client instance for GitHub API [→ Github() implements ApiInterface()]
$client = new \Exodus4D\ESI\Client\GitHub\GitHub('https://api.github.com');

// configure client [→ check ApiInterface() for methods]
$client->setTimeout(3);                     // Timeout of the request (seconds)
$client->setUserAgent('My Example App');    // User-Agent Header (string)
$client->setDecodeContent('gzip, deflate'); // Accept-Encoding Header
$client->setDebugLevel(3);                  // Debug level [0-3]
$client->setNewLog(function() : \Closure {  // Callback for new LogInterface
   return function(string $action, string $level = 'warning') : logging\LogInterface {
       $log = new logging\ApiLog($action, $level);
       $log->addHandler('stream', 'json', './logs/requests.log');
       return $log;
   };
});

// Loggable $requests (e.g. HTTP 5xx resp.) will not get logged if return false;
$client->setIsLoggable(function() : \Closure {
    return function(RequestInterface $request) use ($f3) : bool {
        return true;
    };
});

$client->setLogStats(true);                 // add some cURL status information (e.g. transferTime) to logged responses

$client->setLogCache(true);                 // add (local) cache info (e.g. response data cached) to logged requests
$client->setLogAllStatus(false);            // log all requests regardless of response HTTP status code
$client->setLogRequestHeaders(false);       // add request HTTP headers to loggable requests
$client->setLogResponseHeaders(false);      // add response HTTP headers to loggable requests
$client->setLogFile('requests');            // log file name for request/response errors
$client->setRetryLogFile('retry_requests'); // log file for requests errors due to max request retry exceeds

$client->setCacheDebug(true);               // add debug HTTP Header with local cache status information (HIT/MISS)
$client->setCachePool(function() : \Closure {
    return function() : ?CacheItemPoolInterface {
        $client = new \Redis();             // Cache backend used accross the web client
        $client->connect('localhost', 6379);
          
        // → more PSR-6 compatible adapters at www.php-cache.com (e.g. Filesystem, Array,…)
        $poolRedis = new RedisCachePool($client);
        $cachePool = new NamespacedCachePool($poolRedis, 'myCachePoolName');
        return $cachePool;                  // This can be any PSR-6 compatible instance of CacheItemPoolInterface()
    };
});

2. Send requests

// get all releases from GitHub for a repo
$releases = $client->send('getProjectReleases', 'mbroekman/pathfinder');
// … more requests here

Concept

Guzzle Middlewares :

Middlewares classes are small functions that hook into the "request → response" chain in Guzzle.

• A Middleware can manipulate the request and response objects
• Each Middleware is dedicated to handles its own task.
• There are Middlewares for "logging", "caching",… pre-configured.
• Each Middleware has its own set of config options that can be set through the $client->.
• All configured Middlewares are pushed into a HandlerStack() that gets resolved for each request.
• The order in the HandlerStack() is essential!

Guzzle HandlerStack :

This flowchart shows all Middlewares used by ESI.php API client. Each request to ESI API invokes all Middlewares in the following order:

Before request

GuzzleJsonMiddleware → GuzzleLogMiddleware → GuzzleCacheMiddleware → GuzzleCcpLogMiddleware → GuzzleRetryMiddleware → GuzzleCcpErrorLimitMiddleware

After response (→ reverse order!)

GuzzleCcpErrorLimitMiddleware → GuzzleRetryMiddleware → GuzzleCcpLogMiddleware → GuzzleCacheMiddleware → GuzzleLogMiddleware → GuzzleJsonMiddleware

Default Middlewares:

JSON

Requests with expected JSON encoded response data have GuzzleJsonMiddleware in HandlerStack.
This adds Accept: application/json Header to request and response body gets wrapped into JsonStream.

$client->setAcceptType('json');

Caching

A client instance should be set up with a PSR-6 compatible cache pool where persistent data can be stored. Valid response data can be cached by its Cache-Expire HTTP Header. GuzzleCacheMiddleware also handle Etag Headers. Other Middlewares can also access the cache pool for their needs. E.g. GuzzleLogMiddleware can throttle error logging by using the cache pool for error counts,…

→ See: $client->setCachePool();

Hint: Check out www.php-cache.com for PSR-6 compatible cache pools.

Logging

Errors (or other events) during (~before) a request can be logged (e.g. connect errors, or 4xx/5xx responses).
The primary Middleware for logging is GuzzleLogMiddleware
Other Middlewares also have access to the global new log callback and implement their own logs.

$client->setNewLog();

Retry

Requests result in an expected error (timeouts, cURL connect errors,… ) will be retried [default: 2 times → configurable!]. Check out GuzzleRetryMiddleware for more information.

CCP ESI exclusive Middlewares:

Each web client has its own stack of Middlewares. These Middlewares are exclusive for requests to CCP´s ESI API:

GuzzleCcpLogMiddleware

Requests to endpoints that return a warning HTTP Header for deprecated /or legacy marked endpoints get logged into separate log files.

GuzzleCcpErrorLimitMiddleware

Failed ESI requests (4xx/5xx status code) implement the concept of "Error Rate Limiting" (→ blog: ESI error rate limiting). In case a request failed multiple times in a period, this Middleware keeps track of logging this and pre-block requests (e.g. for a user) an endpoint before CCP actual does.

Content Encoding

The default configuration for "decode-content" is true → decode "gzip" or "deflate" responses.
Most APIs will only send compressed response data if Accept-Encoding HTTP Header found in request. A string value will add this Header and response data gets decoded.

$client->setDecodeContent('gzip, deflate');

Bug report

Issues can be tracked here: https://github.com/mbroekman/pathfinder/issues

Development

If you are a developer you might have both repositories (mbroekman/pathfinder, mbroekman/pathfinder_esi ) checked out locally.

In this case you probably want to test changes in your local mbroekman/pathfinder_esi repo using your local mbroekman/pathfinder installation.

1. Clone/Checkout both repositories local next to each other
2. Make your changes in your pathfinder_esi repo and commit changes (no push!)
3. Switch to your pathfinder repo
4. Run Composer with composer-dev.json, which installs pathfinder_esi from your local repository.
   • Unix: $set COMPOSER=composer-dev.json && composer update
   • Windows (PowerShell): $env:COMPOSER="composer-dev.json"; composer update --no-suggest