README

Admitad API client

this thing is more usable than the official piece of crap. this api client can be used without framework, optionally added laravel service provider to speed up bootstrapping.

Installation

composer require yuriitatur/admitad-api

Usage

framework-agnostic way

Build a Guzzle client via ApiClientBuilder, wire in OAuth2, then pass it to AdmitadApi:

use GuzzleHttp\HandlerStack;
use YuriiTatur\ApiClient\ApiClientBuilder;
use YuriiTatur\Admitad\Services\AdmitadApi;
use kamermans\OAuth2\OAuth2Middleware;
use kamermans\OAuth2\GrantType\ClientCredentials;
use kamermans\OAuth2\GrantType\RefreshToken;
use kamermans\OAuth2\Persistence\FileTokenPersistence;

$oauthClient = (new ApiClientBuilder)
    ->withBaseUri('https://api.admitad.com/token/')
    ->build();

$config = [
    'client_id'     => 'my_client_id',
    'client_secret' => 'my_client_secret',
    'scope'         => ['private_data'],
];
$persistence = new FileTokenPersistence('/tmp/admitad_token.json');

$oauth = new OAuth2Middleware(
    new ClientCredentials($oauthClient->getClient(), $config),
    new RefreshToken($oauthClient->getClient(), $config),
);
$oauth->setTokenPersistence($persistence);

$builder = (new ApiClientBuilder)
    ->withBaseUri('https://api.admitad.com')
    ->withLogger($myLogger); // optional, PSR-3

$builder->getStackBuilder()->withCustomMiddleware($oauth, 'oauth');

$guzzleClient = $builder->build()->getClient();
$api = new AdmitadApi($guzzleClient, $myLogger); // logger optional

methods

Every API method has a sync and an async variant. The sync variant blocks until the response arrives and returns the decoded array. The async variant returns a PromiseInterface for concurrent requests.

// sync
$referrals = $api->getReferrals(['limit' => 50]);

// async — fire several requests in parallel
$promises = [
    'me'       => $api->getMeAsync(),
    'balance'  => $api->getBalanceAsync(),
    'referrals' => $api->getReferralsAsync(['limit' => 50]),
];
$results = \GuzzleHttp\Promise\Utils::unwrap($promises);

Look at the @method docblock on AdmitadApi for the full list of available methods and their signatures.

Lists

To iterate over all records without worrying about pagination, use createList:

$iterator = $api->createList()->getNews([]); // no API call yet
foreach ($iterator as $article) {
    // fetches next batch of 500 automatically when needed
}

Laravel

Configuration

Publish the config:

php artisan vendor:publish --tag=admitad-config

Add credentials to config/services.php under the admitad key:

'admitad' => [
 'client_id'     => env('ADMITAD_KEY'),
 'client_secret' => env('ADMITAD_SECRET'),
 'redirect'      => env('ADMITAD_REDIRECT_URI'),
],

Adjust config/admitad.php to your needs:

'success_redirect' => '/dashboard', // where to redirect after OAuth login
'route_prefix'     => '/admitad',   // prefix for the two OAuth routes
'scopes'           => [
 'private_data',
 'private_data_email',
],

Resolving the client

app(AdmitadApi::class);
// or
app('admitad-api');

Token persistence

By default the Laravel cache is used; the cache key is derived from the configured scopes. To swap the implementation:

// in your ServiceProvider
$this->app->singleton(TokenPersistenceInterface::class, MyCustomPersistence::class);

Route middleware

Protect routes from access without a valid Admitad token:

Route::middleware('admitad_auth')->group(function () {
    // ...
});

Unauthenticated requests are redirected to the Admitad OAuth login page. JSON requests receive a 403 with a Location header instead.

yuriitatur / admitad-api

Maintainers

Package info

Statistics

Security