ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-605] CloudEvents Media Type ​

Guidance ​

  • MUST specify media type as application/cloudevents+json when available.
    • In RESTful APIs, this is done via the Content-Type header.
      • If the response is an event instance of CloudEvents, add Content-Type: application/cloudevents+json in the response header.
      • If the request is to publish/create a CloudEvents-based event, add Content-Type: application/cloudevents+json in the request header.
  • SHOULD implement content negotiation on the event consumer side to support different media types.
  • MAY support other media types such as application/json, but application/cloudevents+json should be preferred.

Examples ​

Response Example ​

http
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
  }
}

Request Example ​

http
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!"
}

Implementation Recommendations ​

  1. Clearly specify supported media types in API documentation.
  2. Implement proper error handling, returning a 415 Unsupported Media Type status code for unsupported media types.
  3. Consider implementing content negotiation, allowing clients to request specific media types via the Accept header.
  4. Ensure correct parsing and validation of JSON structures when handling CloudEvents.

Security Considerations ​

  1. Validate received CloudEvents data to prevent injection attacks.
  2. Implement appropriate access controls to ensure only authorized clients can send and receive events.
  3. Consider using HTTPS to encrypt event data transmission.

References ​