[ADP-304] 集合的複數形式

指導原則

• 在URI中表示集合(即特定資源的多數型態)時，應該(SHOULD)使用複數形式。

  GET /features HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    "features": [
      {
        "name": "WebRTC"
      }
    ]
  }

• DRAFT 對於與特定資源無關的搜索相關API，其回應欄位應該使用results作為欄位名稱。

  POST /search HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    "results": []
  }

• 對於表示動作或命令而非資源集合的端點，應該使用單數形式。

• 對於無法以複數型態表示的單體資源，應該使用單數形式。

  GET /home-appliances/{id}/config

設計思路

對集合使用複數形式是 REST API 最常見的慣例之一。

示例

正確做法:

GET /planets/earth HTTP/1.1
GET /api-guidelines HTTP/1.1
POST /apis HTTP/1.1

錯誤做法:

GET /api HTTP/1.1

參考

設計參考

• https://api.otto.de/portal/guidelines/r100020
• Google AIP-156: Singleton Resource