検索をRESTfulなURLとして表すための合理的な方法を探しています。

セットアップ：CarsとGaragesという2つのモデルがあり、CarsはGaragesに入れることができます。だから私のURLは次のようになります：

/car/xxxx
  xxx == car id
  returns car with given id

/garage/yyy
  yyy = garage id
  returns garage with given id

車はそれ自体で（つまり/ carとして）存在することも、ガレージ内に存在することもできます。たとえば、特定のガレージ内のすべての車を表す正しい方法は何ですか？何かのようなもの：

/garage/yyy/cars     ?

ガレージyyyとzzzの車の結合についてはどうですか？

特定の属性を持つ車の検索を表す正しい方法は何ですか？説明：4ドアの青いセダンをすべて見せてください。

/car/search?color=blue&type=sedan&doors=4

または、代わりに/ carsにする必要がありますか？

そこでは「検索」の使用が不適切に思われます-より良い方法/用語は何ですか？それだけである必要があります：

/cars/?color=blue&type=sedan&doors=4

検索パラメーターをPATHINFOまたはQUERYSTRINGの一部にする必要がありますか？

つまり、クロスモデルのREST url設計と検索についてのガイダンスを探しています。

[更新]私はジャスティンの答えが好きですが、彼はマルチフィールド検索のケースをカバーしていません：

/cars/color:blue/type:sedan/doors:4

またはそのようなもの。どうやって行くの

/cars/color/blue

複数分野のケースに？

検索には、クエリ文字列を使用します。これは完全にRESTfulです。

/cars?color=blue&type=sedan&doors=4

通常のクエリ文字列の利点は、標準で広く理解されており、form-getから生成できることです。

RESTfulなきれいなURL設計は構造に基づいて、リソースを表示する程度である（ディレクトリのような構造、日付：記事/ 2005/5月13日、オブジェクトとそれの属性は、...）、スラッシュは/階層構造を示し、使用-id代わり。

階層構造

私は個人的に好みます：

/garage-id/cars/car-id
/cars/car-id   #for cars not in garages

ユーザーが/car-idパーツを削除すると、carsプレビューが表示されます-直感的。ユーザーはツリーのどこにいるのか、何を見ているのかを正確に知っています。ガレージと車が関係していることを、彼は最初から見て知っています。/car-idまた、とは異なり、一緒に属していることも示し/car/idます。

探す

searchqueryはそのままで問題ありません。ユーザーの好みだけがあり、何を考慮に入れる必要があります。おもしろいのは、検索に参加するときです（下記を参照）。

/cars?color=blue;type=sedan   #most prefered by me
/cars;color-blue+doors-4+type-sedan   #looks good when using car-id
/cars?color=blue&doors=4&type=sedan   #I don't recommend using &*

または基本的に、上記で説明したスラッシュではないもの。
公式：/cars[?;]color[=-:]blue[,;+&]、*。ただし、&一見テキストでは認識できないため、記号は使用しません。

** URIでJSONオブジェクトを渡すことがRESTfulであることをご存知ですか？**

オプションのリスト

/cars?color=black,blue,red;doors=3,5;type=sedan   #most prefered by me
/cars?color:black:blue:red;doors:3:5;type:sedan
/cars?color(black,blue,red);doors(3,5);type(sedan)   #does not look bad at all
/cars?color:(black,blue,red);doors:(3,5);type:sedan   #little difference

可能な機能？

検索文字列を否定する（！）
車を検索するには、黒と赤は 検索しません。
?color=!black,!red
color:(!black,!red)

入社検索は
検索赤または青または黒と車3つのガレージのIDでドアを1..20または101..103または999しかしない 5 /garage[id=1-20,101-103,999,!5]/cars[color=red,blue,black;doors=3]
あなたは、より複雑な検索クエリを構築することができます。（CSS3属性の一致を見て、部分文字列を一致させるアイデアを見つけてください。たとえば、「bar」を含むユーザーを検索しますuser*=bar。）

結論

あなたはすべての後のような、しかし、あなたがそれを行うことができますので、とにかく、これはちょうどことを覚えておいて、あなたのために最も重要な部分であるかもしれないRESTfulな URIが簡単などのようなディレクトリ・理解されている構造で表し/directory/file、/collection/node/item日付、/articles/{year}/{month}/{day}...とするとき、あなたを省略最後のセグメントのどれでも、何が得られるかすぐにわかります。

