Sm@rtDBのREST API 共通の仕様

Sm@rtDBのREST APIについて、共通の仕様を記載します。

通信

通信仕様

プロトコル JSON-RPC 、XML-RPC (HTTP)
リクエストURL http(s)://[Sm@rtDBドメイン]/hibiki/rest/2/

Sm@rtDBのREST APIを使用するための前提条件

Sm@rtDBのREST APIを使用するために以下の条件を満たす必要があります。

・Sm@rtDB APサーバとクライアントとの間は、HTTP(S)通信が可能であることが必要です。
・RESTの規約に則り GET,POST,PUT,DELETE のメソッド を使用します。
・以下の表　Acceptヘッダの指定にある仕様のとおりHTTPリクエストヘッダのAcceptヘッダに指定することで、レスポンスデータの形式（JSON形式かXML形式）を選択することができます。

Acceptヘッダの指定

データ形式 HTTPのAcceptヘッダ
XML形式(既定値) application/xml
JSON形式 application/json

リクエストとレスポンス

REST API におけるレスポンスデータはXML形式もしくはJSON形式となります。このデータ形式はREST API使用時にHTMLのAcceptヘッダを指定することで選択することができます。「リクエストの例」および「レスポンスの例」はそれぞれREST APIを使用した際のリクエストおよびレスポンス(XML形式)の例となります。

リクエストの例

  • リクエストURL

（HTTP Method:GET）

https://xxx.dreamarts.co.jp/hibiki/rest/2/binders/13979/views/10001/documents
  • リクエストヘッダ
Accept: text/html,application/xhtml+xml,application/xml;q=0.9, / ;q=0.8

Accept-Encoding: gzip, deflate

Accept-Language: ja,en-us;q=0.7,en;q=0.3

Connection: keep-alive

Cookie: HIBIKI=930509-vJ7ZMdRW; lastSearchType=MY_APP;
JSESSIONID=5732A932B5C87807309EA704AEF0EA14;
__utma=25956072.421028494.1369362508.1369362508.1372147544.2;
__utmz=25956072.1372147544.2.2.utmcsr=google|utmccn=(organic)|utmcmd=organic|utmctr=(not%20provided); WMONID=5ySdyGn5DQY; INSUITE-Enterprise_user_lang=ja;
INSUITE-Enterprise=1000484.BuzJbYRfVx5Os
Host: xxx.dreamarts.co.jp
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:17.0)

レスポンスの例

  • レスポンスヘッダ
Connection: Keep-Alive
Content-Type: application/xml
Date: Wed, 31 Jul 2013 00:18:41 GMT
Keep-Alive: timeout=10, max=100
Set-Cookie: HIBIKI=930509-vJ7ZMdRW; Path=/hibiki/
Transfer-Encoding: chunked
Vary: User-Agent
  • レスポンスデータ
<documents>
<document>
<id>2</id>
<created>
<id>1000039</id>
<key>taro</key>
<name>ドリーム 太郎</name>
<type>1</type>
<email>taro@dreamarts.co.jp</email>
<primary>2000380</primary>
</created>
<created_at>2013-05-03T09:12:54+09:00</created_at>
<updated>
<id>1000039</id>
<key>taro</key>
<name>ドリーム 太郎</name>
<type>1</type>
<email>taro@dreamarts.co.jp</email>
<primary>2000380</primary>
</updated>
<updated_at>2013-05-08T19:19:40+09:00</updated_at>
<item>
<id>10008</id>
<key>PRIVILEGE_KEY</key>
<type>Text</type>
<value>CDS_IPAD_USER</value>
</item>
<item>
<id>10004</id>
<key>PRIVILEGE_NAME</key>
<type>Text</type>
<value>iPad利用可能ユーザ</value>
</item>
<item>
<id>10005</id>
<key>PRIVILEGE_ACCOUNT</key>
<type>AccountList</type>
<value>[2000018]</value>
</item>
</document>
<document>
<id>1</id>
<created>
<id>1000039</id>
<key>taro</key><name>ドリーム 太郎</name>
<type>1</type>
<email>taro@dreamarts.co.jp</email>
<primary>2000380</primary>
</created>
<created_at>2013-05-03T09:12:54+09:00</created_at>
<updated>
<id>1000039</id>
<key>taro</key>
<name>ドリーム 太郎</name>
<type>1</type>
<email>taro@dreamarts.co.jp</email>
<primary>2000380</primary>
</updated>
<updated_at>2013-05-08T19:19:40+09:00</updated_at>
<item>
<id>10008</id>
<key>PRIVILEGE_KEY</key>
<type>Text</type>
<value>CDS_ADMIN</value>
</item>
<item>
<id>10004</id>
<key>PRIVILEGE_NAME</key>
<type>Text</type>
<value>iPad向けコンテンツ配信システム管理者</value>
</item>
<item>
<id>10005</id>
<key>PRIVILEGE_ACCOUNT</key>
<type>AccountList</type>
<value>[2000000]</value>
</item>
</document>
<totalCount>537</totalCount>
</documents>

Sm@rtDBのREST APIの利用例

Sm@rtDBのREST API を用いてSm@rtDB 内の各種データにアクセスするためには、Basic認証もしくはCookie認証を用いてSm@rtDB へログインする必要があります（Proxy経由でProxy側のBasic認証を使う場合はCookie認証のみ利用可）。認証後、必要なデータ取得処理・更新処理を行うのがREST APIの典型的な利用方法です。
Sm@rtDB の文書一覧・詳細情報を取得する場合のAPI呼び出し例はSm@rtDBのREST API利用フローのようになります。（認証処理については、後述の「セッション処理フロー図」も合わせて参照してください）。

Sm@rtDBのREST API利用フロー(Sm@rtDBの文書一覧を取得し、文書を更新する場合)

application

● 説明
・この例（Sm@rtDBのREST API利用フロー）におけるクライアントアプリケーションの動作の概要は以下となります。

  1. セッション情報を取得し、文書一覧を画面表示します。（①～④）
  2. ユーザが表示された文書一覧から更新する文書を選択すると、その文書の詳細画面を表示します。（⑤）
  3. ユーザが文書の更新情報を入力し、送信することで文書の更新を行います。（⑥～⑦）

● 備考
①' で返却されるデータには、次回以降のAPI呼び出しで必要となるCSRFトークンが含まれます。図上での記載はありませんが、②以降のリクエストのパラメーターとして、①'で取得したCSRFトークンをセットしています。

セッション処理フロー

エラーコード一覧

Sm@rtDBのREST　APIでエラーが発生した場合、下記のHTTPレスポンスコードが返却されます。

エラーコード一覧

エラーコード エラー内容
400 Bad request 不正なリクエスト、CSRFトークンチェックに失敗している
401 Unauthorized 認証処理に失敗している（ログインに失敗 しているor ログインしていない）
403 RESTful service is disabled RESTサービスが無効になっている
404 Not Found 該当するリソース(session,binder,view,document) が見つからない
406 NotAcceptable 全文検索でALL、ONE以外の不正なマッチモードを指定されている
500 Internal Server Error その他サーバー側のエラーが発生している
  • エラーの例(XML形式)
<error>
<code>401</code>
<message>Unauthorized</message>
</error>
  • エラーの例(json形式)
{"code":401,"message":"Unauthorized"}