検索はどのようにRESTfulインターフェースに適合しますか？

RESTfulインターフェースを設計する場合、要求タイプのセマンティクスは設計に不可欠であると見なされます。

• GET-コレクションの一覧表示または要素の取得
• PUT-コレクションまたは要素を置き換えます
• POST-コレクションまたは要素を作成する
• DELETE -まあ、ERM、コレクションや要素を削除

ただし、これは「検索」の概念をカバーしていないようです。

たとえば、求人検索サイトをサポートする一連のWebサービスの設計では、次の要件があります。

• 個々の求人広告を取得する
  • GETへdomain/Job/{id}/
• 求人広告を作成
  • POSTへdomain/Job/
• 求人広告の更新
  • PUT todomain/Job/
• 求人広告の削除
  • DELETEへdomain/Job/

「Get All Jobs」も簡単です。

• GETへdomain/Jobs/

しかし、仕事の「検索」はこの構造にどのように分類されますか？

あなたは可能性があり、それは「リストコレクション」のバリエーションの主張として実装します。

• GETへdomain/Jobs/

ただし、検索は複雑になる可能性があり、長いGET文字列を生成する検索を作成することは完全に可能です。つまり、ここでSOの質問を参照すると、約2000文字よりも長いGET文字列の使用に問題があります。

例として、ファセット検索があります-「ジョブ」の例を続けます。

「テクノロジー」、「役職」、「規律」、およびフリーテキストキーワード、就業年齢、場所、給与などのファセットでの検索を許可できます。

流動的なユーザーインターフェイスと多数のテクノロジと役職により、検索に多数のファセットの選択肢を含めることが可能です。

この例をジョブではなくCVに微調整すると、さらに多くのファセットがもたらされ、100個のファセットが選択された検索、または50文字の長さ（たとえば役職、大学名、雇用者名）。

そのような状況では、検索データが正しく送信されるようにするために、PUTまたはPOSTを移動することが望ましい場合があります。例えば：

• POSTへdomain/Jobs/

しかし意味的には、これはコレクションを作成するための命令です。

これを検索の作成として表現することもできます。

• POSTへdomain/Jobs/Search/

または（以下のburninggrammaで示唆されているように）

• POSTへdomain/JobSearch/

意味的には理にかなっているように思えるかもしれませんが、実際には何も作成しておらず、データを要求しています。

したがって、セマンティック上はGETですが、GETは必要なものをサポートすることを保証されていません。

ですから、質問は-可能な限りRESTfulなデザインを忠実に保ちながら、HTTPの制限内に収まるようにしながら、検索に最適なデザインは何ですか？

GETリクエストには、他のソリューションより優れた利点があることを忘れないでください。

1）GETリクエストはURLバーからコピーでき、検索エンジンによってダイジェストされ、「フレンドリー」です。「フレンドリ」とは、通常、GETリクエストがアプリケーション内の（べき等）を変更しないことを意味します。これは、検索の標準的なケースです。

2）これらの概念はすべて、ユーザーと検索エンジンだけでなく、アーキテクチャのAPI設計の観点からも非常に重要です。

3）POST / PUTを使用して回避策を作成すると、現在考えていない問題が発生します。たとえば、ブラウザの場合、戻るボタン/ページの更新/履歴をナビゲートします。これらはもちろん解決できますが、それは別の回避策となり、別の回避策になります...

これらすべてを考慮すると、私のアドバイスは次のようになるでしょう。

a）巧妙なパラメーター構造を使用して、GETに収まることができるはずです。極端な場合は、このGoogle検索のような戦術に行くこともできますが、ここでも多くのパラメータを設定していますが、それは非常に短いURLです。

b）JobSearchのようなアプリケーションに別のエンティティを作成します。非常に多くのオプションがあると仮定すると、これらの検索を同様に保存し、管理する必要がある可能性が高いため、アプリケーションをクリアします。JobSearchオブジェクトはエンティティ全体として作業できます。つまり、テスト /使用が簡単になります。

