☰

REST API ベストプラクティス: パラメータ値のリストを入力として受け入れる方法 [closed] 質問する

tag-icon • tag-icon rest
REST API ベストプラクティス: パラメータ値のリストを入力として受け入れる方法 [closed] 質問する

私たちは新しい REST API をリリースしており、入力パラメータをどのようにフォーマットすべきかに関するベストプラクティスについてコミュニティからの意見を求めています。

現在、当社の API は JSON 中心です (JSON のみを返します)。XML を返す必要があるかどうかの議論は別の問題です。

私たちの API 出力は JSON 中心なので、入力も少し JSON 中心になる方向に進んでいますが、これは一部の人にとっては便利かもしれませんが、一般的には奇妙だと思っています。

たとえば、複数の製品を一度に取得できる製品の詳細をいくつか取得するには、現在次の方法があります。

http://our.api.com/Product?id=["101404","7267261"]

これを次のように簡略化しましょう:

http://our.api.com/Product?id=101404,7267261

それとも、JSON 入力は便利ですか? それとも面倒ですか?

両方のスタイルを受け入れたいと思うかもしれませんが、その柔軟性は実際にはより多くの混乱や頭痛の種（保守性、ドキュメントなど）を引き起こすのでしょうか?

より複雑なケースは、より複雑な入力を提供したい場合です。たとえば、検索で複数のフィルターを許可する場合:

http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}

必ずしもフィルター タイプ (productType や color など) を次のようにリクエスト名として指定する必要はありません。

http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]

すべてのフィルター入力をグループ化したかったからです。

結局のところ、これは本当に重要なのでしょうか? 世の中には JSON ユーティリティがたくさんあるので、入力タイプはそれほど重要ではないのかもしれません。

API への AJAX 呼び出しを行う JavaScript クライアントは、作業が楽になる JSON 入力を歓迎すると思います。

ベストアンサー1

一歩後退

まず第一に、REST は URI を普遍的に一意な ID として説明します。URI の構造や、どの URI が他の URI よりも「RESTful」であるかにこだわる人が多すぎます。この議論は、誰かに「Bob」という名前を付ける方が「Joe」という名前を付けるよりも良いと言うのと同じくらいばかげています。どちらの名前でも「人を識別する」という役割は果たします。URIは普遍的に一意な名前に過ぎません。

したがって、REST の観点からすると、どちらが?id=["101404","7267261"]より REST に適しているかを議論するのは?id=101404,7267261、\Product\101404,7267261いくぶん無駄なことです。

さて、そうは言っても、多くの場合、URI がどのように構築されるかは、RESTful サービスにおける他の問題の良い指標として役立ちます。URI と一般的な質問には、いくつかの危険信号があります。

提案

  1. 同じリソースに対する複数のURIとContent-Location

    両方のスタイルを受け入れたいと思うかもしれませんが、その柔軟性は実際にはより多くの混乱や頭痛の種（保守性、ドキュメントなど）を引き起こすのでしょうか?

    URI はリソースを識別します。各リソースには1 つの正規 URIが必要です。これは、2 つの URI が同じリソースを指すことができないという意味ではありませんが、これを行うための明確な方法があります。JSON とリスト ベースの形式 (またはその他の形式) の両方を使用する場合は、これらの形式のどちらがメインの正規URI であるかを決定する必要があります。同じ「リソース」を指す他の URI へのすべての応答には、Content-Locationヘッダ。

    名前の例えを続けると、複数の URI を持つことは、人にニックネームがあるようなものです。これはまったく許容範囲であり、多くの場合非常に便利ですが、ニックネームを使用する場合は、その人のフルネーム、つまりその人を指す「正式な」呼び方を知りたいと思うでしょう。こうすることで、誰かが「Nichloas Telsa」というフルネームで誰かに言及したときに、私が「Nick」と呼ぶ同じ人物について話していることがわかります。

  2. URI 内の「検索」

    より複雑なケースは、より複雑な入力を提供したい場合です。たとえば、検索で複数のフィルターを許可したい場合などです...

    私の一般的な経験則は、URI に動詞が含まれている場合、何かが間違っていることを示している可能性があるということです。URI はリソースを識別しますが、そのリソースに対して何を行っているかを示すものではありません。それが HTTP の役割であり、RESTful の用語で言えば「統一インターフェース」です。

    名前のアナロジーを徹底的に説明すると、URI で動詞を使用することは、誰かとやり取りしたいときにその人の名前を変更するようなものです。私が Bob とやり取りしているとき、Bob に Hi と言いたいときに、Bob の名前が「BobHi」になることはありません。同様に、製品を「検索」したいとき、URI 構造が「/Product/...」から「/Search/...」に変更されるべきではありません。

最初の質問への回答

  1. ["101404","7267261"]vsについて101404,7267261: ここでの私の提案は、簡潔さのために JSON 構文を避けることです (つまり、本当に必要がない場合は、ユーザーに URL エンコードを要求しないでください)。これにより、API が少し使いやすくなります。さらに良いのは、他の人が推奨しているように、application/x-www-form-urlencodedおそらくエンド ユーザーに最も馴染みのある標準形式を使用することです (例?id[]=101404&id[]=7267261)。「きれい」ではないかもしれませんが、きれいな URI は必ずしも使いやすい URI を意味するわけではありません。ただし、最初のポイントを繰り返しますが、REST について話すときは、結局のところ、それは重要ではありません。あまりそれにこだわらないでください。

  2. 複雑な検索 URI の例は、製品の例とほぼ同じ方法で解決できます。application/x-www-form-urlencodedすでに多くの人がよく知っている標準であるため、もう一度この形式を使用することをお勧めします。また、2 つをマージすることをお勧めします。

あなたの URI...

/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}

URI エンコード後の URI...

/Search?term=pumas&filters=%7B%22productType%22%3A%5B%22Clothing%22%2C%22Bags%22%5D%2C%22color%22%3A%5B%22Black%22%2C%22Red%22%5D%7D

...に変換できます。

/Product?term=pumas&productType[]=Clothing&productType[]=Bags&color[]=Black&color[]=Red

URL エンコードの必要性を回避し、見た目を少し標準化する以外に、API が少し均一化されました。ユーザーは、製品または製品のリスト (RESTful の用語では両方とも単一の「リソース」と見なされます) を取得する場合、/Product/...URI が必要であることを認識しています。

おすすめ記事