したがって、これらすべての文字はエンコードされていないことが許可されます。

• 予約なし：a-zA-Z0-9_.-~
  通常、エンコードと非エンコードの両方が許可され、両方の使用は同等になります。
• 特殊文字： $-_.+!*'(),
• 予約済み：;/?:@=&
  それらが表す目的でエンコードされていない状態で使用できます。それ以外の場合はエンコードする必要があります。

• unsafe：<>"#%{}|\^~[]`
  なぜ安全ではなく、なぜエンコードする必要があるのか​​：RFC 1738 2.2を参照

  その他の文字クラスについては、RFC 1738＃page-20も参照してください。

RFC 3986は2.2を参照
以前に述べたことにも関わらず、デリミタの一般的な違いは次のとおりです。つまり、一部は他よりも「重要」であることが重要です。

• 一般的な区切り文字： :/?#[]@
• サブデリメータ： !$&'()*+,;=

参考資料：
階層：2.3を参照、1.2.3を参照
URLパスパラメータ構文
CSS3属性が
IBM：RESTful Webサービスに一致-基本事項
注：RFC 1738はRFC 3986によって更新されました

パスにパラメーターがあることにはいくつかの利点がありますが、IMOにはいくつかの重要な要素があります。

• 検索クエリに必要なすべての文字がURLで許可されるわけではありません。ほとんどの句読点とUnicode文字は、クエリ文字列パラメータとしてURLエンコードする必要があります。私は同じ問題に取り組んでいます。URLでXPathを使用したいのですが、すべてのXPath構文がURIパスと互換性があるわけではありません。したがって、単純なパスの場合/cars/doors/driver/lock/combinationはcombination、運転席ドアのXMLドキュメントで' '要素を見つけることが適切です。しかし/car/doors[id='driver' and lock/combination='1234']、それほど友好的ではありません。

• 属性の1つに基づいてリソースをフィルタリングすることと、リソースを指定することには違いがあります。

  たとえば、

  /cars/colors すべての車のすべての色のリストを返します（返されるリソースは色オブジェクトのコレクションです）

  /cars/colors/red,blue,green 車のコレクションではなく、赤、青、緑のカラーオブジェクトのリストを返します。

  車を返すには、パスは

  /cars?color=red,blue,green または /cars/search?color=red,blue,green

• 名前と値のペアは、名前と値のペアではないパスの残りの部分から分離されていないため、パスのパラメーターは読みにくくなります。

最後のコメント。単数形と複数形の間のパスの変更を回避するため、（おそらく元の回答ではタイプミスであった/garages/yyy/cars）よりも（常に複数形）を好み/garage/yyy/carsます。「s」が追加された単語の場合、変更はそれほど悪くありませんが、に変更/person/yyy/friendsするの/people/yyyは面倒です。

ピーターの答えを拡張するには、検索を一流のリソースにすることができます。

POST    /searches          # create a new search
GET     /searches          # list all searches (admin)
GET     /searches/{id}     # show the results of a previously-run search
DELETE  /searches/{id}     # delete a search (admin)

検索リソースには、色、モデルの作成、ガレージステータスなどのフィールドがあり、XML、JSON、またはその他の形式で指定できます。車とガレージのリソースと同様に、認証に基づいて検索へのアクセスを制限できます。同じ検索を頻繁に実行するユーザーは、プロファイルをプロファイルに保存できるため、再作成する必要がありません。URLは十分に短いため、多くの場合、電子メールで簡単に取引できます。これらの保存された検索は、カスタムRSSフィードなどの基礎となります。

リソースとして考える場合、検索を使用する可能性はたくさんあります。

このRailscastでアイデアについて詳しく説明します。

Justinの答えはおそらく進むべき道ですが、アプリケーションによっては、特定の検索をそれ自体をリソースと見なすことが理にかなっている場合があります。

/search/{searchQuery}

または

/search/{savedSearchName}

私は2つのアプローチを使用して検索を実装します。

1）関連付けられた要素を照会し、ナビゲーションするための最も単純なケース。

    /cars?q.garage.id.eq=1

つまり、ガレージIDが1の自動車をクエリします。

より複雑な検索を作成することも可能です：

    /cars?q.garage.street.eq=FirstStreet&q.color.ne=red&offset=300&max=100

