ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-602] CloudEvents ​

Overview ​

This specification aims to guide the design and implementation of RESTful API events to ensure compatibility with the CNCF CloudEvent standard. CNCF CloudEvent is a lightweight specification for describing event data to promote interoperability in event-driven systems. The use of "SHOULD" in this specification indicates a strong recommendation, though exceptions may be permissible in certain situations.

Context Attributes ​

CloudEvents defines a set of metadata to describe events, known as context attributes. These attributes fall into two categories:

  • Core Attributes
  • Extension Attributes

Core Attributes vs Extension Attributes ​

Roles ​

  • Event Producers
  • Event Consumers
  • Event Routers

Guidance ​

  • All RESTful API events SHOULD adhere to the CNCF CloudEvent standard structure, including core attributes and appropriate extension attributes.
  • MUST Follow CloudEvents Type Convention
  • MUST Specify Media Type if Available**: See CloudEvents Media Type Specification
  • SHOULD Follow CloudEvents Source Convention
  • CloudEvents Field Principles:

    • MUST Specify specversion as 1.0

    • MUST Provide a Unique ID: Ensure the ID is unique within the entire system.

    • MUST Provide Time: Specify the occurrence time or the current time (MUST be consistent across the system). When provided, use the RFC3339 date format. See CloudEvents Time Specification

    • SHOULD Provide Subject: Include a subject regarding the event.

      :::tip
💡 There's no strict rule for `subject` in the original CloudEvents spec. It could be a non-empty string. Document what you'd put in the subject well.
:::

Examples ​

Example 1: Basic CloudEvent ​

http
Content-Type: application/cloudevents+json

{
  "specversion": "1.0",
  "type": "com.vivotek.user.created",
  "source": "/mycontext",
  "id": "A234-1234-1234",
  "time": "2020-08-14T14:48:09Z",
  "datacontenttype": "application/json",
  "data": {
    "object": {
      "id": "123",
      "name": "Sample Object"
    }
  }
}

This example represents a basic CloudEvent indicating that an object was created. It includes standard attributes such as specversion, type, source, id, time, datacontenttype, and data.

Example 2: CloudEvent with Extensions ​

json
{
  "specversion": "1.0",
  "type": "com.example.file.uploaded",
  "source": "/mycontext",
  "id": "B234-1234-1234",
  "time": "2020-08-14T14:48:09Z",
  "subject": "user/123/file/456",
  "datacontenttype": "application/json",
  "data": {
    "file": {
      "id": "456",
      "name": "example.txt",
      "size": "1024"
    }
  },
  "traceparent": "00-abcd1234abcd1234abcd1234abcd1234-01",
  "tracestate": "congo=congospecificinfo"
}

This example extends the basic CloudEvent by including additional attributes like traceparent and tracestate. These provide more context about the event and include tracing information to support observability.

Example 3: Transmitting CloudEvent over HTTP ​

http
POST /events HTTP/1.1
Host: example.com
Content-Type: application/cloudevents+json
Content-Length: 400

{
  "specversion": "1.0",
  "type": "com.example.user.updated",
  "source": "/mycontext",
  "id": "C234-1234-1234",
  "time": "2020-08-14T14:48:09Z",
  "datacontenttype": "application/json",
  "data": {
    "user": {
      "id": "123",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  }
}

In this example, a CloudEvent is transmitted over HTTP using the POST method. The request header specifies Content-Type: application/cloudevents+json, and the request body contains the event data.

Reference ​

Design References ​