RESTfulな検索/フィルタリングを設計する方法は？[閉まっている]

現在、PHPでRESTful APIを設計および実装しています。しかし、私は最初の設計の実装に失敗しています。

GET /users # list of users
GET /user/1 # get user with id 1
POST /user # create new user
PUT /user/1 # modify user with id 1
DELETE /user/1 # delete user with id 1

これまでのところ、かなり標準的ですよね？

私の問題は最初のものGET /usersです。リストをフィルタリングするために、リクエスト本文でパラメーターを送信することを検討していました。これは、次のように、非常に長いURLを取得せずに複雑なフィルターを指定できるようにするためです。

GET /users?parameter1=value1&parameter2=value2&parameter3=value3&parameter4=value4

代わりに、私は次のようなものを望んでいました：

GET /users
# Request body:
{
    "parameter1": "value1",
    "parameter2": "value2",
    "parameter3": "value3",
    "parameter4": "value4"
}

これはもっと読みやすく、複雑なフィルターを設定する大きな可能性を与えてくれます。

とにかく、file_get_contents('php://input')リクエストのリクエスト本文を返しませんでしたGET。私も試しましたhttp_get_request_body()が、使用している共有ホスティングにはありませんpecl_http。とにかくそれが役に立ったかどうかはわかりません。

私はこの質問を見つけ、GETはおそらくリクエストボディを持つべきではないことに気づきました。それは少し決定的ではありませんでしたが、彼らはそれに対して助言しました。

だから今私は何をすべきかわかりません。RESTfulな検索/フィルタリング機能をどのように設計しますか？

私はを使用できると思いますがPOST、それはあまりRESTfulに見えません。

RESTful検索を実装する最良の方法は、検索自体をリソースと見なすことです。その後、検索を作成しているため、POST動詞を使用できます。POSTを使用するために、データベースに文字通り何かを作成する必要はありません。

例えば：

Accept: application/json
Content-Type: application/json
POST http://example.com/people/searches
{
  "terms": {
    "ssn": "123456789"
  },
  "order": { ... },
  ...
}

ユーザーの観点から検索を作成しています。これの実装の詳細は無関係です。一部のRESTful APIは永続性さえ必要としない場合があります。これは実装の詳細です。

GETシステムでURLのみを使用するため、GETリクエストをキャッシュできないため、GETリクエストでリクエスト本文を使用すると、RESTの原則に違反します。

さらに悪いことに、ユーザーをこのページにリダイレクトするために必要なすべての情報がURLに含まれていないため、URLをブックマークできません。

リクエストボディパラメータの代わりにURLまたはクエリパラメータを使用します。

例えば：

/myapp?var1=xxxx&var2=xxxx
/myapp;var1=xxxx/resource;var2=xxxx 

実際、HTTP RFC 7231は次のように述べています。

GETリクエストメッセージ内のペイロードには、セマンティクスが定義されていません。GETリクエストでペイロードボディを送信すると、一部の既存の実装がリクエストを拒否する可能性があります。

詳細については、こちらをご覧ください

リソースのフィルタリング/検索はRESTfulな方法で実装できるようです。アイデアは、/filters/またはと呼ばれる新しいエンドポイントを導入すること/api/filters/です。

このエンドポイントフィルターの使用はリソースと見なすことができるため、POSTメソッドを介して作成されます。この方法-もちろん-bodyを使用してすべてのパラメーターを運ぶことができ、複雑な検索/フィルター構造を作成できます。

このようなフィルターを作成した後、検索/フィルター結果を取得するには2つの方法があります。

1. 一意のIDを持つ新しいリソースが201 Createdステータスコードと共に返されます。次に、このIDを使用して、GET要求を次の/api/users/ように行うことができます。

   GET /api/users/?filterId=1234-abcd
   

2. 新しいフィルターが作成された後、POSTそれは応答しません201 Createdが、同時にヘッダーが303 SeeOtherとともに応答します。このリダイレクトは、基盤となるライブラリを介して自動的に処理されます。Location/api/users/?filterId=1234-abcd

どちらのシナリオでも、フィルターされた結果を取得するには2つの要求を行う必要があります。これは、特にモバイルアプリケーションの場合、欠点と見なされる場合があります。モバイルアプリケーションの場合、への単一POST呼び出しを使用し/api/users/filter/ます。

作成したフィルターを保持する方法は？

それらはDBに保存して後で使用できます。これらは、redisなどの一時的なストレージに保存することもでき、有効期限が切れると削除されるTTLがあります。

