[ADP-316] 回應:主要類型

reviewing phase 1

解釋使用 JSON 擴展的優點

指導原則

• 必須(MUST)使用 JSON 作為 API 回應的主要類型，除非該 API 是為二進制數據傳輸而設計。自定義JSON媒體類型也是可以接受的。
• 必須(MUST)使用適當的 Content-Type 標頭來指示回應格式。
• 應該(SHOULD)盡可能使用標準媒體類型，如 IANA 媒體類型註冊表中定義的。
• 可以(MAY)為專門的 JSON 回應使用自定義媒體類型，遵循application/vnd.{組織}.{類型}+json的格式。

範例

標準JSON回應

應該:

GET /term-of-service HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "term-of-service": "在我們的服務中..."
}

不應該:

GET /term-of-service HTTP/1.1

HTTP/1.1 200 OK
Content-Type: text/plain

在我們的服務中...

自定義JSON媒體類型

可以使用自定義JSON媒體類型來更精確地指定JSON回應的性質。

範例:

GET /user/profile HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.myapp.user-profile+json

{
  "id": 12345,
  "name": "張三",
  "email": "zhangsan@example.com"
}

二進制數據傳輸

如果API是為二進制數據傳輸而設計的，例如下載圖片或文件，回應應使用適當的二進制Content-Type。

範例:

GET /download/image HTTP/1.1

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="image.png"

(二進制數據)

最佳實踐

1. 在整個API中保持媒體類型的一致使用。
2. 使用自定義媒體類型時，考慮納入版本資訊(例如，application/vnd.myapp.v1+json)。
3. 在API文件中清楚地記錄所有支持的媒體類型。
4. 實施適當的內容協商以處理來自客戶端的不同Accept標頭。

相關ADPs

• ADP-24: 版本控制機制
• ADP-359: 資源擴展
• ADP-751: 新的OpenAPI文件
• ADP-353: 內容協商

參考資料

• IANA媒體類型
• RFC 6838: 媒體類型規範和註冊程序
• RFC 7231: HTTP/1.1語義和內容