RESTful APIのパラメータに有効な値のリストを提供するにはどうすればよいですか？

Question

これは技術的な質問よりも概念的です。巨大なレンタカーを扱うためのREST APIがあるとします。

APIはそのような非常に標準とコヒーレント（でも物議場合）の方法でビジネスエンティティ/リソースの周りにモデル化されています

• /cars/1234 - 詳細なデータを特定の車
• /clients/5678について - 詳細なデータ車のリストとそのURIを
• /clients - - 特定のクライアント
• /carsに関するクライアントのリスト

しかし、艦隊は巨大で、すべての車のリストはそれほど有用ではありません。私はむしろのように、それがフィルタリングだろう：正しく「type」パラメータを使用するために

GET /cars?type=minivan 

、私は「そのような「ミニバン」、「コンバーチブル」、「ステーションワゴン」として有効な値のリストを持っている必要がありますハッチバック "、"セダン "などです。そこには多くの種類の車はありませんが、このリストはAPIのSwagger定義のenumには大きすぎるものとしましょう。

だから、REST APIがそのようなクエリパラメータに有効な値のリストを提供するために最も一貫して自然な方法はありますか？

• /cars/typesのような従属リソースとして、これでURLパターン/cars/{id}が破損することはありますか？

• /tables/cars/typesのような別のリソースとして、これは、ビジネスモデル自体の主要なリソースの周りの一貫性を破るだろうか？

• OPTIONS /carsの応答の一部として、それは私にとって「最もリーズナブルな」方法のように見えますが、私の同僚の中には同意しない人もいますし、OPTIONSはそのようなものにはめったに使われないようです。

• おそらくGET /cars?&metadata=valuesなどの応答の一部として、ここでの「値」は、クエリパラメータよりも返されるデータに意味的に関連しているように見えますが、そうではありませんか？

• 他に何か？

私は

はありがとう... Googleで検索して、この特定の主題に関するいくつかの推奨事項については、SOで検索、私は、そのような意思決定のための引数で私を助けるために何かを見つけることができませんでしたしています！

はFabricioロシャ

ブラジリア、ブラジル

Answer 1

"良いREST APIは醜いのウェブサイトのようなものです" - Rickard Öberg

それでは、どのようにあなたのウェブサイトでそれを行うのでしょうか？さて、あなたはおそらくフォームに行くリンクを持っていて、フォームにはリストコントロール/各オプションのセマンティックキューを持つラジオボタンがあり、利用可能なオプションから値を選択することを期待していますユーザエージェントは、フォームが提出されたときにその値をGETリクエストのURLにエンコードします。

したがって、RESTでは同じことを行います。最初の応答では、 "フォーム"リソースへのリンクを含めることになります。ユーザーエージェントがフォームリソースを取得すると、使用可能なオプションがエンコードされたフォームのハイパーメディア表現が返されます。フォームが送信されると、リソースは識別子のクエリ部分からクライアントの選択肢を選択します。

しかし、おそらくあなたはRESTをやっていないでしょう：それは巨大なPITAであり、RESTアーキテクチャの制約の利点はおそらくあなたの文脈ではうまくいきません。したがって、オプションのリストを含むメッセージを返すリソースの識別子の合理的なスペルを探している可能性があります。

/cars/typesのような従属リソースですか？これは/ cars/{id} URLパターンを破るでしょうか？そうではありませんか？

ルーティングの実装が曖昧さを処理できるとすれば、それは良い選択です。リストが1つだけであっても、コンテキストごとに異なるリストであっても、それをどのように処理するかを検討することができます。

/tables/cars/typesなどの別のリソースとして、これは、ビジネスモデル自体の主要なリソースの周りの一貫性を破るだろうか？

OOプログラミングとカプセル化を覚えていますか？基礎となるデータモデルからAPIを分離することは良いことです。

私は個人的には、階層内の要素として「テーブル」を気に入っていません。あなたがその方向に向かうしたい場合は、私は/dimensionsをお勧めしたい - あなたはOPTIONS /車のための応答の本文の一部としてdata warehouse

を設計していた場合、それはあなたが使用する可能性がありますスペルですか？それは私にとって「最もリーズナブルな」方法のように見えますが、私の同僚の中には同意しない人もいますし、OPTIONSはそのようなものにはめったに使われないようです。

Yikes！ RFC 7231は非常に混乱していることを示唆しています。

OPTIONSメソッドは、オリジンサーバまたは介在する仲介のいずれかで、ターゲット・リソースの利用可能通信オプションに関する情報を要求します。

（強調が加えられる）。Web用のAPIを記述する際には、クライアントの要求が制御できない仲介者を経由する可能性があることを常に覚えておく必要があります。そのような状況で良い経験を提供するあなたの能力は、仲介者を統一的なインターフェースから逸脱して混乱させないことに依存します。

多分GET/carsへの応答の一部として？ &メタデータ=値など

ほとんどの場合、機械はあらゆるスペルに非常に慣れています。 URIデザインガイドラインは、通常、人間の聴衆に焦点を当てています。私は特に、/cars?...が検索結果であるリソースを特定する場合、特にスペルがあなたの人間の消費者を混乱させると思います。

他に何か？私はまだ人々が/車の下で見つけることを期待しているものは、それらの間の値の一覧ではなく、それらの値のリストではない車の束（それらの表明は...）であると感じています...

あなたの質問を変更しましょう少し

は何文書ようなクエリパラメータの有効な値のリストにREST APIの最も一貫性のある自然な方法だろうか？

ウェブが本当に良いことがあれば、ものを文書化しています。ほとんどすべての文書化されたWeb APIを選んで、エンドポイントについて読んでいるところに注意を払いなさい - それはあなたに良い考えを与えるでしょう。

https://api.stackexchange.com/docs/questions

はあなたが

https://api.stackexchange.com/2.2/questions

タイプのリソースリソースの家族について知る必要があるすべてを告げるどこ

たとえば、あなたは当然、StackExchangeのAPIで見ることができます次のように文書化されています：

https://api.stackexchange.com/docs/types/flag-option

セクシーにしたい場合は、Accept-Typeを使用して、人間が判読可能なドキュメントまたは機械で判読可能なドキュメントにリダイレクトすることができます。

Answer 2

私は同様の状況ですが、多数の可能な値を持つ多数のフィールドがあり、場合によっては値が階層から来てフィールドが文字列の配列である場合があります。 （あなたの例から借用：車を製造したプラントを記録することができますが、大陸、国、州によって構成された1次元のリストではありません）。

すべてのデータをユーザーに提供するために/ taxonomiesリソースを実装すると思います。私はWordPressがそれと密接にまだ勉強していないけれども、同様のスキーム（http://v2.wp-api.org/reference/taxonomies/）を使用しているのを見ている。