このアイデアの利点は何ですか？

フィルター、フィルターされた結果はキャッシュ可能で、ブックマークすることもできます。

リクエストパラメータを使用する必要があると思いますが、やりたいことを実行するための適切なHTTPヘッダーがない場合に限ります。HTTPの仕様では、明示的にGETが身体を持つことができないことを、言っていません。ただし、このペーパーでは次のように述べています。

慣例により、GETメソッドが使用される場合、リソースを識別するために必要なすべての情報はURIにエンコードされます。HTTP / 1.1には、クライアントがURIのクエリ部分ではなくHTTPエンティティ本体でデータをサーバーに提供する安全な対話（検索など）に関する規則はありません。つまり、安全な操作のために、URIが長くなる可能性があります。

私はlaravel / phpバックエンドを使用しているので、次のようなものを使用する傾向があります。

/resource?filters[status_id]=1&filters[city]=Sydney&page=2&include=relatedResource

PHPは自動的に[]paramsを配列に変換するため、この例では$filter、フィルターの配列/オブジェクトを保持する変数に加えて、ページと、積極的にロードしたい関連リソースがあります。

別の言語を使用する場合でも、これは適切な規則である可能性があり[]、配列に変換するパーサーを作成できます。

最初のAPIが完全にRESTfulであるかどうかにかかわらず、あまり心配しないでください（特にアルファ段階にいる場合）。最初にバックエンド配管を機能させます。あらゆる種類のURL変換/書き換えをいつでも行うことができます。広範囲にわたるテスト（ "ベータ版"）に十分な安定性が得られるまで繰り返し調整を行います。

パラメータがURI自体の位置と規則によってエンコードされ、常に何かにマッピングすることがわかっているパスを前に付けたURIを定義できます。私はPHPを知りませんが、そのような機能が（Webフレームワークを使用する他の言語に存在するように）存在すると想定します。

.ie。ストア＃1でparam [i] = value [i] for i = 1..4を使用して「ユーザー」タイプの検索を実行します（URIクエリパラメータの省略形としてvalue1、value2、value3、...）：

1) GET /store1/search/user/value1,value2,value3,value4

または

2) GET /store1/search/user,value1,value2,value3,value4

または次のように（私はそれをお勧めしませんが、後で詳しく説明します）

3) GET /search/store1,user,value1,value2,value3,value4

オプション1では、接頭辞が付いたすべてのURIを/store1/search/userデフォルトで検索ハンドラー（またはPHPの指定）にマップし、store1（と同等）の下のリソースを検索し/search?location=store1&type=userます。

APIによって文書化および適用される慣例により、パラメーター値1〜4はコンマで区切られ、その順序で示されます。

オプション2は、検索タイプ（この場合はuser）を位置パラメーター＃1として追加します。どちらのオプションも単なる表面的な選択です。

オプション3も可能ですが、希望しないと思います。特定のリソース内での検索機能は、検索自体の前にあるURI自体で提示する必要があると思います（URIで検索がリソース内で特定であることを明確に示しているかのように）。

これがURIのパラメーターを渡すことの利点は、検索がURIの一部であることです（したがって、検索はリソース、つまり内容が時間とともに変化し、変化するリソースとして扱われます）。欠点は、パラメーターの順序が必須であることです。 。

このようなことをしたら、GETを使用できます。これは読み取り専用リソースになります（POSTまたはPUTできないため、GETされると更新されます）。それは、呼び出されたときにのみ存在するようになるリソースでもあります。

また、結果を一定期間キャッシュするか、DELETEを使用してキャッシュを削除することで、セマンティクスをさらに追加することもできます。ただし、これは、ユーザーが通常DELETEを使用する目的に反する場合があります（通常、ユーザーはキャッシュヘッダーを使用してキャッシュを制御するためです）。

どのようにそれを行うかは設計上の決定ですが、これが私のやり方です。これは完璧ではなく、これを行うことが最善の方法ではない場合があると確信しています（特に非常に複雑な検索条件の場合）。

参考までに：これは少し遅れていることを知っていますが、興味のある人にとっては。どのくらいRESTfulになりたいかによって異なりますが、HTTP仕様ではあまり明確ではないため、独自のフィルタリング戦略を実装する必要があります。すべてのフィルターパラメーターをURLエンコードすることをお勧めします。

GET api/users?filter=param1%3Dvalue1%26param2%3Dvalue2

私はそれが醜いことを知っていますが、それはそれを行うための最もRESTfulな方法であり、サーバー側で簡単に解析できるはずだと思います:)