[ADE-605] CloudEvents 媒體類型

指導原則

• 必須(MUST)在可用時將媒體類型指定為 application/cloudevents+json。
  • 在 RESTful API 中，通過 Content-Type 標頭完成。
    • 如果回應是 cloudevents 的事件實例，在回應標頭中添加 Content-Type: application/cloudevents+json
    • 如果請求是發布/創建基於 cloudevents 的事件，在請求標頭中添加 Content-Type: application/cloudevents+json
• 應該(SHOULD)在事件消費者端實施內容協商，以支持不同的媒體類型。
• 可以(MAY)支持其他媒體類型，如 application/json，但 application/cloudevents+json 應該是首選。

示例

回應示例

GET /event/{event-id} HTTP/1.1

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

{
  "specversion": "1.0",
  "type": "com.example.someevent",
  "source": "/mycontext",
  "id": "A234-1234-1234",
  "time": "2018-04-05T17:31:00Z",
  "comexampleextension1": "value",
  "datacontenttype": "application/json",
  "data": {
    "appinfoA": "abc",
    "appinfoB": 123,
    "appinfoC": true
  }
}

請求示例

POST /events HTTP/1.1
Content-Type: application/cloudevents+json

{
  "specversion": "1.0",
  "type": "com.example.someevent",
  "source": "/mycontext",
  "id": "C234-1234-1234",
  "time": "2018-04-05T17:31:00Z",
  "datacontenttype": "text/plain",
  "data": "Hello, World!"
}

實施建議

1. 在 API 文件中明確指定支持的媒體類型。
2. 實施適當的錯誤處理，對不支持的媒體類型返回 415 Unsupported Media Type 狀態碼。
3. 考慮實施內容協商，允許客戶端通過 Accept 標頭請求特定的媒體類型。
4. 在處理 CloudEvents 時，確保正確解析和驗證 JSON 結構。

安全性考慮

1. 驗證接收到的 CloudEvents 數據以防止注入攻擊。
2. 實施適當的訪問控制，確保只有授權的客戶端可以發送和接收事件。
3. 考慮使用 HTTPS 來加密事件數據的傳輸。

參考資料

• CloudEvents 規範
• CloudEvents JSON 格式
• HTTP 1.1 規範 - 內容協商