web-dev-qa-db-ja.com

REST Web Services（post / put）：どのタイプのパラメータをいつ選択する必要がありますか？

POST（またはPUT）Webサービスでは、3つの異なるタイプのパラメーターを使用できることがわかっています。疑問符の後に、URL/objects/{path_param}のパスでパラメーターを送信できます。 URL/objects？{param_name} = {Param_value}またはリクエストの本文。

GET Webサービスの場合、パスを使用してリソースを識別し、クエリを使用してリソースがリストの場合にフィルターを追加します。

私の主な質問は、「いつPOST/PUT Webサービスでパス/クエリ/ボディを使用することを選択すべきですか？」です。これに基づいて、クエリパラメータと本文パラメータの両方を同じWebサービスに含めることは許容されますか？

現時点では、クエリパラメータと本文パラメータの唯一の違いは、クエリパラメータをURLの一部として送信できるため、ブラウザの履歴にキャッシュまたは保持できるため、他の違いを知りたいのですが考慮に入れてください。

resthttpparametershttp-request
4
gvo

REST API over HTTP 1.1

これらは、（=）/RESTful準拠になりたい場合に考慮すべき「原則」です。他の多くのものの間で（ CoRE RFC669 も参照）

パス変数

これらの変数は、階層内のreferencingリソースに使用されます。 （メソッドから独立して）

GET: /app/{appId}/user/{userId} #single resource
GET: /app/{appId}/users #collection
POST: /app/{appId}/user/{userId}
DELETE: /app/{appId}/user/{userId}
...

クエリ変数

これらの変数は、応答の修飾子として使用されます。修飾子とは、filters、pagination、attribute selectionなどです。

GET: /app/{appId}/users # all app users

応答の変更：

  GET: /app/{appId}/users?name=Jhon&surname=Conor # Subset by filtering
  GET: /app/{appId}/users?page=1&pageSize=10 # Subset by pagination
  GET: /app/{appId}/users?page=1&pageSize=10&filter=name:jhon;surname:conor # Subset by pagination and filtering

AppIdは引き続き参照用に機能しています。 （アプリXのユーザー）を確認するスコープ/コンテキストを提供します。この値を変更すると、応答は変更されません。リソースを切り替えます。

これらの変数は、リソースのサブセットに対してこれらのアクションを実行するためにPUT、POST、DELETEで使用できますが、OPの言葉では

ユースケースは理論的には可能だと思いますが、実際には非常にまれです。

（そして私は同意しました）

ボディ変数

独断的であるため、POST tocreatenew resources、and PUT to既存のものを変更します。

どちらもリクエストボディが必要です。リクエストボディでは、作成/更新するリソースが最終ステータスで表されます。

注：ここでは、それらの べき等数 性質を参照することが重要です

POST: /app/{appId}/user
BODY: {"name":"Jhon", "surname":"Conor"}
PUT: /app/{appId}/user/{userId}
BODY: {"name":"Sara", "surname":"Conor"}

繰り返しますが、appIdおよびuserIdは単なる参照変数です。

まとめ

  • パス変数：参照用（リソースナビゲーション）
  • クエリ変数：応答変更用
  • 本文：リソースの作成または変更用。

ここに仕様： RFC72 - RFC7235

SOAP Webservices over HTTP 1.1

SOA WSをAPI RESTfulから分離しました。これらは2つの異なる設計であり、それぞれが前述のHttp変数を異なる仕方。

これらのWSは、Webリソースの参照にURIを使用しません。それらを使用して、プロシージャを公開します。

POST: /app/register
Body:  {"name":"Jhon", "pass":"Conor"}
POST: /app/sendNotification
Body:  {"from":"Jhon", "to":"skynet", text:"see you yesterday"}
POST: /app/markNotificationAsRead
Body:  {"id":"0"}
POST: /app/moveNotifications
Body:  {"from":"inbox", "to":"trash", messages:[]}
GET: /app/notifications?from=Jhon
GET: /app/notifications?if=from:Jhon;to:skynet

このアプローチでは、GETとPOSTが主流です。

Pathおよびbody変数はプロシージャの引数。

Query変数はresponse modificatorの機能を保持します。

