スパイラル サポートサイト

powered by SPIRAL PLACE®

HOME > 機能 > スパイラルAPIの仕様

スパイラルAPI仕様





目次

1.アカウント内API
2.APIトークンとAPIトークンシークレット
3.スパイラルAPI共通仕様

1.アカウント内API

アカウント内にて内部呼出しでAPIを利用するには、SPIRALの管理画面からアカウント内APIの設定を「ON」にしていただきます。
アカウント内APIが「ON」の場合、アカウント内のPHPに対応したページであればトークンとトークンシークレットを発行および記載をせずにAPIを動作させることが可能です。
スパイラルアカウント内からAPIをリクエストする場合はアカウント内APIを利用することを推奨します。
内部呼出しに関する詳細は、こちらを参照ください。
アカウント内APIに関する設定方法は、こちらを参照ください。

2.APIトークンとAPIトークンシークレット

外部環境や他のスパイラルアカウントなどから外部呼出しでAPIリクエストを実行する場合は、あらかじめSPIRALの管理画面上でトークンを発行する必要があります。
トークンとトークンシークレットの組み合わせは複数発行することが出来ます。
また、APIタイプ別に利用制限をかけることも可能ですので、必要に応じて使い分けるようにして下さい。
外部呼出しやAPIタイプに関する詳細はこちらを参照ください。

APIトークン
APIトークンは、APIを利用する際に必要なユーザを特定するための文字列で、 通信のパラメータとして必ず送信する必要があります。

APIトークンシークレット
APIトークンのシークレットは、リクエスト時、通信データのメッセージ認証コード(HMAC)を生成するために使用し、暗号で例えると公開鍵の役割を果たします。



※パラメータは、利用するAPI機能により異なるデータとなります。 詳細は各APIメソッドのリファレンスを参照してください。

3.スパイラルAPI共通仕様

通信方式
HTTPS(メソッド:POST)

データフォーマット
リクエスト、レスポンスともにJSON形式

文字コード
UTF-8

認証
すべてのAPI(locator/apiserverは除く)のリクエストには、APIトークンおよびAPIトークンシークレットを用いた認証

URL
ご利用のアカウントによってAPIを実行する際に利用するURLが異なってきます。どのURLを使えばよいかは管理画面からご確認いただけます。※機能詳細ページ参照
また、ロケーターAPIを利用して取得することも可能です。

スパイラルのアカウントによって、APIリクエスト先のURLは異なる場合があります。
locator(ロケータ)を使うと、APIリクエスト先URLをハードコーディングする必要がありませんので、アプリセンター経由で他アカウントへアプリを渡すことを想定している場合などでは、locator(ロケータ)を使ってプログラムを作成されることをおすすめします。

locator(ロケータ)について詳しくは、下記をご参照ください。
* locator(ロケータ)
* スパイラルAPI サンプルプログラムロケータ

APIのリクエスト方法
リクエスト時のHTTPヘッダとしては、Content-Typeと利用したいAPIメソッドをX-SPIRAL-APIに指定します。

Content- Type: application/json; charset=UTF- 8
X- SPIRAL- API: area/login/request

上記の例では、 area/login 部分がAPIメソッドに相当しており、マイエリア機能(area)のログインメソッド(login)をリクエストしています。

リクエストのボディには各メソッドに応じたパラメータをJSONデータとしてPOSTするようにします。なお、JSONデータにはAPIトークン・パスキー・APIトークンシークレットを用いた署名の3つのパラメータを必ず含める必要があります。

{
'spiral_api_token': '0123456......abcdef',
'passkey': '1256342400',
'signature': '987abc......def012',
(略)
}

パラメータ説明文字種長
spiral_api_tokenSPIRALの管理画面で発行したAPIトークン半角英数字
passkeyAPIリクエスト時刻のエポック秒int
signaturespiral_api_tokenとpasskeyを&でつなげた文字列をAPIトークンシークレットを用いて
hmac-sha1によりハッシュ化して生成された署名
半角英数字

なお、署名の有効期間はpasskeyに指定されたエポック秒から15分間となりますのでご注意下さい。

