REST APIのベストプラクティス：クエリ文字列とリクエスト本文の引数

REST APIは、いくつかの場所で引数を持つことができます。

1. リクエストボディ -jsonボディ、またはその他のMIMEタイプの一部として
2. では、クエリ文字列 -たとえば、/api/resource?p1=v1&p2=v2
3. URLパスの一部として -例/api/resource/v1/v2

上記の1と2の間で選択する場合のベストプラクティスと考慮事項は何ですか？ここで
は2対3について説明します。

上記の1と2の間で選択する場合のベストプラクティスと考慮事項は何ですか？

通常、コンテンツの本文はサーバーにアップロードまたはサーバーからダウンロードするデータに使用され、クエリパラメーターは要求された正確なデータを指定するために使用されます。たとえば、ファイルをアップロードするときは、本文で名前、MIMEタイプなどを指定しますが、ファイルのリストをフェッチするときは、クエリパラメータを使用して、ファイルのいくつかのプロパティでリストをフィルタリングできます。一般に、クエリパラメータはデータではなくクエリのプロパティです。

もちろん、これは厳密な規則ではありません。あなたにとってより適切で機能している方法で実装することができます。

また、クエリ文字列に関するウィキペディアの記事、特に最初の2つの段落を確認することもできます。

POST / PUTリクエストについて話していると思います。意味的には、リクエストの本文には、投稿またはパッチを適用するデータを含める必要があります。

クエリ文字列は、URL（URI）の一部として、投稿またはパッチを適用するリソースを識別するために存在します。

次のセマンティクスは私のものです。もちろん、経験則を使用しても機能するはずです。特に、使用するWebフレームワークがこれをパラメーターに抽象化する場合はそうです。

あなたは最も知っています：

• 一部のWebサーバーでは、URIの長さに制限があります。
• CURLを使用して、リクエストの本文内にパラメータを送信できます。
• データの送信先はデバッグに影響を与えません。

以下は私の経験則です...

ボディをいつ使用するか：

• 引数にフラットなkey：value構造がない場合
• シリアル化されたバイナリデータなど、値が人間が読み取れない場合
• 引数が非常に多い場合

クエリ文字列を使用する場合：

• 引数がデバッグ中に確認したい場合
• コードの開発中に手動で呼び出すことができるようにしたい場合、例えば curl
• 引数が多くのWebサービスで共通している場合
• 次のような別のコンテンツタイプをすでに送信している場合 application/octet-stream

混合して一致させることができます-一般的なもの、デバッグ可能なものをクエリ文字列に入れ、残りをすべてjsonにスローします。