はじめに

スパイラルAPIを使うと、SPIRALに設定済みのWebコンポーネントやDBにアクセスして情報の出し入れや、メール配信操作、マイエリアによる認証処理などを利用することが出来ます。

スパイラルAPIを利用するには、あらかじめAPIトークンおよびAPIトークンシークレットの発行が必要になります。詳しくはAPIトークン・トークンシークレットを参照して下さい。

API共通仕様

通信方式

HTTPS (メソッド: POST)

データフォーマット

リクエスト、レスポンスともにJSON形式となります。 (文字コード: UTF-8)

認証

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

URL(エンドポイント)

ご利用のアカウントによってAPIを実行する際に利用するURL(エンドポイント)が異なってきます。どのエンドポイントを使えばよいかを確認するためのロケータAPIを用意していますので、それを使ってエンドポイントのURLを特定する必要があります。詳しくは locator(ロケータ) を参照してください。

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_token SPIRALの管理画面で発行したAPIトークン 半角英数字
passkey APIリクエスト時刻のエポック秒 int
signature spiral_api_tokenpasskey&でつなげた文字列を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/insertcustom_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ボディ
--xxxxxxxxxx_MULTIPART_BOUNDARY
Content-Type: application/json; charset="UTF-8"
Content-Disposition: form-data; name="json"

{
    'spiral_api_token': '0123456......abcdef',
    ・・・
}

--xxxxxxxxxx_MULTIPART_BOUNDARY
Content-Type: application/octet-stream;
Content-Disposition: form-data; name="file01"; filename="ファイル01.png"

(ファイルのバイナリデータ)

--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");

    // ・・・中略・・・
?>