リソースURLにあるRESTfulクエリーストリング

Question

私はAPIをよりRESTfulにする作業を進めています。私はこのようなより多くのRESTfulするエンドポイントを更新しました

/booking?bookingid=123 

：

{ 
    "bookingId":123, 
    "people":[ 
     { 
     "personId":0, 
     "name":{ 
      "forename":"Jon", 
      "surname":"Smith" 
     } 
     }, 
     { 
     "personId":1, 
     "name":{ 
      "forename":"Sarah", 
      "surname":"Jones" 
     } 
     } 
    ] 
} 

：予約はこのようなビットに見える

/bookings/123 

現時点では私はこのようなエンドポイントを持っています

予約に特定の姓が含まれている場合にのみ予約を返し、予約に姓が存在しない場合は「見つからない」を返したいとします。

私は、これは、クエリ文字列を追加することです実装するため探しています方法：

/bookings/123?surname="Jones" 

これはサラの姓として上記の予約を返しますが、「ジョーンズ」の予約は、クエリ文字列で返されますです氏名の値が「Smith」である。

最初の問題は、という名前のプロパティがの予約オブジェクトに追加された場合、そのクエリはそれに反しているように見えます。もう1つは、1つのエンティティに対してクエリを実行しているということですリストは、これはRESTfulなアプローチですか、そうでない場合は、より良いアプローチは何ですか？

Answer 1

コミュニティが同意する「RESTful」の定義はありません。

"RESTful"の定義に最も近いのは、 "REST"という用語を導入した論文であるRoy T. FieldingのArchitectural Styles and the Design of Network-based Software Architecturesです。この論文では、「RESTful」URLをどのように構造化するべきかという言葉は一言もありません。その代わりに、サーバーは、URLに便利なURLを選択してから、ハイパーメディアリンクでクライアントに明示的に通信するという考え方です。この種の「RESTful」システムでは、/_content/AcmeWebApi.dll?ENDPOINT=booking&ID=123&tc=yのように/booking?bookingid=123は完全に優れたURLです。

しかし、この論文（およびそれとの用語「REST」）が広く認識された後、コミュニティは「REST」というこのアイデアから、他のさまざまな矛盾したアイデアの範囲に急速に漂った。 REST "からgreat dismay of Roy T. Fieldingに移動します。

したがって、ご質問に有益にお答えすることはできません。

あなたは可能性がいくつかの他の特性、後にしている場合、たとえば、「休息」は本当にあなたがのために最適化しようとしているプロパティであれば考えてみましょう、またはクライアントの理解の

• やすさを実装
HTTPキャッシュのようにデプロイされたコンポーネントとの相互運用性
• 会社XのAPIのようなもの将来
• にURLを変更するには、サーバーの自由

であり、それぞれが異なるURLデザインを必要とする可能性があります。

Answer 2

クエリパラメータを使用して単一のリソースをフィルタ処理するのは一般的ではありませんが、the specに準拠しています。フィルタの名前を?person-surname=にすると、後で柔軟性を保つことができます。コレクションをフィルタリングして（/bookings?person-surname=）、一致するすべての予約を返す方が理にかなっているかどうかを検討することもできます。

Answer 3

id（つまり/予約/ 123 /）でリソースに直接アクセスすると、後でクウェリングが最適なオプションにならないことがあります。 [あなたが確かに存在することを知っている]リソースのUIDを指定していて、 "見つからない"ことを期待しているときは、不安定です。

クエリをより均一にし、単一のurlパラメータでより多くのパラメータを追加するようにプロビジョニングすることをお勧めします。もちろん、上記で

/bookings?query="param1=value1 AND param2=value2" 

ご予約IDが値123とPARAM2とすることができ、それはここで

/bookings/123?query="param1%3Dvalue1%20AND%20param2%3Dvalue2" 

のparam1なりますので、URLのparamは、最良の選択となりますいしでsurenameすることができますあなたが必要とする価値

param2（つまりsurename）はリソースの直属のプロパティではないため、以下ではさらに改善されたバージョンとして使用することを検討したいと考えています。あなただけの第二のparamを渡すかのようにまた、あなたが上記のparam1とPARAM2の両方を必要とするメモしておき

/bookings?query="bookingId=123 AND people.surename=myname" // in your case people.name.surename 

は、誰かがそれが価値を持つ人のsurename wihtすべての予約を返すよ期待することができbooking.people.name.surename。