実装する仕様は、システムのニーズによって異なります。 @Ericが指摘したように、この種のWebサービスに適用できる [〜＃〜] rpc [〜＃〜] のような仕様があります。

4
Laiv

HTTP（RFC 7230-7235）の設計により、各エンドポイントはサーバーが追跡しているものを表し、通常はResourceと呼ばれます。そのリソースは、単一のウィジェットのように1つだけの場合もあれば、グループ（またはウィジェット）のグループの場合もあります。 URIは、ウィジェットまたはウィジェットのグループを一意に指定するためのものです。

ほとんどのAPIは、人間が読める名前とIDを使用して、URIでこれらを識別します。一部のセキュリティ志向のサービスは、サービスが必要としない情報をエンドユーザーに公開するため、これを行いません。人間が読めるAPIの中で、集まりはコレクションを示すために複数の名詞を使用するようになりました。これらはネストすることができます-個々のアイテム自体が、直接公開したいコレクションまたは個々のアイテムのいずれかを持つ場合があります。そう：

/widgets               > all the widgets the user can see
/widgets/12            > a specific widget
/widgets/12/texture    > a widget has zero or one textures
/widgets/12/colors     > a widget has zero or more colors
/widgets/12/colors/5   > color #5 of widget #12

上記のアプローチは通常RESTfulと呼ばれますが、RESTはそれだけではありません。他の一般的なアプローチはRemote Procedure Calls、または略してRPCと呼ばれます。 RPCでは、エンドポイントは/writeEndOfYearCsvなどのサーバーへの指示を表します。クライアントがPOSTを使用してそのURLを呼び出す場合、応答は年末レポートを含むCSVファイルをストリーミングする可能性があります。 RPCは、時間の経過とともに維持することが困難であると考えられているため、人気が衰えています。適切に記述されたRPCは、POSTおよびGET呼び出しのみを使用します。

RFC 3986 で定義されるクエリパラメータは、URIへの応答の詳細を絞り込むために使用されます。コレクションの内容を絞り込むために、/widgets?shape=roundなどの「コレクションリソース」で最もよく使用されます。通常、これらは、応答の作成方法に関する情報をサーバーに提供するために使用されます。

たとえば、/widgets/12?expand=textureはテクスチャ情報が埋め込まれたウィジェットリソースを返し、/widgets/12はウィジェットの直接プロパティのみを返します。テクスチャを気にしないクライアントはそれを取得する必要はありません。気にするクライアントは、リンクだけでなく情報を埋め込むことでサーバーのヒットを節約できます。

RPCでは、ほぼ同じことに対してクエリパラメータを使用します。POST /writeEndOfYearCsv?format=csvはCSVレポートを提供し、POST /writeEndOfYearCsv?format=xslxはExcelレポートを提供します。

リクエストの本文には通常、作成または変更されるリソース（RESTishアプローチを使用している場合）、またはリクエストの処理方法の説明（RPCを使用している場合）が含まれますアプローチ）。したがって、ウィジェットを作成または更新するとき、リクエストにはウィジェットを構成するものに関するすべての情報（色、テクスチャ、名前など）が含まれます。年末のレポートを要求する場合、要求には要求の年、クライアントがレポートに含めるなどが含まれる場合があります。

RESTishシステムでRPCスタイルのリクエストを使用することはまだ可能です。リクエスト自体をリソースとして考える必要があるだけです。したがって、本文を含むPOST /reports/end-of-yearを使用すると、新しいレポートが作成され、後でそのレポートを表示するためにGET /reports/end-of-year/9を実行できます。

RPCスタイルのリクエストが「属する」場所の点で線を大きくぼかしているように見える場合、それはそれらがそうしているためです。 HTTPは「URL-as-resource」パラダイムを中心に設計されており、RPCはその上に絞り込まれているため、特定の命令の適切な場所を見つけるのは個々の開発者次第です。 RPCを使用している場合（そして一般的には使用しないようにする必要があります）、一般的なルールを理解し、サービス内で何がどこにあるかについて一貫しているようにします。

リクエストまたはレスポンスの本文は通常、リクエストのtypeに依存します。 RESTでは、本体と応答は常にリソース表現ですが、そのリソースが実際に指示である場合もあります。するでしょう

2
Eric Stein