第13章 REST API

REST API は、設定可能なメディアタイプによって定義される形式にデータを保存するキャッシュを公開します。

以下の XML スニペットは、キーと値のメディアタイプを定義する設定例になります。

<cache>
   <encoding>
      <key media-type="application/x-java-object; type=java.lang.Integer"/>
      <value media-type="application/xml; charset=UTF-8"/>
   </encoding>
</cache>

デフォルトのメディアタイプはキーと値の両方で application/octet-stream であり、以下の例外があります。

Red Hat JBoss Data Grid では、クライアントは異なる形式のデータを読み書きでき、自動的に形式を変換できます。

JBoss Data Grid は、相互に交換可能なデータ形式を複数サポートします。

JBoss Data Grid は、前述のリストにあるデータ形式が変換前および変換後となるデータ形式もサポートします。

さらに、JBoss Data Grid は application/x-protostream と application/json 間の変換をサポートします。

Red Hat JBoss Data Grid REST API への呼び出しは、以下を記述するヘッダーを提供できます。

JBoss Data Grid は、値に適用される HTTP/1.1 Content-Type および Accept ヘッダーと、キーの Key-Content-Type ヘッダーをサポートします。

Red Hat JBoss Data Grid の REST サーバーは、Accept ヘッダーの RFC-2616 仕様に準拠し、サポートされる変換を基にして適切なメディアタイプをネゴシエートします。

たとえば、キャッシュからデータを読み取るため、クライアントが呼び出しで以下のヘッダーを送信するとします。

