README

[[DEPRECATED]] This repository is no longer maintained. We'll delete this repository & unpublish package at 2017/12/31.

install

add bolster/base-api to yout composer.json

指定可能なバージョンはreleasesを御覧下さい。

{
	"require": {
		"bolster/base-api": "dev-master"
	}
}

サンプル

インスタンス生成

指定可能なオプションは、こちらを御覧下さい。

<?php

$config = [
	'client_id'     => 'YOUR_CLIENT_ID',
	'client_secret' => 'YOUR_CLIENT_SECRET',
	'redirect_uri'  => 'YOUR_REDIRECT_URI',
	'scopes'        => ['read_orders', 'read_users'],
];

$client = new \Bolster\BaseApi\Client($config);

各種APIのクライアントを生成する

各種APIのクライアントを生成するにはapi名(小文字アンダーバーなし)のメソッドが用意されているので、そちらをご利用下さい。
その先のメソッドは各ソースコードを御覧下さい。

$client = new \Bolster\BaseApi\Client($config);

// NOTE: 一度変数に取るとインスタンス生成のコストを削減できる
$oauth_client  = $client->oauth();
$aurhotize_url = $oauth_client->authorize();

// NOTE: 一度にチェインで書くことも可能
$aurhotize_url = $client->oauth()->authorize();

// other methods
// $client->users();
// $client->items();
// $client->categories();
// $client->itemcategories();
// $client->orders();
// $client->savings();

例外

BASE APIからエラーのレスポンスが返ってきたら、それを例外としてスローします。

特別にcatchするであろう例外を子クラスにして、より具体化しています。

ExpiredAccessTokenExceptionもRateLimitExceedExceptionもBaseApiExceptionを継承しているので、
両方ともcatchしたい場合にはBaseApiExceptionをキャッチすれば問題ありません。

ExpiredAccessTokenExceptionは、アクセストークンがセットされていない場合は発生しません。
アクセストークンがセットされており、なおかつ無効ですとレスポンスが返ってきた場合のみ発生します。

<?php
try {

	$client->items()->delete(['item_id' => 100]);

// アクセストークンの有効期限が切れた
} catch(\Base\Api\ExpiredAccessTokenException $e) {
	// アクセストークンをリフレッシュしてリトライ
	$client->oauth()->refresh($_SESSION['refresh_token']);
	$client->items()->delete(['item_id' => 100]);

// 1日もしくは1時間あたりのAPI使用回数制限に達した
} catch(\Base\Api\RateLimitExceedException $e) {
	// 1分待って再送信（NOTE: 日を跨ぐまで回数はリセットされないので実用例ではない）
	sleep(60);
	$client->items()->delete(['item_id' => 100]);

// その他エラー
} catch(\Base\Api\BaseApiException $e) {
	var_dump($e);
}

リダイレクト、コールバックのサンプル

リダイレクト

<?php

$config = [
	'client_id'     => 'YOUR_CLIENT_ID',
	'client_secret' => 'YOUR_CLIENT_SECRET',
	'redirect_uri'  => 'YOUR_REDIRECT_URI',
	'scopes'        => ['read_orders', 'read_users'],
];
$client = new \Bolster\BaseApi\Client($config);

$state  = 'hogehoge';
$client->oauth()->authorize($state);

コールバック

<?php

if(isset($_GET['error'])) {
	throw new RuntimeException($_GET['error']);
}

$config = [
	'client_id'     => 'YOUR_CLIENT_ID',
	'client_secret' => 'YOUR_CLIENT_SECRET',
	'redirect_uri'  => 'YOUR_REDIRECT_URI',
	'scopes'        => ['read_orders', 'read_users'],
];
$client = new \Bolster\BaseApi\Client($config);

$credentials = $client->oauth()->getAccessToken($code);

$_SESSION['access_token'] = $credentials['access_token'];
$_SESSION['refresh_token'] = $credentials['refresh_token'];

$client->setAccessToken($credentials['access_token']);
$me = $client->users()->me();
var_dump($me);

取得、エラー制御

<?php

// @param array $orders
// @return void
function dispatch_all(array $orders) {
	global $client;

	foreach($orders as $order) {
		$detail = $client->orders()->detail($order['unique_key']);

		foreach($detail['order_items'] as $item) {
			$client->orders()->editStatus($item['order_item_id'], 'dispatched');
		}
	}
}

if(isset($_SESSION['access_token'])) {
	throw new RuntimeException('アクセストークンがセットされていません');
}

$config = [
	'client_id'     => 'YOUR_CLIENT_ID',
	'client_secret' => 'YOUR_CLIENT_SECRET',
	'redirect_uri'  => 'YOUR_REDIRECT_URI',
	'scopes'        => ['read_orders', 'read_users'],

	'access_token'  => $_SESSION['access_token'],
];
$client = new \Bolster\BaseApi\Client($config);

// NOTE: 60 * 60 * 24 * 7 = 1 week
$orders = $client->orders()->all([
	'limit' => 100,
	'start_ordered' => date('Y-m-d H:i:s', time() - (60 * 60 * 24 * 7))
]);

var_dump($orders);

try {
	dispatch_all($orders);
} catch(\Base\Api\ExpiredAccessTokenException $e) {
	$client->oauth()->refresh($_SESSION['refresh_token']);
	dispatch_all($orders);
}

BASE APIの仕様雑記

OAuth

authorizeメソッドでscopeを何も設定せず(&scope=で終わった状態で)送信するとデフォルト権限になる

Items

価格(税込み)は、50以上 ~ 500000以下しか登録不可能
在庫数は、0以上 ~ 10000以下

ItemCategories

既に登録されているitem_id, category_idの組み合わせをaddしようとすると不正なcategory_idです。と言われる

bolster / base-api

Maintainers

Details