API概要｜INTER-STREAMサポート

印刷する

はじめに

概要

INTER-STREAM APIは、他のアプリケーションとINTER-STREAMとの統合/相互作用を可能にするように設計されています。

API認証情報の管理

APIを使用する前に、INTER-STREAMでクレデンシャル（認証情報）を作成します。
クレデンシャルはいくつでも作成できます。

APIクレデンシャルの作成/編集
1. [API]セクションに移動します。

2. 新たにAPI認証情報を作成するには[+新規クレデンシャル情報]ボタンをクリックします。
既存のAPI認証情報を編集するには、対応するアイコンをクリックします。

作成のインターフェースと編集のインターフェースは非常に似ていますが、編集のインターフェースには追加情報が表示されます。

3. 新規認証情報を入力します。

タイトル：参照用のわかりやすいタイトルを入力してください。
リクエスト有効期限（秒）：リクエストが生成された日からそれを受け付ける最大時間を指定します。
許可リファラ（参照元）：（オプション）Webページ（Javascriptなど）で使用するために認証情報が生成されている場合は、許可されているリファラードメインをカンマ区切りで指定できます。
認証情報が参照元によって制限されるように設定されているが元のサーバから参照元情報が提供されていない場合はリストに「空白("blank")」も追加します。そうでないとそのリクエストは破棄されます。
例）"mydomain.com"と"blank"からのリクエストを許可したい場合は"mydomain.com,www.mydomain.com,blank"と入力します。
統計を有効化：有効にするとシステムは認証情報の統計を登録します。

4. リクエスト権限
認証情報に付与する一般および特定の権限を選択します。
特定の権限により、APIの一部のセクションで一般のものとは異なる権限を持つことができます。

5. 編集が終了したら、[保存する]ボタンをクリックします。

認証情報を保存して作成した後、システムは「キーID」と「シークレットキー（共有）」を生成します。

キーID：この認証情報によるリクエストを識別する為に、このIDが公に使用されます。
シークレットキー（共有）：検証署名（ハッシュ）の生成に使用されます。従ってこれは公開するべきではありません。

注：キーIDとシークレットキーは認証情報作成時に一度だけ生成されます。

APIベースURL

API URLはINTER-STREAMのベースURLに"/api.php"を続けたものになります。

例）
INTER-STREAMのURLがhttps://www.interstreamdomain.com/の場合、全てのAPIリクエストはhttps://www.interstreamdomain.com/api.phpに送信する必要があります（httpsプロトコル推奨）。

注：リクエストは全て"GET"及び"POST"を使用して実行されます。

セキュリティ

必須情報

APIに送信するリクエストごとに、リクエストURLに次のGET変数が必要です。

変数	値	説明
timestamp	UNIX timestamp	Unix UTCタイムスタンプ
salt	random string	リクエストごとにランダムに生成された文字列
key	KEY ID	認証情報の「キーID」
signature	base64+HMAC SHA256	生成されたハッシュ（下記参照）注：認証情報未署名のリクエストを許可している場合は、ハッシュは必要ありません。

例）

https://....../api.php?go=clips&do=get&iq=5&timestamp=1427282901&salt=1e05489590729c06363f6ddfff5c99ff&key=57a3f24f8abd71cdde44c3e3fb675bc7&signature=Y98d2tB3oMPKwIJ8PJEZXG72Nd1zqn27yUCUsP8phHs%3D

認証：検証署名（ハッシュ）

未署名のリクエストを許可した場合を除き、すべてのAPIリクエストに検証署名（ハッシュ）が必要です。ハッシュは「シークレットキー（共有）」と共にbase64 + HMAC SHA256を使用して"salt"と"timestamp"の連結から生成されます。

PHPの例）

$API_KEY_SECRET = "credential key secret";
$salt = md5(mt_rand());
$timestamp = time();
$signature = urlencode(base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_KEY_SECRET, true)));

他の言語で作業している場合は、HMAC SHA256を使用してさまざまな言語でbase64ハッシュを作成する例を参照ください。

注意事項

1. リクエストは、APIリクエストURLにHTTPSプロトコルを使用する事により保護されます。INTER-STREAMのサーバーに有効なSSL証明書が設定されていなければなりません。
これは、ユーザー関連のリクエストを処理するときに特に重要となります。

2. Web上では、フロントエンドアプリケーションを使用してAPIにリクエストを送信しないようにしてください。
例えば、情報を取得するためにJavascriptを使用する必要がある場合は、Javascriptから直接リクエストを実行しない代わりに、バックエンド（サーバー側）アプリケーションを使用してAPIにリクエストを送信してから、適切な結果をJavascriptにのみ送信することができます。
また、APIシークレットキー（共有）は一般にアクセス可能なので、JavaScriptに含める事はしないでください。

3. APIシークレットキー（共有）は絶対に公開しないでください。
モバイルアプリ等でフロントエンドアプリケーションを使用してAPIへのリクエストを送信する場合、シークレットキーが本当に保護されていることを確認するか、バックエンドアプリケーションを使用してリクエストをAPIに送信し、その結果をアプリに送信します。
また、常にHTTPSプロトコルを使用する事でアプリからの機密情報の管理は回避されます。

戻りのフォーマット

デフォルトでは、APIは結果をJSON形式で返しますが、リクエストURLにGET変数"format"と"callback"を追加することで、コールバックありのJSONP形式での戻りを確認できます。

例）

https://....../api.php?go=clips&do=get&iq=5&key=57a3f....&format=jsonp&callback=myfunction

キャッシュ

システムはパフォーマンス向上のために"GET"リクエストをキャッシュします。
キャッシュされていない結果が必要な場合は、リクエストURLにGET変数"cache"を追加します。

注：キャッシュの有効期間を調整するには、[一般設定＞設定＞キャッシュ]から「APIキャッシュ期限」の値を変更します。

例）

https://....../api.php?go=clips&do=get&iq=5&key=57a3f....&cache=0

重要
api/temp/cacheディレクトリに書き込み権限があることを確認してください。これは診断ツールで確認可能です。

一般的なエラーメッセージ

以下は、任意のリクエストによって返される可能性があるエラーです。

・REQUEST_ERROR | Missing signature
ハッシュが見つかりません。

・REQUEST_ERROR | Invalid request (missing required info)
リクエストされた情報（GET変数）の全部または一部がURL上にに存在しません。

・REQUEST_ERROR | Invalid API Key ID
指定されたAPIキーIDがシステムに見つかりませんでした。

・REQUEST_ERROR | Invalid request (time out)
認証情報で指定されている「リクエストの有効期限」が切れています。

・REQUEST_ERROR | Permission error (GET, MODIFY, CREATE, DELETE)
認証情報にリクエストの実行権限がありません。

・REQUEST_ERROR | Wrong signature
ハッシュが一致しません。

・REQUEST_ERROR | Not allowed
認証情報は参照元から送信されたリクエストを許可していません。