ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-603] CloudEvents Type Conventions ​

Guidance ​

  • MUST use namespaced events

  • MUST reverse domain names

  • MUST follow the naming convention

    json
    com.vivotek[.applicationId].resourceType.eventVersioning.eventInPastTense
    • The applicationId part is optional; it can be omitted if the resourceType part is guaranteed to be unique under the (reversed) domain name

  • MAY use application specific domain without applicationId

    json
    com.vortexcloud.resourceType.eventVersioning.eventInPastTense

  • Event versioning SHOULD follow semantic versioning

  • SHOULD register and manage resource types in a centralized registry

  • SHOULD register and manage the overall event type in a centralized registry

  • SHOULD use past tense for event names.

  • SHOULD be in camelCase.

Examples ​

Here are some examples of event types that adhere to the above guidelines:

  1. Basic event type:

    http
    com.vivotek.camera.v1.recorded

  2. Event type with application ID:

    http
    com.vivotek.vms.user.v1.created

  3. Event type with semantic versioning:

    http
    com.vivotek.accesscontrol.door.v2.1.opened

OpenAPI Example ​

Here's an example using OpenAPI 3.0 to describe the CloudEvents type conventions:

yaml
components:
  schemas:
    CloudEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          pattern: '^com\.vivotek(\.[a-z0-9]+)*\.[a-z0-9]+\.v\d+(\.\d+){0,2}\.[a-z]+$'
          example: 'com.vivotek.camera.v1.recorded'
        source:
          type: string
          format: uri-reference
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object

paths:
  /events:
    post:
      summary: Publish a CloudEvent
      requestBody:
        content:
          application/cloudevents+json:
            schema:
              $ref: '#/components/schemas/CloudEvent'
      responses:
        '201':
          description: Event published successfully
        '400':
          description: Invalid event format

Notes ​

  • When designing new event types, it is recommended to consider existing event types to avoid unnecessary duplication or confusion.

  • Periodically review and update the event type conventions to ensure they continue to meet system requirements.

  • [Draft] Consider establishing a centralized event type registry to make it easy for team members to find and understand existing event types.

References ​