描述請求和返回數據的REST API響應

在實現之前，我正在考慮產生REST API的JSON響應結構。我在這裏經歷了許多問答，閱讀了許多文章，建議和僞標準。描述請求和返回數據的REST API響應

要求

通知客戶端的一些有用的元信息 - HTTP狀態代碼等
尋呼和過濾信息 - 偏移量，限制和過濾查詢（API客戶端知道，影響所有參數結果）。
關於數據收集的信息 - 收集中的總記錄數和返回項的數量。 API客戶端然後可以創建分頁。
鏈接到上一頁和下一頁（僅考慮，不知道這是否是可用的API客戶端，但許多REST API的連接部分使用 - 比如貝寶）

響應

這是我第一次返回搜索結果數據結構草案：

{ 
    "meta": { 
     "status_code": 200, 
     "success": true, 
     "server_time": "2017-06-29T15:24:40+0200" 
    }, 
    "request": { 
     "offset": 5, 
     "limit": 5, 
     "query": [ 
      "foo", 
      "bar" 
     ] 
    }, 
    "response": { 
     "count": 5, 
     "total_count": 754, 
     "data": [ 
      { 
       "id": "88b60cc6-70bc-4b1a-8f26-c919355d47d3", 
       "name": "Name of entity 1" 
      }, 
      { 
       "id": "2f4ccda5-11bc-4ef7-b663-30c506f5118c", 
       "name": "Name of entity 2" 
      }, 
      { 
       "id": "1333f2fe-a958-474e-9a82-8b343fda3aff", 
       "name": "Name of entity 3" 
      }, 
      { 
       "id": "f5187143-f3b8-412b-a416-1e3a5830baee", 
       "name": "Name of entity 4" 
      }, 
      { 
       "id": "2dd17750-bbdf-460a-abec-1f74e1170726", 
       "name": "Name of entity 5" 
      } 
     ] 
    }, 
    "links": { 
     "previous": { 
      "href": "http:\/\/api.example.com\/envelopes?offset=0&limit=5", 
      "rel": "previous", 
      "method": "GET" 
     }, 
     "self": { 
      "href": "http:\/\/api.example.com\/envelopes?offset=5&limit=5", 
      "rel": "self", 
      "method": "GET" 
     }, 
     "next": { 
      "href": "http:\/\/api.example.com\/envelopes?offset=10&limit=5", 
      "rel": "next", 
      "method": "GET" 
     } 
    } 
}

我想避免一個「意見問題」來討論最合適的JSON結構。我看到很多關於信封的意見，有些服務/標準是它推薦的，有些則不是。

問題：

是它在這個結構中返回結果好主意嗎？
你看到這個結構有些問題嗎？做什麼更好？
您是否看到API客戶端需要的一些缺失值？一些不必要的值？
是否需要返回URL到self？

來源

2017-06-29 Artegon

爲什麼您將請求的成功作爲元信息返回？無論如何，這應該在HTTP響應標頭中可用。我不確定請求參數是否有用，因爲客戶希望知道她要求什麼。響應元素也是多餘的：返回的數據顯然是一個響應，因此使用不需要的數據增加響應。鏈接部分的關係名已由JSON元素覆蓋。額外的'rel'字段因此也是多餘的。如果您應用所有建議，則您的方法與JSON-HAL類似 –

意見問題很難，但我會嘗試。

首先，您的問題不應針對社區，而應針對客戶本身。沒有任何東西比這種反饋更清楚地表明丟失/必要值的假設。

結構本身就夠好了，至少作爲一個草稿。在設計響應時，你需要記住你基本上鎖定自己，因爲客戶不喜歡API的根本變化。只有很多增量「請在此添加一個字段」。你在思考方面做得很好，關於元場，分頁和分離實際響應，但不要認爲你可以預測一切。你不會的。也許看起來像HAL或JSON Collection。至少作爲一個啓發。

API的設計最終是漸進式的，主要是客戶端驅動的過程。所以和你的客戶談談。

來源

2017-06-29 15:55:45

描述請求和返回數據的REST API響應

回答

相關問題