赤ではないFirstStreetのすべてのガレージ内の車（3ページ目、ページあたり100要素）。

2）複雑なクエリは、作成され、回復できる通常のリソースと見なされます。

    POST /searches  => Create
    GET  /searches/1  => Recover search
    GET  /searches/1?offset=300&max=100  => pagination in search

検索作成用のPOST本文は次のとおりです。

    {  
       "$class":"test.Car",
       "$q":{
          "$eq" : { "color" : "red" },
          "garage" : {
             "$ne" : { "street" : "FirstStreet" }
          }
       }
    }

Grailsに基づいています（基準DSL）：http : //grails.org/doc/2.4.3/ref/Domain%20Classes/createCriteria.html

これはRESTではありません。API内でリソースのURIを定義することはできません。リソースナビゲーションはハイパーテキスト駆動である必要があります。かなりのURIと大量の結合が必要な場合は問題ありませんが、RESTfulアーキテクチャの制約に直接違反するため、RESTと呼ばないでください。

RESTの発明者によるこの記事を参照してください。

私はジャスティンの応答が好きですが、検索よりもフィルターをより正確に表すと感じています。camで始まる名前の車について知りたい場合はどうすればよいですか？

私の見たところ、特定のリソースを処理する方法に組み込むことができます：
/ cars / cam *

または、単にフィルターに追加することができます：
/ cars / doors / 4 / name / cam * / colors / red、青、緑

個人的には後者を好みますが、私は決してRESTの専門家ではありません（2週間ほど前に初めて聞いた...）

RESTfulは、URLの/ cars / searchで動詞を使用することをお勧めしません。APIをフィルター/検索/ページ分割する正しい方法は、クエリパラメーターを使用することです。ただし、規範を破る必要がある場合もあります。たとえば、複数のリソースを検索する場合、/ search？q = queryのようなものを使用する必要があります

http://saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/を参照して、RESTful APIを設計するためのベストプラクティスを理解することができます。

さらに、私もお勧めします：

/cars/search/all{?color,model,year}
/cars/search/by-parameters{?color,model,year}
/cars/search/by-vendor{?vendor}

ここでSearchは、Carsリソースの子リソースと見なされます。

ここにあなたのケースに適したオプションがたくさんあります。それでも、POSTボディの使用を検討する必要があります。

クエリ文字列はこの例に最適ですが、たとえばアイテムの任意の長いリストやブール条件など、より複雑なものがある場合、クライアントがPOSTで送信するドキュメントとして投稿を定義することができます。

これにより、より柔軟な検索の説明が可能になり、サーバーのURLの長さの制限を回避できます。

私のアドバイスはこれでしょう：

/garages
  Returns list of garages (think JSON array here)
/garages/yyy
  Returns specific garage
/garage/yyy/cars
  Returns list of cars in garage
/garages/cars
  Returns list of all cars in all garages (may not be practical of course)
/cars
  Returns list of all cars
/cars/xxx
  Returns specific car
/cars/colors
  Returns lists of all posible colors for cars
/cars/colors/red,blue,green
  Returns list of cars of the specific colors (yes commas are allowed :) )

編集：

/cars/colors/red,blue,green/doors/2
  Returns list of all red,blue, and green cars with 2 doors.
/cars/type/hatchback,coupe/colors/red,blue,green/
  Same idea as the above but a lil more intuitive.
/cars/colors/red,blue,green/doors/two-door,four-door
  All cars that are red, blue, green and have either two or four doors.

うまくいけば、それはあなたにアイデアを与えます。基本的に、Rest APIは簡単に発見でき、データを参照できるようにする必要があります。クエリ文字列ではなくURLを使用するもう1つの利点は、HTTPトラフィック用にWebサーバー上に存在するネイティブキャッシュメカニズムを利用できることです。

RESTでのクエリ文字列の悪を説明するページへのリンクは次のとおりです。http：//web.archive.org/web/20070815111413/http：//rest.blueoxen.net/cgi-bin/wiki.pl？QueryStringsConsideredHarmful

通常のページが機能しなかったため、Googleのキャッシュを使用しました。ここにもリンクがあります。http： //rest.blueoxen.net/cgi-bin/wiki.pl？QueryStringsConsideredHarmful