個人的に、私はすべての爪と戦い、a）でそれを成し遂げようとします。すべての希望が失われたら、涙を浮かべてオプションb）に戻ります。

TL; DR：フィルタリング用のGET、検索用のPOST

コレクションのリストからの結果のフィルタリングと複雑な検索を区別します。私が使用するリトマステストは、基本的にフィルタリング（ポジティブ、ネガティブ、または範囲）以上のものが必要な場合、POSTを必要とするより複雑な検索だと考えています。

これは、何が返されるかを考えるときに強化される傾向があります。通常、リソースのライフサイクルがほぼ完全な場合（PUT、DELETE、GET、コレクションGET）にのみGETを使用します。通常、コレクションGETでは、そのコレクションを構成するRESTリソースであるURIのリストを返します。複雑なクエリでは、応答を構築するために複数のリソースからプルすることがあり（SQL結合を考えてください）、URIではなく実際のデータを送り返します。問題は、データがリソースで表されないため、常にデータを返す必要があることです。これは、POSTを必要とする明確なケースのようです。

-

しばらく経ち、元の投稿は少しずさんだったので、更新するつもりでした。

GETは、ほとんどの種類のデータ、RESTリソースのコレクション、リソースの構造化データ、単一のペイロード（画像、ドキュメントなど）を返すための直感的な選択です。

POSTは、GET、PUT、DELETEなどに収まらないように思われるものすべてのキャッチオールメソッドです。

この時点で、単純な検索、フィルタリングはGETを通じて直感的に意味をなすと思います。複雑な検索は、特に集約関数、相互相関（結合）、再フォーマッターなどを投入する場合、個人の好み次第です。 ）は、POSTリクエストの本文としてより意味があります。

また、API使用のエクスペリエンスの側面も考慮します。私は通常、ほとんどの方法をできるだけ使いやすく、できるだけ直感的にしたいと考えています。特に同じAPIの他のRESTリソースの動作と矛盾する場合は、より柔軟な（したがってより複雑な）呼び出しをPOSTおよび異なるリソースURIにプッシュします。

いずれにせよ、GETで検索するのかPOSTで検索するのかよりも、おそらく一貫性が重要です。

お役に立てれば。

RESTでは、リソース定義は非常に広範囲です。実際には、いくつかのデータをバンドルする必要があります。

• 検索リソースをコレクションリソースと考えると便利です。クエリパラメータ（URIの検索可能部分とも呼ばれる）は、クライアントが関心のあるアイテムにリソースを絞り込みます。

たとえば、メインのGoogle URIは、「インターネット上のすべてのサイトへのリンク」というコレクションリソースを指します。クエリパラメータは、表示するサイトに絞り込みます。

（URI =ユニバーサルリソース識別子。URL=ユニバーサルリソースロケーター。おなじみの "http：//"はURIのデフォルト形式です。URLはロケーターですが、RESTではリソース識別子に一般化することをお勧めします。 。しかし、人々はそれらを交換可能に使用します。）

• この例で検索しているリソースはジョブコレクションであるため、次のように検索するのが理にかなっています

GET site / jobs？type = blah＆location = here＆etc = etc

（リターン）{ジョブ：[{ジョブ：...}]}

次に、POSTを使用します。これは、追加または処理の動詞であり、そのコレクションに新しいアイテムを追加します。

POSTサイト/ジョブ

{ジョブ：...}

• job各ケースでオブジェクトの構造は同じであることに注意してください。クライアントは、クエリパラメーターを使用して検索を絞り込んでジョブのコレクションを取得し、アイテムの1つに同じ形式を使用して新しいジョブをPOSTできます。または、それらのアイテムの1つを取り、そのURIにPUTしてそのアイテムを更新できます。

• 本当に長い、または複雑なクエリ文字列の場合、慣例により、代わりにそれらをPOSTリクエストとして送信しても問題ありません。クエリパラメータを名前/値のペア、またはJSONまたはXML構造のネストされたオブジェクトとしてバンドルし、リクエストの本文で送信します。たとえば、クエリに多数の名前/値ペアの代わりにネストされたデータがある場合。POSTのHTTP仕様では、追加動詞またはプロセス動詞として記述されています。（RESTの抜け穴から戦艦を航海する場合は、POSTを使用します。）

