diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml new file mode 100644 index 00000000..5a44e4c8 --- /dev/null +++ b/artifacts/notification-as-cloud-event.yaml @@ -0,0 +1,287 @@ +openapi: 3.0.3 +info: + title: Event Notification using CloudEvents specifications + description: | + The event notification endpoint is used by the API server to notify the API consumer that an event occurred. The notification is the message posted on listener side. + + # Introduction + + A lot of CAMARA APIs offer the capability to API consumer to receive events. + Event data are defined in each API definition but in order to provide consistency across CAMARA APIs and to increase + interoperability we will use [cloudevents](https://cloudevents.io/) specifications. In particular, every CAMARA Event will + be defined using [cloudevents-json-format](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md) + + # Relevant terms and definitions + + * **Occurrence** : An "occurrence" is the capture of a statement of fact during the operation of a software system. + + * **Event**: An "event" is a data record expressing an occurrence and its context. Events are routed from an + event producer (the source) to interested event consumers. + + * **Producer**: The "producer" is a specific instance, process or device that creates the data structure + describing the CloudEvent. + + * **Source**: The "source" is the context in which the occurrence happened. In a distributed system it might + consist of multiple producers. If a source is not aware of CloudEvents, an external producer creates + the CloudEvent on behalf of the source. + + * **Consumer**: A "consumer" receives the event and acts upon it. It uses the context and data to execute some + logic, which might lead to the occurrence of new events. + + * **Data**: Domain-specific information about the occurrence (i.e. the payload). This might + include information about the occurrence, details about the data that was changed, or more. + + # API Functionality + + Only one endpoint/operation is provided: `POST /your_webhook_notification_url` + This endpoint describes the event notification received on subscription listener side when the event occurred. A detailed description of the event notification is provided in the CAMARA API design guideline document. + + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 0.1.0 +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/ +security: + - notificationsBearerAuth: [] + - {} + +servers: + - url: '{apiRoot}' + variables: + apiRoot: + default: https://localhost:8080 + description: Can be any notification server address sent by the client application +tags: + - name: Cloud Event + description: | + Events received on subscription listener side. +paths: + /your_webhook_notification_url: + post: + tags: + - CAMARA Cloud Event notification endpoint + summary: "Cloud Event notification endpoint to notify consumer that statement of fact had occurred" + description: | + INFORMATIVE ENDPOINT: The value of this endpoint is freely declared by each client app by means of resource-based + subscription or instance-based subscription. /your_webhook_notification_url is + just a convention naming referring to an absolute URL, indeed the one indicated by API client + in the triggering of the procedure (resource-based or instance-based). In this way, it represents an absolute + URL, i.e.: notifications won't be sent to /event-notification/vX/your_webhook_notification_url. + operationId: sendEvent + requestBody: + required: true + content: + application/cloudevents+json: + schema: + $ref: "#/components/schemas/CloudEvent" + examples: + QOS_STATUS_CHANGED_EXAMPLE: + $ref: '#/components/examples/QOS_STATUS_CHANGED_EXAMPLE' + + responses: + 201: + description: Created + 202: + description: Accepted + 204: + description: No Content + 200: + description: Ok + content: + application/json: + schema: + type: object + 400: + $ref: "#/components/responses/Generic400" + 401: + $ref: "#/components/responses/Generic401" + 403: + $ref: "#/components/responses/Generic403" + 410: + $ref: "#/components/responses/Generic410" + 415: + $ref: "#/components/responses/Generic415" + 429: + $ref: "#/components/responses/Generic429" + 500: + $ref: "#/components/responses/Generic500" + 503: + $ref: "#/components/responses/Generic503" +components: + securitySchemes: + notificationsBearerAuth: + type: http + scheme: bearer + bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + schemas: + ErrorInfo: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + + DateTime: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. Must adhere to RFC 3339. + WARN: This optional field in CloudEvents specification is required in CAMARA APIs implementation. + example: '2018-04-05T17:31:00Z' + + Source: + type: string + format: uri-reference + minLength: 1 + description: | + Identifies the context in which an event happened - be a non-empty `URI-reference` like: + - URI with a DNS authority: + * https://github.com/cloudevents + * mailto:cncf-wg-serverless@lists.cncf.io + - Universally-unique URN with a UUID: + * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - Application-specific identifier: + * /cloudevents/spec/pull/123 + * 1-555-123-4567 + example: "https://notificationSendServer12.supertelco.com" + + CloudEvent: + description: The notification callback + required: + - id + - source + - specversion + - type + - time + properties: + id: + type: string + description: identifier of this event, that must be unique in the source context. + minLength: 1 + source: + $ref: '#/components/schemas/Source' + type: + type: string + description: 'type of event as defined in each CAMARA API (e.g.: org.camaraproject.qod.qos-status-changed-event)' + example: 'org.camaraproject.qod.qos-status-changed-event' + minLength: 25 + specversion: + type: string + description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) + minLength: 3 + datacontenttype: + type: string + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + data: + type: object + description: Event details payload described in each CAMARA API and referenced by its type + time: + $ref: "#/components/schemas/DateTime" + + responses: + Generic400: + description: Problem with the client request + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 400 + code: "INVALID_ARGUMENT" + message: "Client specified an invalid argument, request body or query param" + Generic401: + description: Authentication problem with the client request + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: "UNAUTHENTICATED" + message: "Request not authenticated due to missing, invalid, or expired credentials" + Generic403: + description: Client does not have sufficient permission + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 403 + code: "PERMISSION_DENIED" + message: "Client does not have sufficient permissions to perform this action" + Generic410: + description: Gone + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: GONE + message: "Access to the target resource is no longer available." + Generic415: + description: Unsupported Media Type + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: UNSUPPORTED_MEDIA_TYPE + message: "The specified media type is not supported" + Generic429: + description: Too Many Requests + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: TOO_MANY_REQUESTS + message: "Endpoint does not support as many requests per time slot" + Generic500: + description: Server error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 500 + code: "INTERNAL" + message: "Server error" + Generic503: + description: Service unavailable. Typically the server is down. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: "UNAVAILABLE" + message: "Service unavailable" + examples: + QOS_STATUS_CHANGED_EXAMPLE: + value: + id: "123e4567-e89b-12d3-a456-426655440000" + source: "https://notificationSendServer12.supertelco.com" + type: "org.camaraproject.qod.qos-status-changed-event" + specversion: "1.0" + time: "2023-01-17T13:18:23.682Z" + datacontenttype: "application/json" + data: + sessionId: "6e8bc430-9c3a-11d9-9669-0800200c9a66" + qosStatus: UNAVAILABLE + statusInfo: DURATION_EXPIRED +