各メソッドに合わせて正しいJSONフォーマットで上記のルールに従ってAPIをリクエストすれば、レスポンスがJSONデータで返ってきます。以下に実際のリクエスト・レスポンスの例を示します。

リクエスト


POST /api/service/ HTTP/1.1
X-SPIRAL-API: area/login/request
Content-Type: application/json; charset=UTF-8
 
{'spiral_api_token':'00000000aaaaaaaaaabbbbbbbbbbccccccccccdddddddddddeee','passkey':'1366375090','signature':'0000ffc6e281f9e128538e1d05b947405421b99c','my_area_title':'my_area01','id':'suzuki.taro','password':'hogehoge'}

レスポンス


200 OK
Date:  Fri, 19 Apr 2013 12:38:26 GMT
Server:  Apache
X-SPIRAL-API:  area/login/response
Keep-Alive:  timeout=15, max=100
Connection:  Keep-Alive
Transfer-Encoding:  chunked
Content-Type:  application/json;charset=UTF-8
 
{"message":"OK","jsessionid":"000000009B838604C8A49DE200000000","code":"0","url":"https://beta.smp.ne.jp/area/servlet/area.MyPageBundle;jsessionid=000000009B838604C8A49DE200000000?MyPageID=999efb02_qh7milh7m2l0000"}

ファイル型などバイナリデータを含む場合
通常のAPIのリクエストでは上記のようなシングルパートのリクエスト方法を使っていただければ問題なく動作します。しかしながらdata/insertやcustom_module/uploadなどのリクエストにバイナリデータを含むAPIメソッドを実行する際には、以下のようなフォーマットを使ってAPIをリクエストする必要があります。

  • マルチパート形式を必ず利用
  • 改行コードはCRLF
  • ファイル型フィールドのタイトルはJSONでの指定は不要

なお、マルチパート形式とは以下の様なものになります。

HTTPヘッダ

Content-Type: multipart/form-data; boundary="xxxxxxxxxx_MULTIPART_BOUNDARY"
X-SPIRAL-API: 機能名/メソッド名/request

マルチパートのそれぞれのデータの境界を示すために必要となる任意のboundary文字列(この例では xxxxxxxxxx_MULTIPART_BOUNDARY)を決めて、上記のようにヘッダに指定します。

HTTPボディ

1|--xxxxxxxxxx_MULTIPART_BOUNDARY
2|Content-Type: application/json; charset="UTF-8"
3|Content-Disposition: form-data; name="json"
4|
5|{
6| 'spiral_api_token': '0123456......abcdef',
7| ・・・
8|}
9|
10|--xxxxxxxxxx_MULTIPART_BOUNDARY
11|Content-Type: application/octet-stream;
12|Content-Disposition: form-data; name="file01"; filename="ファイル01.png"
13|
14|(ファイルのバイナリデータ)
15|
16|--xxxxxxxxxx_MULTIPART_BOUNDARY--

1行目や10行目のように各パートの先頭行に--に続けてboundary文字列を指定します。2行目〜9行目がJSONパート(そのうちの5〜8行目がJSONデータ)で、11行目〜15行目がファイルパートになります。12行目では、nameにフィールドタイトルを、filenameにファイル名をそれぞれ指定しています。

APIエラー時の対応
APIレスポンスのcodeプロパティが0の場合は正常終了ですが、0以外の場合は何らかのエラーが発生しています。各々のエラー詳細については、エラーコード表を参照してください。

正常終了時の応答サンプル(JSON)

{
"message": "OK",
"count": "2",
"data": [
["suzuki@example.com", "テキストエリア"],
["yamada@example.com", "テキストエリア2"]
],
"code": "0",
"header": ["メールアドレス", "テキストエリア"]
}

エラー終了時の応答サンプル(JSON)

{
"message": "Requested data not found",
"code": "203"
}

エラー判定を行うサンプルコード(PHP)

<?php
/ / ・・・中略・・・
$response = curl_multi_getcontent($curl);
curl_close($curl);
$result = json_decode($response, true);
($result["code"] == 0) or die("API呼び出しでエラー発生\n");
/ / ・・・中略・・・
?>

最終更新日:2019/7/31