web-dev-qa-db-ja.com

設計：RESTfulなリソースベースのAPIでエンティティのプロパティを更新する

私はRESTfulなリソースベースのAPIに取り組んでおり、多くのプロパティ（30と言います）を持つ大きなエンティティ（アカウント）を持っています。アカウントには、変更可能ないくつかのプロパティがあります...

  1. 名前：これは、本人確認のためのリクエスト（電子メール）を実際に送信し、別のシステムを使用して名前を更新します。

  2. 目標節約額：クライアントが希望する金額に更新できるのは単なる数値です。

だから、ここに私の考えがありました、そしてなぜ私はそれらを好きではありません：

1. PATCHをマージする

  • パッチ.../account/{id}

私は、パッチボディのアカウントエンティティを取得して、何が変更されたかを更新します...この場合、2つのプロパティ（name/savings-target）と他の変更のみを含めることができます。

  • 非常にシームレスにGET> Modify> PATCHを実行できるため、気に入っています。
  • マージパッチのこのような小さな変更面はあまり意味がないので、私はそれが好きではありません。名前の更新が有効にならないため、名前とSavings-targetを同時に更新すると、あいまいな応答になります。

2. POSTアップデート

  • POST .../account/{id}/updates/name？value = test
  • POST .../account/{id} /updates/savings-target?value=123.00

更新をエンティティとして扱い、新しい更新をアカウントに投稿します。

  • 一貫性があり、クリーンで、応答を異なる方法で処理できるため、気に入っています（名前の更新では、204などの遅延応答のようなものを返し、savings-targetには200を返します）。
  • RPC風のAPIに陥っているように感じるので、私はそれを嫌いです。 GETへの更新がないため、更新をエンティティとして扱うのは厄介に思えます。また、更新可能なフィールドを追加してしまうと、これは非常に醜くなります。

3.実際の更新エンティティ

  • POST .../account/{id}/updates
    • おそらく単なるキーと値のペアであるボディを取り、参照する303を返します...
  • GET .../account/{id}/updates/{update-id}
  • GET .../account/{id}/updates
    • このアカウントエンティティに対して作成されたすべての更新を返すことができる有効なエンドポイント

基本的には2つですが、更新用の実際のエンティティがあり、CQRSを更新しています。更新エンティティ（現時点ではより適切な名前がないため）には、変更が完了したかどうかを示すステータスがあります。

  • 変更を最も正確にモデル化しているので、気に入っています。
  • ヘビー級のソリューションなので、気に入らない。 Savings-Targetのような些細な変更の場合、アカウントエンティティを更新してすぐに更新エンティティを完了することができますが、名前などの場合、実際に更新エンティティにコールバックしてそれを完了するシステムはありません。

それはやり過ぎのボートの負荷のようであり、よりきれいなAPIを用意するだけの多くの作業です。また、通常そのタイプのアーキテクチャを保証するスループットの懸念もありません。

4. JSONパッチ

見ての通り here

  • 標準であり、実装も比較的簡単なので、気に入っています。
  • 私が開発しているAPIのリソースベースのフォーカスに反するため、私はそれが好きではありません（これはビジネスからの要件です...）。

助けて

私はこれらの4つの選択肢に制限されていませんが、私が考えることができる最良の選択肢です。私は2に傾いており、検証されるか、同様の状況に遭遇した他の誰かから経験ベースのソリューションを与えられることを望んでいます。

designrestapiapi-design
4
Steven Evers

マイクロエンドポイントの使用を検討してください。次の追加のエンドポイントを公開できます。

/accounts/{id}/name
/accounts/{id}/savings-target

名前でPOSTを有効にして、目標節約額でPUTを有効にすることができます。エンドポイントでJSONをサポートする必要すらありません。POST to単純な文字列（電子メールアドレス）を指定すると、新しいターゲット金額をPUTできます。アカウントエンドポイントの応答には、nameおよびsavings-targetプロパティを含めることができます。

2
Eric Stein