ただし、これをフォールバックプランとして使用します。

あなたがそれを行うときに失うものはa）GETは無効です-つまり、何も変更しません-POSTはそうではありません。そのため、呼び出しが失敗した場合、ミドルウェアは結果を自動的に再試行したりキャッシュしたりしません。2）本体の検索パラメーターを使用すると、URIをカットアンドペーストできなくなります。つまり、URIは必要な検索の特定の識別子ではありません。

「作成」と「検索」を区別するため。RESTのプラクティスと一致するオプションがいくつかあります。

• ジョブの代わりにジョブ検索のように、コレクションの名前に何かを追加することで、URIでそれを行うことができます。つまり、検索コレクションを別個のリソースとして扱っているということです。

• POSTのセマンティクスは両方とも追加ORプロセスであるため、検索ボディをペイロードで識別することができます。{job：...} vs. {search：...}のように。適切に投稿または処理するのはPOSTロジック次第です。

それはほとんど設計/実装の好みです。明確な慣習があるとは思わない。

したがって、既にレイアウトしたように、アイデアは次のコレクションリソースを定義することです。 jobs

サイト/ジョブ

GET +クエリパラメーターで検索して、検索を絞り込みます。長いまたは構造化されたデータクエリは、POSTの本体に（おそらく別の検索コレクションに）入ります。コレクションに追加するPOSTで作成します。そして、特定のURIへのPUTで更新します。

（FWIW URIのスタイル規則では、すべて小文字でハイフンで区切られた単語を使用します。しかし、そうする必要はありません。）

（また、あなたの質問から、あなたがこの道をずっと進んでいるのは明らかだと言うべきです。それらを並べるためだけに、ある種のことを明確に綴りましたが、あなたの質問はこの中のセマンティック問題のほとんどにすでに対処していました答え。私は単に慣習と練習を組み合わせていただけです。）

私は通常、ODataクエリを使用します。これらはGET呼び出しとして動作しますが、返されるプロパティを制限し、フィルタリングすることができます。

あなたはこのようなトークンを使用$select=して$filter=ますので、次のようになりますURIで終わるだろう。

/users?$select=Id,Name$filter=endswith(Name, 'Smith')

$skipand $topおよびordering を使用してページングを行うこともできます。

詳細については、OData.orgをご覧ください。使用している言語を指定していませんが、ASP.NETの場合、WebApiプラットフォームはODataクエリをサポートします-他（PHPなど）の場合、データベースクエリに変換するために使用できるライブラリが存在する可能性があります。

考慮すべき1つのアプローチは、可能なクエリのセットをコレクションリソースとして扱うことです/jobs/filters。

POST本体にクエリパラメータを指定したこのリソースへのリクエストは、新しいリソースを作成するか、既存の同等のフィルターを識別し、そのIDを含むURLを返します/jobs/filters/12345。

このIDは、ジョブのGETリクエストで使用できます/jobs?filter=12345。GETフィルターリソースに対する後続のリクエストは、フィルターの定義を返します。

このアプローチには、フィルター定義のクエリパラメーター形式から解放されるという利点があり、潜在的に複雑なフィルターを定義するための強力な機能を提供します。OR条件は、クエリ文字列で達成するのが難しいと考えることができる1つの例です。

この方法の欠点は、URLの可読性が失われることです（ただしGET、フィルターリソースの要求を通じて定義を取得することで軽減できます）。このため/jobs、フィルターリソースをサポートするのと同じまたはリソースのクエリパラメーターのサブセットをサポートすることもできます。これは、短いクエリに使用できます。この機能が提供されている場合、上のクエリパラメータを使用する場合、フィルタリングの2種類のキャッシュ可能性を維持するために/jobsリソース、実装は、内部/作成フィルタリソースを再利用し、返すべき302か、303の形のURLを示すステータス/jobs?filter=12345。

