オブジェクトグラフを更新するためのREST APIの設計

Question

私はREST APIを設計しており、オブジェクトグラフを更新するための推奨されるベストプラクティスを探しています。私の質問は、最良の例で説明されて、それでは、次のように私がGETリソースを持っているとしましょう：

URI：/人/ 123

このURIは、このようなオブジェクトグラフを返します。

{ 
    "name":"Johnny", 
    "country":{"id":100,"name":"Canada"}, 
    "likes":[ 
     {"id":5,"name":"Fruit"}, 
     {"id":100,"name":"Sports"} 
    ] 
} 

APIコンシューマーがこのリソースを更新できるようにするとき、オブジェクトをPUTまたはPATCH経由でどのように更新すると思いますか？ 「名前」プロパティを更新するのはかなり簡単ですが、消費者は他のオブジェクトとの関係を変更するだけで新しいものを作成することはできないため、「国」や「好き」についてはわかりません。ここで

が更新を要求する一つの方法です：

{ 
    "name":"Bob", 
    "countryId":200 
    "likeIds":[3,10,22] 
} 

このアップデートは、次のリソースを変更します：

{ 
    "name":"Bob", 
    "country":{"id":200,"name":"United States of America"}, 
    "likes":[ 
     {"id":3,"name":"Cars"}, 
     {"id":10,"name":"Planes"}, 
     {"id":22,"name":"Real Estate"} 
    ] 
} 

この設計は、明示的に、はっきりのみ」を更新するために、消費者に依頼しますPUT/PATCHのオブジェクトグラフがGETと違って見えてしまい、APIを覚えて覚えがたくなってしまうのではないかと心配しています。したがって、次のようにPUT/PATCHを要求することもできます。

{ 
    "name":"Bob", 
    "country":{"id":100}, 
    "likes":[ 
     {"id":3}, 
     {"id":10}, 
     {"id":22} 
    ] 
} 

これにより、前回と同じ変更が行われ、オブジェクトグラフは変更されません。ただし、「ID」のみを更新できることをAPIコンシューマーに明確にするものではありません。

このシナリオでは、どの方法をお勧めしますか？

Answer 1

私の意見では、GETとPUTの両方のリクエストに対して同じ構造をとどめておくべきです。どうして？ JSON/XMLデータをオブジェクトにマップするのは非常に一般的なので、JSONスキーマが常に同じ場合は、実際のマッピングを行うほとんどのソフトウェア（すべてではないにしても）が最も効果的です。

だからあなたのWebサービスはに、次のJSONコード受け入れる必要があります。それは考慮に国名を取る必要がないとは唯一の国IDに焦点を合わせることができるしかし

{ 
    "name":"Joe", 
    "country":{"id":200,"name":"United States of America"}, 
    "likes":[ 
     {"id":5,"name":"Fruit"} 
    ] 
} 

を。