REST API - 関連するオブジェクトの詳細やIDだけを含む

Question

より優れたデザインプラクティスは何ですか？

私はオブジェクトAを持っていて、いくつかの関連オブジェクトを含んでいるとします。たとえば、私は車オブジェクトを持っていて、それはさまざまなタイプです。

は、私はちょうどそれらのリソースへのIDの持つ要求api.example.org/cars/1応答に

{ 
    "id": 1, 
    "name": "Some Car", 
    "types": [ 
     1, 
     2 
    ] 
} 

（誰かがそれらについての詳細を必要がある場合に、別のAPIコールはapi.example.org/type/1で必要）または

だけでなく、これらのリソースに関する詳細情報を提供する必要があります

{ 
    "id": 1, 
    "name": "Some Car", 
    "types": [ 
     { 
      "id": 1, 
      "name": "Some Type", 
      "something": "Blah" 
     }, 
     { 
      "id": 2, 
      "name": "Some Type", 
      "something": "Blah" 
     } 
    ] 
} 

「displayAll」のようなオプションのパラメータを指定し、1つのAPI呼び出しですべて取得する必要があるパラメータの名前を配列します（この場合はタイプ）。

Answer 1

これは、HATEOAS（アプリケーション状態のエンジンとしてのハイパーメディア）と呼ばれるRESTの基本原則の1つに当てはまります。

オブジェクトIDは、クライアントにとって無意味で無意味です。あなたは彼らと何をしていますか？検索機能にそれらを供給しますか？それらの末尾に追加して新しいURIを構築しますか？ 1-800番に電話して、彼らと何をするべきか尋ねますか？紙に印刷し、政府機関に郵送して、APIクライアントが次のステップを見つけられるようにします。

完全なURIを返すだけです。クライアントに与えられたIDは常にURIでなければなりません。それは問題のリソースを一意に識別し、それを検索、更新、または削除するために使用できます。

Answer 2

私はオプション1のパラメータのないバージョンを好みますが、タイプリソースの場所が返される場所が好きで、クライアントがそれらのリソースを取得するかどうかを選択できるようにします。

それ以外の場合は、ドキュメントをナビゲートしていません。むしろ、事前に型へのパスを知るなど、いくつかの帯域外データに頼っています。

{ 
    "id": 1, 
    "name": "Some Car", 
    "types": [ 
     { 
      "location": "api.example.org/type/1" 
     }, 
     { 
      "location": "api.example.org/type/2" 
     } 
    ] 
}