これは古い答えですが、私はまだ議論に少し貢献できます。私は、REST、RESTful、およびアーキテクチャの誤解を非常に頻繁に観察しました。RESTfulは、検索を構築しないことについて何も言及していません。RESTfulにはアーキテクチャに関するものは何もありません。これは一連の設計原則または基準です。

より良い方法で検索を説明するには、特にアーキテクチャについて話さなければなりません。より適切なものはリソース指向アーキテクチャ（ROA）です。

RESTfulには設計の原則があります。dem等とは、いくつかの答えを読んで結果が変わらないという意味ではなく、独立したリクエストの結果は実行回数に依存しないことを意味します。それは変化する可能性があります.RESTful APIによって提供されるいくつかのデータを供給しているデータベースを継続的に更新していることを想像してみましょう。同じGETを実行すると結果が変わる可能性がありますが、実行回数に依存しません 世界をフリーズできれば、別の結果につながるリソースをリクエストしたときに、サービス内に状態、変換、何かが存在しないことを意味します。

定義上、リソースはそれ自体が物として参照されることが重要なものです。

リソース指向のアーキテクチャ（簡潔にするために、これからROAと呼びましょう）では、多くの可能性があるリソースに焦点を当てます。

• ドキュメントのバージョン
• ドキュメントの最終更新バージョン
• 検索の結果
• オブジェクトのリスト
• 電子商取引から最初に購入した記事

リソースの点でユニークなのは、追加性です。つまり、URIが1つしかないということです。

そのようにして、検索はROAを考慮してRESTfulに完全に適合します。検索は通常の検索であり、何も変更しないと仮定しているため、GETを使用する必要があります。したがって、so等です（追加された新しい要素に応じて異なるものを返す場合でも）。ROAではなくRESTfulに固執する可能性があるため、ここでは混乱があります。つまり、ROAのアドレス可能性の原則を使用していないため、検索を作成し、同じパラメーターで異なるものを返すパターンに従うことができることを意味します。どう？さて、本文またはヘッダーで検索フィルターを送信すると、リソースはADDRESSABLEではありません。

W3の元のドキュメントには、正確な内容とURIの原則が記載されています。

https://www.w3.org/DesignIssues/Axioms

このアーキテクチャのURLはすべて自己記述的でなければなりません。原則に従ってURIのすべてに対処する必要があります。つまり、/（スラッシュ）を使用して必要なものを分離したり、パラメーターをクエリしたりすることができます。これには制限があることはわかっていますが、これはアーキテクチャパターンです。

RESTfulのROAパターンに従うと、検索は他のどのリソースよりも多くなく、唯一の違いは、リソースがオブジェクト自体との直接的な関係ではなく計算から得られることです。原則に基づいて、次のパターンに基づいた簡単な算術計算サービスに取り組み、それを取得できました。

http://myapi.com/sum/1/2

sum、1および2は変更できますが、計算の結果は一意であり、アドレス指定可能です。同じパラメーターを使用して呼び出すたびに、サービスで同じ変更を取得します。リソース/ sum / 1/2および/ substract / 5/4は、原則に完全に準拠しています。

1つのURIに対して常に同じ結果（表現）を返す静的コレクションがある場合、GETは問題ありません。また、これらの表現を生成するデータが変更されることはありません。ソースは読み取り専用データベースです。

GETが1つの同じURIに対して異なる結果を返すと、べき等性/安全性とCoolURI原則に違反するため、RESTfulではありません。べき等動詞をデータベースに書き込むことは可能ですが、表現に影響を与えてはなりません。

一般的な検索は、結果への参照を返すPOSTリクエストで始まります。結果を生成します（新しく、後続のGETで取得できます）。もちろん、この結果は階層的（GET可能なURIのさらなる参照）である可能性があり、アプリケーションにとって意味がある場合は、以前の検索の要素を再利用する可能性があります。

ちなみに、私は人々が違うやり方をしていることを知っています。RESTに違反することがいかに便利であるかを説明する必要はありません。