大企業がREST APIを設計する方法をすべて見てきたので、RESTを適切に使用する方法について少し混乱しているのは理解できます。
RESTはリソースコレクションシステムです。これは、Representational State Transferの略です。あなたが私に尋ねるなら、素晴らしい定義ではありません。しかし、主な概念は4つのHTTP VERBであり、ステートレスであることです。
注意すべき重要な部分は、RESTで使用できるVERBSは4つだけであることです。これらは、GET、POST、PUT、DELETEです。あなたのresend例は、RESTに新しい動詞を追加することです。これは危険信号です。
質問1
REST APIの呼び出し元はPUT、コレクションに対してを実行すると電子メールが生成されることを知る必要がないことを理解することが重要です。それは私に漏れのにおいがします。彼らが知ることができるのは、を実行すると、PUT後でクエリできる余分なタスクが発生する可能性があるということです。彼らはGET、最近作成されたリソースでを実行することでこれを知っています。これGETにより、Taskリソースとそれに関連付けられているすべてのリソースID が返されます。その後、それらのタスクをクエリしてステータスを確認し、新しいを送信することもできTaskます。
いくつかのオプションがあります。
REST-タスクリソースベースのアプローチ
tasks特定のタスクをシステムに送信してアクションを実行できるリソースを作成します。次にGET、ID返されたタスクに基づいてタスクを実行し、ステータスを判断できます。
またはSOAP over HTTP、アーキテクチャにRPCを追加するためにWebサービスを混在させることができます。
特定のリソースのすべてのタスクを照会する
GET http://server/api/myCollection/123/tasks
{ "tasks" :
[ { "22333" : "http://server/api/tasks/223333" } ]
}
タスクリソースの例
PUT http://server/api/tasks
{
"type" : "send-email" ,
"parameters" :
{
"collection-type" : "foo" ,
"collection-id" : "123"
}
}
==>タスクのIDを返します
223334
GET http://server/api/tasks/223334
{
"status" : "complete" ,
"date" : "whenever"
}
REST-POSTを使用してアクションをトリガーする
POSTリソースにはいつでもデータを追加できます。私の意見では、これはRESTの精神に違反しますが、それでも準拠します。
次のようなPOSTを実行できます。
POST http://server/api/collection/123
{ "action" : "send-email" }
追加のデータでコレクションからリソース123を更新します。その追加データは基本的に、そのリソースの電子メールを送信するようにバックエンドに指示するアクションです。
これに関して私が抱えている問題はGET、リソースのがこの更新されたデータを返すことです。ただし、これは要件を解決し、RESTfulです。
SOAP-RESTから取得したリソースを受け入れるWebサービス
REST APIからの以前のリソースIDに基づいて電子メールを送信できる新しいWebServiceを作成します。元の質問はRESTに関するものなので、ここではSOAPについて詳しく説明しません。これらの2つの概念/技術は、AppleとOrangesであるため、比較しないでください。
質問2
ここにはいくつかのオプションもあります。
REST APIを公開している多くの大企業がsearchコレクションを公開しているようですが、コレクションは、クエリパラメーターを渡してリソースを返す方法にすぎません。
GET http://server/api/search?q="type = myCollection & someField >= someval"
次のような完全修飾RESTリソースのコレクションを返します。
{
"results" :
{ [
"location" : "http://server/api/myCollection/1",
"location" : "http://server/api/myCollection/9",
"location" : "http://server/api/myCollection/56"
]
}
}
または、MVELなどをクエリパラメータとして許可することもできます。
質問3
前に戻ってクエリパラメータを使用して他のリソースにクエリを実行する必要があるよりも、サブレベルを好みます。なんらかのルールがあるとは思いません。両方の方法を実装して、発信者が最初にシステムに入力した方法に基づいて、どちらがより適切であるかを決定できるようにすることができます。
ノート
他の人からの読みやすさのコメントに同意しません。RESTはまだ人間の消費用ではないと考える人もいるでしょう。機械消費用です。ツイートを見たい場合は、Twitterの通常のWebサイトを使用します。APIでREST GETを実行しません。プログラムでツイートを処理したい場合は、REST APIを使用します。はい、APIは理解できる必要がありますgteが、それほど悪くはありません。直感的ではありません。
RESTのもう1つの重要な点は、事前に他のリソースの正確なURLを知らなくても、APIの任意の時点から開始して、他のすべての関連リソースに移動できることです。GETREST のVERB の結果は、それが参照するリソースの完全なREST URLを返す必要があります。したがって、PersonオブジェクトのIDを返すクエリではなく、などの完全修飾URLを返しますhttp://server/api/people/13。その後、URLが変更された場合でも、プログラムで常に結果をナビゲートできます。
コメントへの応答
実際には、リソースの作成、読み取り、更新、または削除（CRUD）を行わない必要があることが実際にあります。
リソースに対して追加のアクションを実行できます。一般的なリレーショナルデータベースは、ストアドプロシージャの概念をサポートしています。これらは、一連のデータに対して実行できる追加のコマンドです。RESTには本質的にその概念はありません。そして、そうすべき理由はありません。これらのタイプのアクションは、RPCまたはSOAP Webサービスに最適です。
これは、REST APIで見られる一般的な問題です。開発者は、RESTを取り巻く概念上の制限を気に入らないため、RESTを適応させて、RESTを好きなように実行できます。ただし、RESTfulサービスになることはできません。基本的に、これらのURL GETは疑似RESTのようなサーブレットの呼び出しになります。
いくつかのオプションがあります：
- タスクリソースを作成する
POSTアクションを実行するためのリソースへの追加データのサポート。- SOAP Webサービスを介して追加のコマンドを追加します。
クエリパラメータを使用した場合、どのHTTP VERBを使用してメールを再送信しますか？
GET-これはメールを再送信し、リソースのデータを返しますか？システムがそのURLをキャッシュし、そのリソースの一意のURLのように処理した場合はどうなるでしょうか。URLにアクセスするたびに、メールが再送信されます。POST -実際には新しいデータをリソースに送信せず、追加のクエリパラメータを送信しました。
与えられたすべての要件に基づいPOSTて、action fieldas POSTデータでリソースに対してを実行すると、問題が解決します。