Accept: text/plain;q=0.7, application/json;q=0.8, */*;q=0.6

この場合、ネゴシエーション中に JBoss Data Grid はメディアタイプの優先度が最も高い (0.8) JSON 形式を優先します。サーバーが JSON 形式をサポートしない場合、次に優先度が高い (0.7) text/plain が優先されます。

サーバーが JSON および text/plain メディアタイプをサポートしない場合は、/ が優先されます。これは、キャッシュ設定を基にした適切なメディアタイプを意味します。

ネゴシエーションの終了後、サーバーは選択したメディアタイプを継続して操作に使用します。操作中にエラーが発生した場合、サーバーは他のメディアタイプの使用を試みません。

REST API へのほとんどの呼び出しは URL にキーが含まれています。これらの呼び出しを処理するとき、Red Hat JBoss Data Grid はデフォルトで java.lang.String をキーのコンテンツタイプとして使用します。しかし、Key-Content-Type ヘッダーを使用して別のコンテンツタイプをキーに指定することもできます。

以下のメソッドでデータをキャッシュに追加します。

PUT および POST メソッドで REST API を呼び出すとき、リクエストのボディーにはデータが含まれます。

提供された URL フォームからの PUT 要求により、提供されたキーを使用して要求本文からのペイロードがターゲットキャッシュに配置されます。このタスクが正常に完了するには、ターゲットキャッシュがサーバーに存在する必要があります。

例として、以下の URL では値 hr がキャッシュ名で payRoll%2F3 がキーになります。値 %2F は、/ 文字がキーで使用されたことを示しています。

http://someserver/rest/hr/payRoll%2F3

既存のデータが置き換えられ、必要な場合は Time-To-Live および Last-Modified の値が更新されます。

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

提供された URL フォームからの POST メソッドにより、提供されたキーを使用して (要求本文からの) ペイロードがターゲットキャッシュに配置されます。ただし、POST メソッドでは、値がキャッシュ/キーに存在する場合に、HTTP CONFLICT ステータスが返され、内容が更新されません。

timeToLiveSeconds ヘッダーおよび maxIdleTimeSeconds ヘッダーには以下の組み合わせを設定できます。

以下のメソッドでキャッシュからデータを取得します。

GET メソッドは、指定の cacheName に存在し、関連するキーに一致するデータを応答の本文として返します。Content-Type ヘッダーは、データのタイプを提供します。ブラウザーはキャッシュに直接アクセスできます。

各エントリーに対して、要求された URL でデータの状態を示す Last-Modified ヘッダーとともに一意のエンティティータグ (ETag) が返されます。ETag により、ブラウザー (および他のクライアント) は、(帯域幅を節約するために) データが変更された場合のみデータを要求できます。ETag は、HTTP 標準の一部であり、Red Hat JBoss Data Grid によりサポートされます。

格納されたコンテンツのタイプは、返されたタイプです。例として、String が格納された場合は、文字列が返されます。シリアライズされた形式で格納されたオブジェクトは、手動でデシリアライズする必要があります。

クエリーに extended パラメーターを追加すると、追加の情報が返されます。例を以下に示します。

GET /{cacheName}/{cacheKey}?extended

以下のカスタムヘッダーが返されます。

HEAD メソッドは、GET メソッドと同様に動作しますが、コンテンツを返しません (ヘッダーフィールドが返されます)。

GET メソッドは、キャッシュに存在するキーのリストを返すことができます。返されるキーのリストは応答のボディーにあります。

Accept ヘッダーは次のように応答をフォーマットできます。

キャッシュが分散されている場合、リクエストを処理するノードが所有するキーのみが返されます。すべてのキーを返すには、次のようにクエリーに global パラメータを追加します。

GET /{cacheName}?global

HTTP DELETE メソッドで Red Hat JBoss Data Grid からデータを削除します。

DELETE メソッドは以下を行うことができます。

DELETE メソッドがこのコンテキスト (DELETE /{cacheName}/{cacheKey}) で使用された場合、指定のキーのキャッシュからキー/値を削除します。

このコンテキスト (DELETE /{cacheName}) では、DELETE メソッドが名前付きキャッシュ内のすべてのエントリーを削除します。正常な DELETE 操作後に、HTTP ステータスコード 200 が返されます。

performAsync ヘッダーの値を true に設定して、削除操作がバックグラウンドで続行される状態で値がすぐに返されるようにします。

JBoss Data Grid はプロトコルバッファーを使用して、データを効率的にバイナリー形式でキャッシュに保存し、クエリーを公開してコンテンツを JSON 形式で読み書きできるようにします。

Protobuf でエンコードされたエントリーを保存するには、キャッシュを application/x-protostream メディアタイプで設定する必要があります。設定後、JBoss Data Grid は自動的に JSON を Protobuf に変換します。

キャッシュがインデックス化されている場合、設定を何も実行する必要はありません。デフォルトでは、インデックス化されたキャッシュはエントリーを application/x-protostream メディアタイプで保存します。

しかし、キャッシュがインデックス化されていない場合、以下の例のようにキーと値を application/x-protostream メディアタイプに設定する必要があります。

<cache>
   <encoding>
      <key media-type="application/x-protostream"/>
      <value media-type="application/x-protostream"/>
   </encoding>
</cache>

Protobuf スキーマを登録するには、以下の例のように HTTP POST メソッドを使用して、スキーマを ___protobuf_metadata キャッシュに挿入します。

curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:8080/rest/___protobuf_metadata/schema.proto

Protobuf のエンコーディングと Protobuf スキーマの登録についての詳細は、「Protobuf エンコーディング」を参照してください。

_type フィールドが JSON ドキュメントに含まれるようにする必要があります。このフィールドは、JSON ドキュメントが対応する Protobuf メッセージを特定します。

たとえば、以下は Person として定義された Protobuf メッセージになります。

message Person {
  required string name = 1;
  required int32 age = 2;
}

以下は対応する JSON ドキュメントになります。

{
  "_type": "Person",
  "name": "user1",
  "age": 32
}

以下のように、JSON 形式でキャッシュにコンテンツを書き込むことができます。

curl -u user:user -XPOST --data-binary @./Person.json -H "Content-Type: application/json; charset=UTF-8" http://127.0.0.1:8080/rest/{cacheName}/{key}

コンテンツをキャッシュに書き込んだ後、以下のように JSON 形式で読み取ることができます。

curl -u user:user http://127.0.0.1:8080/rest/{cacheName}/{key}

HTTP GET メソッドまたは POST メソッドを使用して、REST インターフェース経由でデータのクエリーを行います。

GET メソッドのクエリーリクエストの構造は次のようになります。

{cacheName}?action=search&query={ickle query}

以下はクエリーの例になります。

POST メソッドのクエリーリクエストの構造は次のようになります。

{cacheName}?action=search

リクエストのボディーは、クエリーと JSON 形式のパラメーターを指定します。

以下は、Entity という名前のエンティティーからデータを返し、where 句を使用して結果をフィルターするクエリーの例になります。

{
 "query":"from Entity where name:\"user1\"",
 "max_results":20,
 "offset":10
}

{
  "total_results" : 150,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 25
    }
  } ]
}