From c8945a37f6437e2eef3011f48a7d8f7ee68365ac Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 18 Apr 2024 18:14:38 +0200 Subject: [PATCH 01/68] Create subscription-notification-template.yaml Create subscription-notification-template.yaml aligned with CloudEvents subscription model. Refer to https://github.com/camaraproject/Commonalities/issues/185 --- .../subscription-notification-template.yaml | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 artifacts/camara-cloudevents/subscription-notification-template.yaml diff --git a/artifacts/camara-cloudevents/subscription-notification-template.yaml b/artifacts/camara-cloudevents/subscription-notification-template.yaml new file mode 100644 index 00000000..bcec4412 --- /dev/null +++ b/artifacts/camara-cloudevents/subscription-notification-template.yaml @@ -0,0 +1,759 @@ +openapi: 3.0.3 +info: + title: Notification Subscription Template + description: | + This file is a template for CAMARA explicit subscription template and for Notification model. Additional information are provided in API Design guidelines 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-wip +externalDocs: + description: Product documentation at CAMARA + url: hhttps://github.com/camaraproject/ +servers: + - url: '{apiRoot}/xxx-notification-subscriptions/v0' + variables: + apiRoot: + default: http://localhost:9091 + description: API root +tags: + - name: xxx notification subscription + description: Operation to manage event subscription on xxx event + +paths: + /subscriptions: + post: + tags: + - xxx notification subscription + summary: 'Create a xxx event subscription' + description: Create a xxx event subscription + operationId: createXxxSubscription + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - xxx:subscriptions:create + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubscriptionRequest' + required: true + callbacks: + notifications: + "{$request.body#/webhook/notificationUrl}": + post: + tags: + - Session notifications callback + summary: "Session notifications callback" + description: | + Important: this endpoint is to be implemented by the API consumer. + The xxx server will call this endpoint whenever a xxx event occurs. + operationId: postNotification + parameters: + - $ref: '#/components/parameters/x-correlator' + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CloudEvent" + + responses: + "204": + description: Successful notification + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - { } + - notificationsBearerAuth: [ ] + + responses: + "201": + description: Created + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + "202": + description: Request accepted to be processed. It applies for async creation process. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/SubscriptionAsync' + "400": + $ref: '#/components/responses/Generic400' + "401": + $ref: '#/components/responses/Generic401' + "403": + $ref: '#/components/responses/Generic403' + "409": + $ref: '#/components/responses/Generic409' + "500": + $ref: '#/components/responses/Generic500' + "503": + $ref: '#/components/responses/Generic503' + get: + tags: + - xxx notification subscription + summary: 'Retrieve a list of xxx event subscription' + description: Retrieve a list of xxx event subscription(s) + operationId: retrieveSubscriptionList + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - xxx:subscriptions:read + responses: + "200": + description: List of event subscription details + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Subscription' + "400": + $ref: '#/components/responses/Generic400' + "401": + $ref: '#/components/responses/Generic401' + "403": + $ref: '#/components/responses/Generic403' + "500": + $ref: '#/components/responses/Generic500' + "503": + $ref: '#/components/responses/Generic503' + /subscriptions/{subscriptionId}: + get: + tags: + - xxx notification subscription + summary: 'Retrieve a xxx event subscription' + description: retrieve event subscription information for a given subscription. + operationId: retrieveSubscription + security: + - openId: + - xxx:subscriptions:read + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: '#/components/parameters/x-correlator' + responses: + "200": + description: OK + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + "400": + $ref: '#/components/responses/SubscriptionIdRequired' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + delete: + tags: + - xxx notification subscription + summary: 'Delete a xxx event subscription' + operationId: deleteSubscription + description: delete a given event subscription. + security: + - openId: + - xxx:subscriptions:delete + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: '#/components/parameters/x-correlator' + responses: + "204": + description: event subscription deleted + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "202": + description: Request accepted to be processed. It applies for async deletion process. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/SubscriptionAsync' + "400": + $ref: '#/components/responses/SubscriptionIdRequired' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + parameters: + SubscriptionId: + name: subscriptionId + in: path + description: Subscription identifier that was obtained from the create event subscription operation + required: true + schema: + $ref: '#/components/schemas/SubscriptionId' + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + 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 + + SubscriptionRequest: + description: The request for creating a xxx event subscription + type: object + required: + - sink + - protocol + - config + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/webhook" + sinkCredential: + $ref: '#/components/schemas/SinkCredential' + types: + description: Camara Event types eligible to be delivered by this subscription - Use of array MUST be decided at API project level. + type: array + items: + type: string + filters: + type: object + description: Placeholder to add filters management for futur UC. **Not to be used as of now.** + config: + $ref: '#/components/schemas/Config' + discriminator: + propertyName: protocol + + Protocol: + type: string + enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] + description: Identifier of a delivery protocol. Only HTTP is used for now + example: "HTTP" + + Config: + description: | + Implementation-specific configuration parameters needed by the subscription manager for acquiring events. + In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` + Specific event type attributes must be defined in `subscriptionDetail` + Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. + type: object + required: + - subscriptionDetail + properties: + subscriptionDetail: + $ref: '#/components/schemas/CreateSubscriptionDetail' + subscriptionExpireTime: + type: string + format: date-time + example: 2023-01-17T13:18:23.682Z + description: The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it. + subscriptionMaxEvents: + type: integer + description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it. + minimum: 1 + example: 5 + initialEvent: + type: boolean + description: | + Set to `true` by APi consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. + Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered + Up to API project decision to keep it. + + SinkCredential: + type: object + properties: + credentialType: + type: string + enum: ["PLAIN", "ACCESSTOKEN", "REFRESHTOKEN"] + description: "The type of the credential." + discriminator: + propertyName: credentialType + required: + - credentialType + PlainCredential: + type: object + description: A plain credential as a combination of an identifier and a secret. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - properties: + identifier: + description: The identifier might be an account or username. + type: string + secret: + description: The secret might be a password or passphrase. + type: string + AccessTokenCredential: + type: object + description: An access token credential. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: RECOMMENDED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: OPTIONAL. )Type of the access token (See https://tools.ietf.org/html/rfc6749#section-7.1). + type: string + default: bearer + required: + - accessToken + - accessTokenExpiresUtc + RefreshTokenCredential: + type: object + description: An access token credential with a refresh token. + allOf: + - $ref: "#/components/schemas/AccessTokenCredential" + - type: object + properties: + refreshToken: + description: REQUIRED. An refresh token credential used to acquire access tokens. + type: string + refreshTokenEndpoint: + type: string + format: uri + description: REQUIRED. A URL at which the refresh token can be traded for an access token. + required: + - refreshToken + - refreshTokenEndpoint + + SubscriptionDetail: + description: The detail of the requested event subscription + type: object + + CreateSubscriptionDetail: + description: The detail of the requested event subscription + type: object + required: + - type + + XxxNotificationEventType: + type: string + description: | + xxx - Event triggered when a xxx event occured + + subscription-ends: Event triggered when the subscription ends + enum: + - org.camaraproject.xxx.v0.xxx + - org.camaraproject.xxx.v0.subscription-ends + + Subscription: + description: Represents a xxx subscription. + required: + - startsAt + - subscriptionId + allOf: + - $ref: '#/components/schemas/SubscriptionRequest' + - type: object + properties: + id: + type: string + description: The unique identifier of the subscription in the scope of the subscription manager. + example: 1119920371 + status: + type: string + description: current status of the subscription - Management of subscriptionstate engine is not mandatory for now. + enum: ["REQUESTED", "ACTIVE", "EXPIRED", "DEACTIVATED"] + required: + - id + + SubscriptionAsync: + description: Response for a xxx subscription request managed asynchronously (Creation or Deletion) + type: object + properties: + id: + $ref: '#/components/schemas/SubscriptionId' + + SubscriptionId: + type: string + description: The event subscription identifier. + example: qs15-h556-rt89-1298 + + CloudEvent: + description: The notification callback + required: + - id + - source + - specversion + - type + - data + properties: + id: + type: string + description: identifier of this event, that must be unique in the source context. + source: + $ref: '#/components/schemas/Source' + type: + $ref: '#/components/schemas/XxxNotificationEventType' + 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) + example: "1.0" + enum: ["1.0"] + datacontenttype: + type: string + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + example: application/json + data: + type: object + description: Event details payload described in each CAMARA API and referenced by its type + time: + $ref: "#/components/schemas/DateTime" + discriminator: + propertyName: 'type' + mapping: + org.camaraproject.xxx.v0.xxx: '#/components/schemas/EventXxx' + org.camaraproject.xxx.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' + + Source: + type: string + format: uri-reference + minLength: 1 + description: "Identifies the context in which an event happened in the specific Provider Implementation." + example: + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + + DateTime: + type: string + format: date-time + description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. + example: '2018-04-05T17:31:00Z' + + EventXxx: + description: event structure for xxx event + allOf: + - $ref: '#/components/schemas/CloudEvent' + - type: object + + EventSubscriptionEnds: + description: event structure for event subscription ends + allOf: + - $ref: '#/components/schemas/CloudEvent' + - type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionEnds' + + SubscriptionEnds: + description: Event detail structure for SUBSCRIPTION_ENDS event + type : object + required: + - terminationReason + - subscriptionId + properties: + terminationReason: + $ref: "#/components/schemas/TerminationReason" + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + terminationDescription: + type: string + + TerminationReason: + type: string + description: | + - NETWORK_TERMINATED - API server stopped sending notification + - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached + - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached + enum: + - MAX_EVENTS_REACHED + - NETWORK_TERMINATED + - SUBSCRIPTION_EXPIRED + + + HTTPSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/HTTPSettings" + + HTTPSettings: + type: object + properties: + headers: + type: object + additionalProperties: + type: string + method: + type: string + + MQTTSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/MQTTSettings" + + MQTTSettings: + type: object + properties: + topicName: + type: string + qos: + type: integer + format: int32 + retain: + type: boolean + expiry: + type: integer + format: int32 + userProperties: + type: object + required: + - topicName + + AMQPSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/AMQPSettings" + + AMQPSettings: + type: object + properties: + address: + type: string + linkName: + type: string + senderSettlementMode: + type: string + enum: ["settled", "unsettled"] + linkProperties: + type: object + additionalProperties: + type: string + + ApacheKafkaSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/ApacheKafkaSettings" + + ApacheKafkaSettings: + type: object + properties: + topicName: + type: string + partitionKeyExtractor: + type: string + clientId: + type: string + ackMode: + type: integer + required: + - topicName + + NATSSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/NATSSettings" + + NATSSettings: + type: object + properties: + subject: + type: string + required: + - subject + responses: + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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 + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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 + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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" + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: "The specified resource is not found" + Generic409: + description: Conflict + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: CONFLICT + message: "The specified resource is in a conflict" + Generic500: + description: Server error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: "UNAVAILABLE" + message: "Service unavailable" + SubscriptionIdRequired: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Schema validation failed + value: + status: 400 + code: INVALID_ARGUMENT + message: "Client specified an invalid argument, request body or query param" + subscriptionIdRequired: + summary: subscription id is required + value: + status: 400 + code: INVALID_ARGUMENT + message: "Expected property is missing: subscriptionId" + + From e8e6216ef24d438bebf5df10b0e50e0c43ef2742 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 19 Apr 2024 13:32:12 +0200 Subject: [PATCH 02/68] Update subscription-notification-template.yaml Udpaded following Maximilian review --- .../subscription-notification-template.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/artifacts/camara-cloudevents/subscription-notification-template.yaml b/artifacts/camara-cloudevents/subscription-notification-template.yaml index bcec4412..4ef1eca0 100644 --- a/artifacts/camara-cloudevents/subscription-notification-template.yaml +++ b/artifacts/camara-cloudevents/subscription-notification-template.yaml @@ -45,11 +45,11 @@ paths: required: true callbacks: notifications: - "{$request.body#/webhook/notificationUrl}": + "{$request.body#/sink}": post: tags: - - Session notifications callback - summary: "Session notifications callback" + - notifications callback + summary: "notifications callback" description: | Important: this endpoint is to be implemented by the API consumer. The xxx server will call this endpoint whenever a xxx event occurs. @@ -187,7 +187,7 @@ paths: - xxx notification subscription summary: 'Delete a xxx event subscription' operationId: deleteSubscription - description: delete a given event subscription. + description: delete a given event subscription. security: - openId: - xxx:subscriptions:delete From e876826b3e653bd140f9639730b5443561519880 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 22 Apr 2024 08:58:18 +0200 Subject: [PATCH 03/68] Update artifacts/camara-cloudevents/subscription-notification-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- .../camara-cloudevents/subscription-notification-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/subscription-notification-template.yaml b/artifacts/camara-cloudevents/subscription-notification-template.yaml index 4ef1eca0..ea4a7e02 100644 --- a/artifacts/camara-cloudevents/subscription-notification-template.yaml +++ b/artifacts/camara-cloudevents/subscription-notification-template.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Notification Subscription Template description: | - This file is a template for CAMARA explicit subscription template and for Notification model. Additional information are provided in API Design guidelines document. + This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document. termsOfService: http://swagger.io/terms/ contact: From cbb3b1cd6ec606df45f6f49e4484b1eaddbc07cd Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 22 Apr 2024 08:58:27 +0200 Subject: [PATCH 04/68] Update artifacts/camara-cloudevents/subscription-notification-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- .../camara-cloudevents/subscription-notification-template.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/subscription-notification-template.yaml b/artifacts/camara-cloudevents/subscription-notification-template.yaml index ea4a7e02..ae473e15 100644 --- a/artifacts/camara-cloudevents/subscription-notification-template.yaml +++ b/artifacts/camara-cloudevents/subscription-notification-template.yaml @@ -461,7 +461,8 @@ components: 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) example: "1.0" - enum: ["1.0"] + enum: + - "1.0" datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' From 857429b784af832b5dd5ccf509a9d871aa80837c Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 22 Apr 2024 09:53:10 +0200 Subject: [PATCH 05/68] Rename subscription-notification-template.yaml to event-subscription-template.yaml As suggested by @akoshunyadi --- ...otification-template.yaml => event-subscription-template.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename artifacts/camara-cloudevents/{subscription-notification-template.yaml => event-subscription-template.yaml} (100%) diff --git a/artifacts/camara-cloudevents/subscription-notification-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml similarity index 100% rename from artifacts/camara-cloudevents/subscription-notification-template.yaml rename to artifacts/camara-cloudevents/event-subscription-template.yaml From 19ad9fc0c58d1b24501077b44641e3b6df45d385 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 22 Apr 2024 10:15:46 +0200 Subject: [PATCH 06/68] Update event-subscription-template.yaml Rename xxx to event-type Fixed issue with security remove example for apiVersion --- .../event-subscription-template.yaml | 66 +++++++++---------- 1 file changed, 31 insertions(+), 35 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index ae473e15..c2fcec26 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -15,28 +15,28 @@ externalDocs: description: Product documentation at CAMARA url: hhttps://github.com/camaraproject/ servers: - - url: '{apiRoot}/xxx-notification-subscriptions/v0' + - url: '{apiRoot}/event-type-notification-subscriptions/v0' variables: apiRoot: default: http://localhost:9091 description: API root tags: - - name: xxx notification subscription - description: Operation to manage event subscription on xxx event + - name: event-type notification subscription + description: Operation to manage event subscription on event-type event paths: /subscriptions: post: tags: - - xxx notification subscription - summary: 'Create a xxx event subscription' - description: Create a xxx event subscription - operationId: createXxxSubscription + - event-type notification subscription + summary: 'Create a event-type event subscription' + description: Create a event-type event subscription + operationId: createEvent-TypeSubscription parameters: - $ref: '#/components/parameters/x-correlator' security: - openId: - - xxx:subscriptions:create + - event-type:subscriptions:create requestBody: content: application/json: @@ -52,7 +52,7 @@ paths: summary: "notifications callback" description: | Important: this endpoint is to be implemented by the API consumer. - The xxx server will call this endpoint whenever a xxx event occurs. + The event-type server will call this endpoint whenever a event-type event occurs. operationId: postNotification parameters: - $ref: '#/components/parameters/x-correlator' @@ -81,7 +81,6 @@ paths: $ref: "#/components/responses/Generic503" security: - { } - - notificationsBearerAuth: [ ] responses: "201": @@ -116,15 +115,15 @@ paths: $ref: '#/components/responses/Generic503' get: tags: - - xxx notification subscription - summary: 'Retrieve a list of xxx event subscription' - description: Retrieve a list of xxx event subscription(s) + - event-type notification subscription + summary: 'Retrieve a list of event-type event subscription' + description: Retrieve a list of event-type event subscription(s) operationId: retrieveSubscriptionList parameters: - $ref: '#/components/parameters/x-correlator' security: - openId: - - xxx:subscriptions:read + - event-type:subscriptions:read responses: "200": description: List of event subscription details @@ -150,13 +149,13 @@ paths: /subscriptions/{subscriptionId}: get: tags: - - xxx notification subscription - summary: 'Retrieve a xxx event subscription' + - event-type notification subscription + summary: 'Retrieve a event-type event subscription' description: retrieve event subscription information for a given subscription. operationId: retrieveSubscription security: - openId: - - xxx:subscriptions:read + - event-type:subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' @@ -184,13 +183,13 @@ paths: $ref: "#/components/responses/Generic503" delete: tags: - - xxx notification subscription - summary: 'Delete a xxx event subscription' + - event-type notification subscription + summary: 'Delete a event-type event subscription' operationId: deleteSubscription description: delete a given event subscription. security: - openId: - - xxx:subscriptions:delete + - event-type:subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' @@ -264,7 +263,7 @@ components: description: Detailed error description SubscriptionRequest: - description: The request for creating a xxx event subscription + description: The request for creating a event-type event subscription type: object required: - sink @@ -399,18 +398,18 @@ components: required: - type - XxxNotificationEventType: + Event-typeNotification: type: string description: | - xxx - Event triggered when a xxx event occured + event-type - Event triggered when a event-type event occured subscription-ends: Event triggered when the subscription ends enum: - - org.camaraproject.xxx.v0.xxx - - org.camaraproject.xxx.v0.subscription-ends + - org.camaraproject.api-name.v0.event-type + - org.camaraproject.api-name.v0.subscription-ends Subscription: - description: Represents a xxx subscription. + description: Represents a event-type subscription. required: - startsAt - subscriptionId @@ -430,7 +429,7 @@ components: - id SubscriptionAsync: - description: Response for a xxx subscription request managed asynchronously (Creation or Deletion) + description: Response for a event-type subscription request managed asynchronously (Creation or Deletion) type: object properties: id: @@ -456,11 +455,10 @@ components: source: $ref: '#/components/schemas/Source' type: - $ref: '#/components/schemas/XxxNotificationEventType' + $ref: '#/components/schemas/Event-typeNotification' 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) - example: "1.0" enum: - "1.0" datacontenttype: @@ -475,8 +473,8 @@ components: discriminator: propertyName: 'type' mapping: - org.camaraproject.xxx.v0.xxx: '#/components/schemas/EventXxx' - org.camaraproject.xxx.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' + org.camaraproject.api-name.v0.event-type: '#/components/schemas/Event-typeEvent' + org.camaraproject.api-name.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' Source: type: string @@ -497,8 +495,8 @@ components: description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. example: '2018-04-05T17:31:00Z' - EventXxx: - description: event structure for xxx event + Event-typeEven: + description: event structure for event-type event allOf: - $ref: '#/components/schemas/CloudEvent' - type: object @@ -756,5 +754,3 @@ components: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: subscriptionId" - - From 2b0596a3f8b29c65cc33d2ac8e1b05066c2636b6 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 22 Apr 2024 17:58:02 +0200 Subject: [PATCH 07/68] Update event-subscription-template.yaml Fixed issue for scope in the openId security part (line 40) --- .../event-subscription-template.yaml | 759 +++++++++++++++++- 1 file changed, 758 insertions(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index c2fcec26..d5c04267 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -36,7 +36,764 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - event-type:subscriptions:create + - api-name:subscriptions:create + - api-name:event-type:grant-level + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubscriptionRequest' + required: true + callbacks: + notifications: + "{$request.body#/sink}": + post: + tags: + - notifications callback + summary: "notifications callback" + description: | + Important: this endpoint is to be implemented by the API consumer. + The event-type server will call this endpoint whenever a event-type event occurs. + operationId: postNotification + parameters: + - $ref: '#/components/parameters/x-correlator' + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CloudEvent" + + responses: + "204": + description: Successful notification + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - { } + + responses: + "201": + description: Created + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + "202": + description: Request accepted to be processed. It applies for async creation process. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/SubscriptionAsync' + "400": + $ref: '#/components/responses/Generic400' + "401": + $ref: '#/components/responses/Generic401' + "403": + $ref: '#/components/responses/Generic403' + "409": + $ref: '#/components/responses/Generic409' + "500": + $ref: '#/components/responses/Generic500' + "503": + $ref: '#/components/responses/Generic503' + get: + tags: + - event-type notification subscription + summary: 'Retrieve a list of event-type event subscription' + description: Retrieve a list of event-type event subscription(s) + operationId: retrieveSubscriptionList + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - event-type:subscriptions:read + responses: + "200": + description: List of event subscription details + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Subscription' + "400": + $ref: '#/components/responses/Generic400' + "401": + $ref: '#/components/responses/Generic401' + "403": + $ref: '#/components/responses/Generic403' + "500": + $ref: '#/components/responses/Generic500' + "503": + $ref: '#/components/responses/Generic503' + /subscriptions/{subscriptionId}: + get: + tags: + - event-type notification subscription + summary: 'Retrieve a event-type event subscription' + description: retrieve event subscription information for a given subscription. + operationId: retrieveSubscription + security: + - openId: + - event-type:subscriptions:read + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: '#/components/parameters/x-correlator' + responses: + "200": + description: OK + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + "400": + $ref: '#/components/responses/SubscriptionIdRequired' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + delete: + tags: + - event-type notification subscription + summary: 'Delete a event-type event subscription' + operationId: deleteSubscription + description: delete a given event subscription. + security: + - openId: + - event-type:subscriptions:delete + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: '#/components/parameters/x-correlator' + responses: + "204": + description: event subscription deleted + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "202": + description: Request accepted to be processed. It applies for async deletion process. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/SubscriptionAsync' + "400": + $ref: '#/components/responses/SubscriptionIdRequired' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + parameters: + SubscriptionId: + name: subscriptionId + in: path + description: Subscription identifier that was obtained from the create event subscription operation + required: true + schema: + $ref: '#/components/schemas/SubscriptionId' + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + 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 + + SubscriptionRequest: + description: The request for creating a event-type event subscription + type: object + required: + - sink + - protocol + - config + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/webhook" + sinkCredential: + $ref: '#/components/schemas/SinkCredential' + types: + description: Camara Event types eligible to be delivered by this subscription - Use of array MUST be decided at API project level. + type: array + items: + type: string + filters: + type: object + description: Placeholder to add filters management for futur UC. **Not to be used as of now.** + config: + $ref: '#/components/schemas/Config' + discriminator: + propertyName: protocol + + Protocol: + type: string + enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] + description: Identifier of a delivery protocol. Only HTTP is used for now + example: "HTTP" + + Config: + description: | + Implementation-specific configuration parameters needed by the subscription manager for acquiring events. + In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` + Specific event type attributes must be defined in `subscriptionDetail` + Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. + type: object + required: + - subscriptionDetail + properties: + subscriptionDetail: + $ref: '#/components/schemas/CreateSubscriptionDetail' + subscriptionExpireTime: + type: string + format: date-time + example: 2023-01-17T13:18:23.682Z + description: The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it. + subscriptionMaxEvents: + type: integer + description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it. + minimum: 1 + example: 5 + initialEvent: + type: boolean + description: | + Set to `true` by APi consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. + Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered + Up to API project decision to keep it. + + SinkCredential: + type: object + properties: + credentialType: + type: string + enum: ["PLAIN", "ACCESSTOKEN", "REFRESHTOKEN"] + description: "The type of the credential." + discriminator: + propertyName: credentialType + required: + - credentialType + PlainCredential: + type: object + description: A plain credential as a combination of an identifier and a secret. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - properties: + identifier: + description: The identifier might be an account or username. + type: string + secret: + description: The secret might be a password or passphrase. + type: string + AccessTokenCredential: + type: object + description: An access token credential. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: RECOMMENDED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: OPTIONAL. )Type of the access token (See https://tools.ietf.org/html/rfc6749#section-7.1). + type: string + default: bearer + required: + - accessToken + - accessTokenExpiresUtc + RefreshTokenCredential: + type: object + description: An access token credential with a refresh token. + allOf: + - $ref: "#/components/schemas/AccessTokenCredential" + - type: object + properties: + refreshToken: + description: REQUIRED. An refresh token credential used to acquire access tokens. + type: string + refreshTokenEndpoint: + type: string + format: uri + description: REQUIRED. A URL at which the refresh token can be traded for an access token. + required: + - refreshToken + - refreshTokenEndpoint + + SubscriptionDetail: + description: The detail of the requested event subscription + type: object + + CreateSubscriptionDetail: + description: The detail of the requested event subscription + type: object + required: + - type + + Event-typeNotification: + type: string + description: | + event-type - Event triggered when a event-type event occured + + subscription-ends: Event triggered when the subscription ends + enum: + - org.camaraproject.api-name.v0.event-type + - org.camaraproject.api-name.v0.subscription-ends + + Subscription: + description: Represents a event-type subscription. + required: + - startsAt + - subscriptionId + allOf: + - $ref: '#/components/schemas/SubscriptionRequest' + - type: object + properties: + id: + type: string + description: The unique identifier of the subscription in the scope of the subscription manager. + example: 1119920371 + status: + type: string + description: current status of the subscription - Management of subscriptionstate engine is not mandatory for now. + enum: ["REQUESTED", "ACTIVE", "EXPIRED", "DEACTIVATED"] + required: + - id + + SubscriptionAsync: + description: Response for a event-type subscription request managed asynchronously (Creation or Deletion) + type: object + properties: + id: + $ref: '#/components/schemas/SubscriptionId' + + SubscriptionId: + type: string + description: The event subscription identifier. + example: qs15-h556-rt89-1298 + + CloudEvent: + description: The notification callback + required: + - id + - source + - specversion + - type + - data + properties: + id: + type: string + description: identifier of this event, that must be unique in the source context. + source: + $ref: '#/components/schemas/Source' + type: + $ref: '#/components/schemas/Event-typeNotification' + 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) + enum: + - "1.0" + datacontenttype: + type: string + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + example: application/json + data: + type: object + description: Event details payload described in each CAMARA API and referenced by its type + time: + $ref: "#/components/schemas/DateTime" + discriminator: + propertyName: 'type' + mapping: + org.camaraproject.api-name.v0.event-type: '#/components/schemas/Event-typeEvent' + org.camaraproject.api-name.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' + + Source: + type: string + format: uri-reference + minLength: 1 + description: "Identifies the context in which an event happened in the specific Provider Implementation." + example: + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + + DateTime: + type: string + format: date-time + description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. + example: '2018-04-05T17:31:00Z' + + Event-typeEven: + description: event structure for event-type event + allOf: + - $ref: '#/components/schemas/CloudEvent' + - type: object + + EventSubscriptionEnds: + description: event structure for event subscription ends + allOf: + - $ref: '#/components/schemas/CloudEvent' + - type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionEnds' + + SubscriptionEnds: + description: Event detail structure for SUBSCRIPTION_ENDS event + type : object + required: + - terminationReason + - subscriptionId + properties: + terminationReason: + $ref: "#/components/schemas/TerminationReason" + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + terminationDescription: + type: string + + TerminationReason: + type: string + description: | + - NETWORK_TERMINATED - API server stopped sending notification + - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached + - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached + enum: + - MAX_EVENTS_REACHED + - NETWORK_TERMINATED + - SUBSCRIPTION_EXPIRED + + + HTTPSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/HTTPSettings" + + HTTPSettings: + type: object + properties: + headers: + type: object + additionalProperties: + type: string + method: + type: string + + MQTTSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/MQTTSettings" + + MQTTSettings: + type: object + properties: + topicName: + type: string + qos: + type: integer + format: int32 + retain: + type: boolean + expiry: + type: integer + format: int32 + userProperties: + type: object + required: + - topicName + + AMQPSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/AMQPSettings" + + AMQPSettings: + type: object + properties: + address: + type: string + linkName: + type: string + senderSettlementMode: + type: string + enum: ["settled", "unsettled"] + linkProperties: + type: object + additionalProperties: + type: string + + ApacheKafkaSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/ApacheKafkaSettings" + + ApacheKafkaSettings: + type: object + properties: + topicName: + type: string + partitionKeyExtractor: + type: string + clientId: + type: string + ackMode: + type: integer + required: + - topicName + + NATSSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/NATSSettings" + + NATSSettings: + type: object + properties: + subject: + type: string + required: + - subject + responses: + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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 + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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 + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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" + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: "The specified resource is not found" + Generic409: + description: Conflict + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: CONFLICT + message: "The specified resource is in a conflict" + Generic500: + description: Server error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + 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. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: "UNAVAILABLE" + message: "Service unavailable" + SubscriptionIdRequired: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Schema validation failed + value: + status: 400 + code: INVALID_ARGUMENT + message: "Client specified an invalid argument, request body or query param" + subscriptionIdRequired: + summary: subscription id is required + value: + status: 400 + code: INVALID_ARGUMENT + message: "Expected property is missing: subscriptionId"openapi: 3.0.3 +info: + title: Notification Subscription Template + description: | + This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines 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-wip +externalDocs: + description: Product documentation at CAMARA + url: hhttps://github.com/camaraproject/ +servers: + - url: '{apiRoot}/event-type-notification-subscriptions/v0' + variables: + apiRoot: + default: http://localhost:9091 + description: API root +tags: + - name: event-type notification subscription + description: Operation to manage event subscription on event-type event + +paths: + /subscriptions: + post: + tags: + - event-type notification subscription + summary: 'Create a event-type event subscription' + description: Create a event-type event subscription + operationId: createEvent-TypeSubscription + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - api-name:subscriptions:create + - api-name:event-type:grant-level requestBody: content: application/json: From 367ecb898b4e1173359434855398ac06d9f82e60 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 24 Apr 2024 12:03:21 +0200 Subject: [PATCH 08/68] Update event-subscription-template.yaml --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index d5c04267..d1ad3dad 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -754,7 +754,7 @@ components: value: status: 400 code: INVALID_ARGUMENT - message: "Expected property is missing: subscriptionId"openapi: 3.0.3 + message: "Expected property is missing: subscriptionId" info: title: Notification Subscription Template description: | From 56959e19fbbae5687933448585b59cda63d2ce2e Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 24 Apr 2024 14:37:42 +0200 Subject: [PATCH 09/68] Update event-subscription-template.yaml --- .../event-subscription-template.yaml | 756 ------------------ 1 file changed, 756 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index d1ad3dad..e8a9440a 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -755,759 +755,3 @@ components: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: subscriptionId" -info: - title: Notification Subscription Template - description: | - This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines 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-wip -externalDocs: - description: Product documentation at CAMARA - url: hhttps://github.com/camaraproject/ -servers: - - url: '{apiRoot}/event-type-notification-subscriptions/v0' - variables: - apiRoot: - default: http://localhost:9091 - description: API root -tags: - - name: event-type notification subscription - description: Operation to manage event subscription on event-type event - -paths: - /subscriptions: - post: - tags: - - event-type notification subscription - summary: 'Create a event-type event subscription' - description: Create a event-type event subscription - operationId: createEvent-TypeSubscription - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - api-name:subscriptions:create - - api-name:event-type:grant-level - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SubscriptionRequest' - required: true - callbacks: - notifications: - "{$request.body#/sink}": - post: - tags: - - notifications callback - summary: "notifications callback" - description: | - Important: this endpoint is to be implemented by the API consumer. - The event-type server will call this endpoint whenever a event-type event occurs. - operationId: postNotification - parameters: - - $ref: '#/components/parameters/x-correlator' - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CloudEvent" - - responses: - "204": - description: Successful notification - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - security: - - { } - - responses: - "201": - description: Created - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/Subscription' - "202": - description: Request accepted to be processed. It applies for async creation process. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/SubscriptionAsync' - "400": - $ref: '#/components/responses/Generic400' - "401": - $ref: '#/components/responses/Generic401' - "403": - $ref: '#/components/responses/Generic403' - "409": - $ref: '#/components/responses/Generic409' - "500": - $ref: '#/components/responses/Generic500' - "503": - $ref: '#/components/responses/Generic503' - get: - tags: - - event-type notification subscription - summary: 'Retrieve a list of event-type event subscription' - description: Retrieve a list of event-type event subscription(s) - operationId: retrieveSubscriptionList - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - event-type:subscriptions:read - responses: - "200": - description: List of event subscription details - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Subscription' - "400": - $ref: '#/components/responses/Generic400' - "401": - $ref: '#/components/responses/Generic401' - "403": - $ref: '#/components/responses/Generic403' - "500": - $ref: '#/components/responses/Generic500' - "503": - $ref: '#/components/responses/Generic503' - /subscriptions/{subscriptionId}: - get: - tags: - - event-type notification subscription - summary: 'Retrieve a event-type event subscription' - description: retrieve event subscription information for a given subscription. - operationId: retrieveSubscription - security: - - openId: - - event-type:subscriptions:read - parameters: - - $ref: "#/components/parameters/SubscriptionId" - - $ref: '#/components/parameters/x-correlator' - responses: - "200": - description: OK - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/Subscription' - "400": - $ref: '#/components/responses/SubscriptionIdRequired' - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - delete: - tags: - - event-type notification subscription - summary: 'Delete a event-type event subscription' - operationId: deleteSubscription - description: delete a given event subscription. - security: - - openId: - - event-type:subscriptions:delete - parameters: - - $ref: "#/components/parameters/SubscriptionId" - - $ref: '#/components/parameters/x-correlator' - responses: - "204": - description: event subscription deleted - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - "202": - description: Request accepted to be processed. It applies for async deletion process. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/SubscriptionAsync' - "400": - $ref: '#/components/responses/SubscriptionIdRequired' - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" -components: - securitySchemes: - openId: - type: openIdConnect - openIdConnectUrl: https://example.com/.well-known/openid-configuration - parameters: - SubscriptionId: - name: subscriptionId - in: path - description: Subscription identifier that was obtained from the create event subscription operation - required: true - schema: - $ref: '#/components/schemas/SubscriptionId' - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - type: string - headers: - x-correlator: - description: Correlation id for the different services - schema: - type: string - 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 - - SubscriptionRequest: - description: The request for creating a event-type event subscription - type: object - required: - - sink - - protocol - - config - properties: - protocol: - $ref: "#/components/schemas/Protocol" - sink: - type: string - format: url - description: The address to which events shall be delivered using the selected protocol. - example: "https://endpoint.example.com/webhook" - sinkCredential: - $ref: '#/components/schemas/SinkCredential' - types: - description: Camara Event types eligible to be delivered by this subscription - Use of array MUST be decided at API project level. - type: array - items: - type: string - filters: - type: object - description: Placeholder to add filters management for futur UC. **Not to be used as of now.** - config: - $ref: '#/components/schemas/Config' - discriminator: - propertyName: protocol - - Protocol: - type: string - enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] - description: Identifier of a delivery protocol. Only HTTP is used for now - example: "HTTP" - - Config: - description: | - Implementation-specific configuration parameters needed by the subscription manager for acquiring events. - In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` - Specific event type attributes must be defined in `subscriptionDetail` - Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. - type: object - required: - - subscriptionDetail - properties: - subscriptionDetail: - $ref: '#/components/schemas/CreateSubscriptionDetail' - subscriptionExpireTime: - type: string - format: date-time - example: 2023-01-17T13:18:23.682Z - description: The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it. - subscriptionMaxEvents: - type: integer - description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it. - minimum: 1 - example: 5 - initialEvent: - type: boolean - description: | - Set to `true` by APi consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. - Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered - Up to API project decision to keep it. - - SinkCredential: - type: object - properties: - credentialType: - type: string - enum: ["PLAIN", "ACCESSTOKEN", "REFRESHTOKEN"] - description: "The type of the credential." - discriminator: - propertyName: credentialType - required: - - credentialType - PlainCredential: - type: object - description: A plain credential as a combination of an identifier and a secret. - allOf: - - $ref: "#/components/schemas/SinkCredential" - - properties: - identifier: - description: The identifier might be an account or username. - type: string - secret: - description: The secret might be a password or passphrase. - type: string - AccessTokenCredential: - type: object - description: An access token credential. - allOf: - - $ref: "#/components/schemas/SinkCredential" - - properties: - accessToken: - description: REQUIRED. An access token is a previously acquired token granting access to the target resource. - type: string - accessTokenExpiresUtc: - type: string - format: date-time - description: RECOMMENDED. An absolute UTC instant at which the token shall be considered expired. - accessTokenType: - description: OPTIONAL. )Type of the access token (See https://tools.ietf.org/html/rfc6749#section-7.1). - type: string - default: bearer - required: - - accessToken - - accessTokenExpiresUtc - RefreshTokenCredential: - type: object - description: An access token credential with a refresh token. - allOf: - - $ref: "#/components/schemas/AccessTokenCredential" - - type: object - properties: - refreshToken: - description: REQUIRED. An refresh token credential used to acquire access tokens. - type: string - refreshTokenEndpoint: - type: string - format: uri - description: REQUIRED. A URL at which the refresh token can be traded for an access token. - required: - - refreshToken - - refreshTokenEndpoint - - SubscriptionDetail: - description: The detail of the requested event subscription - type: object - - CreateSubscriptionDetail: - description: The detail of the requested event subscription - type: object - required: - - type - - Event-typeNotification: - type: string - description: | - event-type - Event triggered when a event-type event occured - - subscription-ends: Event triggered when the subscription ends - enum: - - org.camaraproject.api-name.v0.event-type - - org.camaraproject.api-name.v0.subscription-ends - - Subscription: - description: Represents a event-type subscription. - required: - - startsAt - - subscriptionId - allOf: - - $ref: '#/components/schemas/SubscriptionRequest' - - type: object - properties: - id: - type: string - description: The unique identifier of the subscription in the scope of the subscription manager. - example: 1119920371 - status: - type: string - description: current status of the subscription - Management of subscriptionstate engine is not mandatory for now. - enum: ["REQUESTED", "ACTIVE", "EXPIRED", "DEACTIVATED"] - required: - - id - - SubscriptionAsync: - description: Response for a event-type subscription request managed asynchronously (Creation or Deletion) - type: object - properties: - id: - $ref: '#/components/schemas/SubscriptionId' - - SubscriptionId: - type: string - description: The event subscription identifier. - example: qs15-h556-rt89-1298 - - CloudEvent: - description: The notification callback - required: - - id - - source - - specversion - - type - - data - properties: - id: - type: string - description: identifier of this event, that must be unique in the source context. - source: - $ref: '#/components/schemas/Source' - type: - $ref: '#/components/schemas/Event-typeNotification' - 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) - enum: - - "1.0" - datacontenttype: - type: string - description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' - example: application/json - data: - type: object - description: Event details payload described in each CAMARA API and referenced by its type - time: - $ref: "#/components/schemas/DateTime" - discriminator: - propertyName: 'type' - mapping: - org.camaraproject.api-name.v0.event-type: '#/components/schemas/Event-typeEvent' - org.camaraproject.api-name.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' - - Source: - type: string - format: uri-reference - minLength: 1 - description: "Identifies the context in which an event happened in the specific Provider Implementation." - example: - - https://github.com/cloudevents - - mailto:cncf-wg-serverless@lists.cncf.io - - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - cloudevents/spec/pull/123 - - /sensors/tn-1234567/alerts - - 1-555-123-4567 - - DateTime: - type: string - format: date-time - description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. - example: '2018-04-05T17:31:00Z' - - Event-typeEven: - description: event structure for event-type event - allOf: - - $ref: '#/components/schemas/CloudEvent' - - type: object - - EventSubscriptionEnds: - description: event structure for event subscription ends - allOf: - - $ref: '#/components/schemas/CloudEvent' - - type: object - properties: - data: - $ref: '#/components/schemas/SubscriptionEnds' - - SubscriptionEnds: - description: Event detail structure for SUBSCRIPTION_ENDS event - type : object - required: - - terminationReason - - subscriptionId - properties: - terminationReason: - $ref: "#/components/schemas/TerminationReason" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - terminationDescription: - type: string - - TerminationReason: - type: string - description: | - - NETWORK_TERMINATED - API server stopped sending notification - - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached - - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached - enum: - - MAX_EVENTS_REACHED - - NETWORK_TERMINATED - - SUBSCRIPTION_EXPIRED - - - HTTPSubscriptionRequest: - allOf: - - $ref: "#/components/schemas/SubscriptionRequest" - - type: object - properties: - protocolSettings: - $ref: "#/components/schemas/HTTPSettings" - - HTTPSettings: - type: object - properties: - headers: - type: object - additionalProperties: - type: string - method: - type: string - - MQTTSubscriptionRequest: - allOf: - - $ref: "#/components/schemas/SubscriptionRequest" - - type: object - properties: - protocolSettings: - $ref: "#/components/schemas/MQTTSettings" - - MQTTSettings: - type: object - properties: - topicName: - type: string - qos: - type: integer - format: int32 - retain: - type: boolean - expiry: - type: integer - format: int32 - userProperties: - type: object - required: - - topicName - - AMQPSubscriptionRequest: - allOf: - - $ref: "#/components/schemas/SubscriptionRequest" - - type: object - properties: - protocolSettings: - $ref: "#/components/schemas/AMQPSettings" - - AMQPSettings: - type: object - properties: - address: - type: string - linkName: - type: string - senderSettlementMode: - type: string - enum: ["settled", "unsettled"] - linkProperties: - type: object - additionalProperties: - type: string - - ApacheKafkaSubscriptionRequest: - allOf: - - $ref: "#/components/schemas/SubscriptionRequest" - - type: object - properties: - protocolSettings: - $ref: "#/components/schemas/ApacheKafkaSettings" - - ApacheKafkaSettings: - type: object - properties: - topicName: - type: string - partitionKeyExtractor: - type: string - clientId: - type: string - ackMode: - type: integer - required: - - topicName - - NATSSubscriptionRequest: - allOf: - - $ref: "#/components/schemas/SubscriptionRequest" - - type: object - properties: - protocolSettings: - $ref: "#/components/schemas/NATSSettings" - - NATSSettings: - type: object - properties: - subject: - type: string - required: - - subject - responses: - Generic400: - description: Problem with the client request - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - 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 - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - 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 - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - 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" - Generic404: - description: Resource Not Found - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "The specified resource is not found" - Generic409: - description: Conflict - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: "The specified resource is in a conflict" - Generic500: - description: Server error - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - 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. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: "UNAVAILABLE" - message: "Service unavailable" - SubscriptionIdRequired: - description: Problem with the client request - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic400: - summary: Schema validation failed - value: - status: 400 - code: INVALID_ARGUMENT - message: "Client specified an invalid argument, request body or query param" - subscriptionIdRequired: - summary: subscription id is required - value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: subscriptionId" From e09a10d482dd422709e8a18eda82719ffb31fd1d Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 29 Apr 2024 18:43:04 +0200 Subject: [PATCH 10/68] Update event-subscription-template.yaml Following Shilpa suggestion, removal of the scope - api-name:subscriptions:create for the `POST` operation are the scope for the event-type itself is just good enough. --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index e8a9440a..44c6d2d7 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -36,7 +36,6 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - api-name:subscriptions:create - api-name:event-type:grant-level requestBody: content: From f1a37f68961d5ec03533ead84bb6eb6c0db5cfb3 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 1 May 2024 16:24:24 +0200 Subject: [PATCH 11/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 44c6d2d7..7980e88d 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -22,7 +22,7 @@ servers: description: API root tags: - name: event-type notification subscription - description: Operation to manage event subscription on event-type event + description: Operations to manage event subscriptions on event-type event paths: /subscriptions: From 540d932ee20721f99400cb1067c46669f8acf517 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 1 May 2024 16:25:20 +0200 Subject: [PATCH 12/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 7980e88d..5fa8c465 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -286,7 +286,7 @@ components: type: string filters: type: object - description: Placeholder to add filters management for futur UC. **Not to be used as of now.** + description: Placeholder to add filters management for future UC. **It MUST not be used as long as UC requires it and their behaviour is discussed and agreed in advance** config: $ref: '#/components/schemas/Config' discriminator: From 5fe825f29ab6e89776929b742989b01065e83f9d Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 1 May 2024 16:26:02 +0200 Subject: [PATCH 13/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 5fa8c465..e6d1eb40 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -295,7 +295,7 @@ components: Protocol: type: string enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] - description: Identifier of a delivery protocol. Only HTTP is used for now + description: Identifier of a delivery protocol. Only HTTP is allowed for now example: "HTTP" Config: From f3d50fdadc3351713cd7cc59f432d3893b3bfb14 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 1 May 2024 17:00:05 +0200 Subject: [PATCH 14/68] Update event-subscription-template.yaml Updated accordingly to Pedro & Shilpa review. --- .../event-subscription-template.yaml | 70 +++++++++++++------ 1 file changed, 48 insertions(+), 22 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index e6d1eb40..5e3629d9 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -4,6 +4,8 @@ info: description: | This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document. + Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type:grant-level` must be replaced accordingly to the format defined in the guideline document. + termsOfService: http://swagger.io/terms/ contact: email: project-email@sample.com @@ -15,23 +17,26 @@ externalDocs: description: Product documentation at CAMARA url: hhttps://github.com/camaraproject/ servers: - - url: '{apiRoot}/event-type-notification-subscriptions/v0' + - url: '{apiRoot}/{apiName}/v0' variables: apiRoot: default: http://localhost:9091 description: API root + api-name: + default: camaraAPI + description: apiName will be replaced in WG by its value and not modelled as a variable tags: - - name: event-type notification subscription + - name: apiName subscription description: Operations to manage event subscriptions on event-type event paths: /subscriptions: post: tags: - - event-type notification subscription - summary: 'Create a event-type event subscription' - description: Create a event-type event subscription - operationId: createEvent-TypeSubscription + - apiName subscription + summary: 'Create a apiName event subscription' + description: Create a apiName event subscription + operationId: createApiNameSubscription parameters: - $ref: '#/components/parameters/x-correlator' security: @@ -52,7 +57,7 @@ paths: summary: "notifications callback" description: | Important: this endpoint is to be implemented by the API consumer. - The event-type server will call this endpoint whenever a event-type event occurs. + The apiName server will call this endpoint whenever a apiName event occurs. operationId: postNotification parameters: - $ref: '#/components/parameters/x-correlator' @@ -70,7 +75,7 @@ paths: x-correlator: $ref: '#/components/headers/x-correlator' "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/CreateSubscriptionBadRequest400" "401": $ref: "#/components/responses/Generic401" "403": @@ -115,9 +120,9 @@ paths: $ref: '#/components/responses/Generic503' get: tags: - - event-type notification subscription - summary: 'Retrieve a list of event-type event subscription' - description: Retrieve a list of event-type event subscription(s) + - apiName subscription + summary: 'Retrieve a list of apiName event subscription' + description: Retrieve a list of apiName event subscription(s) operationId: retrieveSubscriptionList parameters: - $ref: '#/components/parameters/x-correlator' @@ -149,9 +154,9 @@ paths: /subscriptions/{subscriptionId}: get: tags: - - event-type notification subscription - summary: 'Retrieve a event-type event subscription' - description: retrieve event subscription information for a given subscription. + - apiName subscription + summary: 'Retrieve a apiName event subscription' + description: retrieve apiName subscription information for a given subscription. operationId: retrieveSubscription security: - openId: @@ -183,10 +188,10 @@ paths: $ref: "#/components/responses/Generic503" delete: tags: - - event-type notification subscription - summary: 'Delete a event-type event subscription' + - apiName subscription + summary: 'Delete a apiName event subscription' operationId: deleteSubscription - description: delete a given event subscription. + description: delete a given apiName subscription. security: - openId: - event-type:subscriptions:delete @@ -195,7 +200,7 @@ paths: - $ref: '#/components/parameters/x-correlator' responses: "204": - description: event subscription deleted + description: apiName subscription deleted headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -269,6 +274,7 @@ components: - sink - protocol - config + - types properties: protocol: $ref: "#/components/schemas/Protocol" @@ -280,13 +286,13 @@ components: sinkCredential: $ref: '#/components/schemas/SinkCredential' types: - description: Camara Event types eligible to be delivered by this subscription - Use of array MUST be decided at API project level. + description: | + Camara Event types eligible to be delivered by this subscription. + Note : for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided + at API project level. type: array items: type: string - filters: - type: object - description: Placeholder to add filters management for future UC. **It MUST not be used as long as UC requires it and their behaviour is discussed and agreed in advance** config: $ref: '#/components/schemas/Config' discriminator: @@ -641,6 +647,26 @@ components: required: - subject responses: + CreateSubscriptionBadRequest400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + InvalidArgument: + value: + status: 400 + code: "INVALID_ARGUMENT" + message: "Client specified an invalid argument, request body or query param" + InvalidProtocol: + value: + status: 400 + code: "INVALID_PROTOCOL" + message: "Only HTTP is supported" Generic400: description: Problem with the client request headers: From 9ccffdf7997475819ed395720255450e27d63c61 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:18:56 +0200 Subject: [PATCH 15/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 5e3629d9..f1539296 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -22,7 +22,7 @@ servers: apiRoot: default: http://localhost:9091 description: API root - api-name: + apiName: default: camaraAPI description: apiName will be replaced in WG by its value and not modelled as a variable tags: From d3904d2563c9ca130795d00a4624212a449486dc Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:19:32 +0200 Subject: [PATCH 16/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index f1539296..f73263ca 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -58,6 +58,7 @@ paths: description: | Important: this endpoint is to be implemented by the API consumer. The apiName server will call this endpoint whenever a apiName event occurs. + `operationId` value will have to be replaced accordingly with WG API specific semantic operationId: postNotification parameters: - $ref: '#/components/parameters/x-correlator' From fbc0d8ced460eeade355e82845fd35693500de67 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:20:44 +0200 Subject: [PATCH 17/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index f73263ca..bc9f50da 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -76,7 +76,7 @@ paths: x-correlator: $ref: '#/components/headers/x-correlator' "400": - $ref: "#/components/responses/CreateSubscriptionBadRequest400" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": From 3dce73be3e6bcd3fe4d1f5efbf78eb8cc52f8b3d Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:21:00 +0200 Subject: [PATCH 18/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index bc9f50da..9d668137 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -108,7 +108,7 @@ paths: schema: $ref: '#/components/schemas/SubscriptionAsync' "400": - $ref: '#/components/responses/Generic400' + $ref: '#/components/responses/CreateSubscriptionBadRequest400' "401": $ref: '#/components/responses/Generic401' "403": From ed0c0652c455021ff8ac534f4bbe32b7e27412b1 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:26:31 +0200 Subject: [PATCH 19/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 9d668137..9389f551 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -124,7 +124,7 @@ paths: - apiName subscription summary: 'Retrieve a list of apiName event subscription' description: Retrieve a list of apiName event subscription(s) - operationId: retrieveSubscriptionList + operationId: retrieveApiNameSubscriptionList parameters: - $ref: '#/components/parameters/x-correlator' security: From 3487c67f0e00ed5a911ab9356db8a1bb22f7ef67 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:26:57 +0200 Subject: [PATCH 20/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 9389f551..7ca45c0c 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -140,6 +140,7 @@ paths: application/json: schema: type: array + minItems: 0 items: $ref: '#/components/schemas/Subscription' "400": From bae1d3b7735324862318736a00c44b0383bbdb2b Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:27:46 +0200 Subject: [PATCH 21/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 7ca45c0c..f4c2e597 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -159,7 +159,7 @@ paths: - apiName subscription summary: 'Retrieve a apiName event subscription' description: retrieve apiName subscription information for a given subscription. - operationId: retrieveSubscription + operationId: retrieveApiNameSubscription security: - openId: - event-type:subscriptions:read From 8a3b7a639cbe843456a577cef731a242c96d46fd Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:28:05 +0200 Subject: [PATCH 22/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index f4c2e597..516a8c07 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -192,7 +192,7 @@ paths: tags: - apiName subscription summary: 'Delete a apiName event subscription' - operationId: deleteSubscription + operationId: deleteApiNameSubscription description: delete a given apiName subscription. security: - openId: From 5c18686822abbf02fbaac5955a0a16e190dbab68 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:29:10 +0200 Subject: [PATCH 23/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 516a8c07..80a413c1 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -286,7 +286,9 @@ components: description: The address to which events shall be delivered using the selected protocol. example: "https://endpoint.example.com/webhook" sinkCredential: - $ref: '#/components/schemas/SinkCredential' + allOf: + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: '#/components/schemas/SinkCredential' types: description: | Camara Event types eligible to be delivered by this subscription. From d0d37cc0e9e797add68f4cfc7f64ad1a3830340a Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 08:29:42 +0200 Subject: [PATCH 24/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 80a413c1..d047bf99 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -333,7 +333,7 @@ components: initialEvent: type: boolean description: | - Set to `true` by APi consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. + Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered Up to API project decision to keep it. From e197380e6af79da3a886ceed618e94d6403a66d8 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:44:48 +0200 Subject: [PATCH 25/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- .../camara-cloudevents/event-subscription-template.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index d047bf99..deacdfde 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -342,7 +342,10 @@ components: properties: credentialType: type: string - enum: ["PLAIN", "ACCESSTOKEN", "REFRESHTOKEN"] + enum: + - PLAIN + - ACCESSTOKEN + - REFRESHTOKEN description: "The type of the credential." discriminator: propertyName: credentialType From 7c24dbf679c172dc163f32e1a958c36f76dedfeb Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:45:06 +0200 Subject: [PATCH 26/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index deacdfde..21059f20 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -129,7 +129,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - event-type:subscriptions:read + - api-name:read responses: "200": description: List of event subscription details From c8d1a4228366a43384a1a7670c0c99f77db0dbe8 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:45:40 +0200 Subject: [PATCH 27/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 21059f20..6ad6e5bc 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -377,7 +377,7 @@ components: format: date-time description: RECOMMENDED. An absolute UTC instant at which the token shall be considered expired. accessTokenType: - description: OPTIONAL. )Type of the access token (See https://tools.ietf.org/html/rfc6749#section-7.1). + description: OPTIONAL. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string default: bearer required: From 082d982b82427f18810e00d90c1b8e74c60d7121 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:46:16 +0200 Subject: [PATCH 28/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- .../camara-cloudevents/event-subscription-template.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 6ad6e5bc..2b0b18fd 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -356,7 +356,11 @@ components: description: A plain credential as a combination of an identifier and a secret. allOf: - $ref: "#/components/schemas/SinkCredential" - - properties: + - type: object + required: + - identifier + - secret + properties: identifier: description: The identifier might be an account or username. type: string From 9f830c412fe60140d5cbc72b0707ff3b27a54341 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:46:37 +0200 Subject: [PATCH 29/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 2b0b18fd..f9f5047a 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -383,7 +383,7 @@ components: accessTokenType: description: OPTIONAL. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string - default: bearer + default: Bearer required: - accessToken - accessTokenExpiresUtc From 357b3767e44f70e4f1aa1dcb84f186e144566b0a Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:47:05 +0200 Subject: [PATCH 30/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index f9f5047a..7eb58384 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -372,7 +372,8 @@ components: description: An access token credential. allOf: - $ref: "#/components/schemas/SinkCredential" - - properties: + - type: object + properties: accessToken: description: REQUIRED. An access token is a previously acquired token granting access to the target resource. type: string From 698f8a98b7eb382abdbb616ccb604d8d35625e73 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:48:07 +0200 Subject: [PATCH 31/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 7eb58384..97755b6a 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -437,7 +437,7 @@ components: properties: id: type: string - description: The unique identifier of the subscription in the scope of the subscription manager. + description: The unique identifier of the subscription in the scope of the subscription manager. NOTE: When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). example: 1119920371 status: type: string From 78c87d2902c79b49ac8cbd939f65ed729334ceae Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:49:28 +0200 Subject: [PATCH 32/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 97755b6a..9b792818 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -455,7 +455,7 @@ components: SubscriptionId: type: string - description: The event subscription identifier. + description: The unique identifier of the subscription in the scope of the subscription manager. example: qs15-h556-rt89-1298 CloudEvent: From 8f13c6d0c49ce8323f10df4306854ff91dbc9fd2 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:50:00 +0200 Subject: [PATCH 33/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 9b792818..918e5553 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -567,6 +567,10 @@ components: properties: headers: type: object + description: |- + A set of key/value pairs that is copied into the HTTP request as custom headers. + + NOTE: Use/Applicability of this concept has not been discussed in Commonalities under the scope of Meta Release v0.4. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it. additionalProperties: type: string method: From 1e81e940b055b8129bfa59efd32ea3b69432c976 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 11:50:33 +0200 Subject: [PATCH 34/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 918e5553..09cbdfc1 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -513,7 +513,7 @@ components: description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. example: '2018-04-05T17:31:00Z' - Event-typeEven: + Event-typeEvent: description: event structure for event-type event allOf: - $ref: '#/components/schemas/CloudEvent' From 3dc8a8628ac074520c13e467bd9edc46d7913b1c Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 12:00:22 +0200 Subject: [PATCH 35/68] Update event-subscription-template.yaml --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 09cbdfc1..b89cca30 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -482,7 +482,6 @@ components: datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' - example: application/json data: type: object description: Event details payload described in each CAMARA API and referenced by its type From 492010c86fc9b264175bbb59d1df060dc79c19c0 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 12:03:09 +0200 Subject: [PATCH 36/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index b89cca30..b52a2798 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -162,7 +162,7 @@ paths: operationId: retrieveApiNameSubscription security: - openId: - - event-type:subscriptions:read + - api-name:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' From 3b59582515fc3a3cf757e547f00ab99b4c526f18 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Thu, 2 May 2024 12:03:34 +0200 Subject: [PATCH 37/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index b52a2798..424b760d 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -196,7 +196,7 @@ paths: description: delete a given apiName subscription. security: - openId: - - event-type:subscriptions:delete + - api-name:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' From 3dc63e19d3b9b8137738a384c1d461ceb0eb66e8 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 3 May 2024 10:01:14 +0200 Subject: [PATCH 38/68] Update event-subscription-template.yaml Added 403 SUBSCRIPTION_MISTMATCH Added 400 INVALID_TOKEN Set enum for accessTokenType to Bearer Adds startsAt/expiresAt and make mandatory Add status description + enum Add 415 & 429 Error pour POST Add POST in the ENUM for the CallBack --- .../event-subscription-template.yaml | 89 +++++++++++++++++-- 1 file changed, 84 insertions(+), 5 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 424b760d..8b5a3550 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -112,9 +112,13 @@ paths: "401": $ref: '#/components/responses/Generic401' "403": - $ref: '#/components/responses/Generic403' + $ref: '#/components/responses/CreateSubscription403' "409": $ref: '#/components/responses/Generic409' + "415": + $ref: "#/components/responses/Generic415" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: '#/components/responses/Generic500' "503": @@ -384,10 +388,12 @@ components: accessTokenType: description: OPTIONAL. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string - default: Bearer + enum: + - Bearer required: - accessToken - accessTokenExpiresUtc + - accessTokenType RefreshTokenCredential: type: object description: An access token credential with a refresh token. @@ -437,14 +443,34 @@ components: properties: id: type: string - description: The unique identifier of the subscription in the scope of the subscription manager. NOTE: When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). example: 1119920371 + startsAt: + type: string + format: date-time + description: Date when the event subscription will begin/began + expiresAt: + type: string + format: date-time + description: Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. status: type: string - description: current status of the subscription - Management of subscriptionstate engine is not mandatory for now. - enum: ["REQUESTED", "ACTIVE", "EXPIRED", "DEACTIVATED"] + description: |- + Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details: + - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet. + - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative. + - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted. + - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` event. + - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its metainformation is kept). + enum: + - ACTIVATION_REQUESTED + - ACTIVE + - EXPIRED + - DEACTIVATE + - DELETED required: - id + - startsAt SubscriptionAsync: description: Response for a event-type subscription request managed asynchronously (Creation or Deletion) @@ -574,6 +600,9 @@ components: type: string method: type: string + description: The HTTP method to use for sending the message. + enum: + - POST MQTTSubscriptionRequest: allOf: @@ -682,6 +711,11 @@ components: status: 400 code: "INVALID_PROTOCOL" message: "Only HTTP is supported" + InvalidToken: + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" Generic400: description: Problem with the client request headers: @@ -708,6 +742,27 @@ components: status: 401 code: "UNAUTHENTICATED" message: "Request not authenticated due to missing, invalid, or expired credentials" + + CreateSubscription403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PermissionDenied: + value: + status: 403 + code: "PERMISSION_DENIED" + message: "Client does not have sufficient permissions to perform this action" + TokenMismatch: + value: + status: 403 + code: "SUSBCRIPTION_MISMATCH" + message: "Client mistmatches between tokens used" Generic403: description: Client does not have sufficient permission headers: @@ -747,6 +802,30 @@ components: status: 409 code: CONFLICT message: "The specified resource is in a conflict" + Generic415: + description: Unsupported Media Type + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + 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 + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + 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 headers: From a219aad829120717bf9eebdc0f38c680be6be484 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 10 May 2024 15:24:40 +0200 Subject: [PATCH 39/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 8b5a3550..75b6c822 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -296,7 +296,7 @@ components: types: description: | Camara Event types eligible to be delivered by this subscription. - Note : for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided + Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array items: From 8e06611e0087f6ed312115a40e0a015702dc2b29 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 10 May 2024 15:24:58 +0200 Subject: [PATCH 40/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 75b6c822..881322cc 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -508,6 +508,8 @@ components: datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + enum: + - application/json data: type: object description: Event details payload described in each CAMARA API and referenced by its type From 089bbe199556410bdaedf75f26fc006d0080f0e1 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 10 May 2024 15:26:02 +0200 Subject: [PATCH 41/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 881322cc..4261243f 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -491,7 +491,7 @@ components: - source - specversion - type - - data + - time properties: id: type: string From 6a25db715ff64bf024c4480c1d73519b07bc5102 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 15 May 2024 08:44:11 +0200 Subject: [PATCH 42/68] Update event-subscription-template.yaml fixed line 18 --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 4261243f..a5af3fd3 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -15,7 +15,7 @@ info: version: 0.1.0-wip externalDocs: description: Product documentation at CAMARA - url: hhttps://github.com/camaraproject/ + url: https://github.com/camaraproject/ servers: - url: '{apiRoot}/{apiName}/v0' variables: From c0d5e9aeae1f0d87e68b5bd7644e7fd70aec3df5 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 15 May 2024 12:16:18 +0200 Subject: [PATCH 43/68] Update event-subscription-template.yaml Reworked the subscription model as suggested by Pedro --- .../event-subscription-template.yaml | 363 +++++++++++------- 1 file changed, 218 insertions(+), 145 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index a5af3fd3..8fa67ed8 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -17,7 +17,7 @@ externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/ servers: - - url: '{apiRoot}/{apiName}/v0' + - url: "{apiRoot}/{apiName}/v0" variables: apiRoot: default: http://localhost:9091 @@ -27,26 +27,26 @@ servers: description: apiName will be replaced in WG by its value and not modelled as a variable tags: - name: apiName subscription - description: Operations to manage event subscriptions on event-type event + description: Operations to manage event subscriptions on event-type event paths: /subscriptions: post: tags: - apiName subscription - summary: 'Create a apiName event subscription' + summary: "Create a apiName event subscription" description: Create a apiName event subscription operationId: createApiNameSubscription parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" security: - openId: - - api-name:event-type:grant-level + - api-name:event-type:grant-level requestBody: content: application/json: schema: - $ref: '#/components/schemas/SubscriptionRequest' + $ref: "#/components/schemas/SubscriptionRequest" required: true callbacks: notifications: @@ -61,20 +61,20 @@ paths: `operationId` value will have to be replaced accordingly with WG API specific semantic operationId: postNotification parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudEvent" - + responses: "204": description: Successful notification headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/Generic400" "401": @@ -86,60 +86,60 @@ paths: "503": $ref: "#/components/responses/Generic503" security: - - { } + - {} responses: "201": description: Created headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: '#/components/schemas/Subscription' + $ref: "#/components/schemas/Subscription" "202": description: Request accepted to be processed. It applies for async creation process. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: '#/components/schemas/SubscriptionAsync' + $ref: "#/components/schemas/SubscriptionAsync" "400": - $ref: '#/components/responses/CreateSubscriptionBadRequest400' + $ref: "#/components/responses/CreateSubscriptionBadRequest400" "401": - $ref: '#/components/responses/Generic401' + $ref: "#/components/responses/Generic401" "403": - $ref: '#/components/responses/CreateSubscription403' + $ref: "#/components/responses/CreateSubscription403" "409": - $ref: '#/components/responses/Generic409' + $ref: "#/components/responses/Generic409" "415": $ref: "#/components/responses/Generic415" "429": $ref: "#/components/responses/Generic429" "500": - $ref: '#/components/responses/Generic500' + $ref: "#/components/responses/Generic500" "503": - $ref: '#/components/responses/Generic503' + $ref: "#/components/responses/Generic503" get: tags: - apiName subscription - summary: 'Retrieve a list of apiName event subscription' + summary: "Retrieve a list of apiName event subscription" description: Retrieve a list of apiName event subscription(s) operationId: retrieveApiNameSubscriptionList parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" security: - openId: - - api-name:read + - api-name:read responses: "200": description: List of event subscription details headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -148,40 +148,40 @@ paths: items: $ref: '#/components/schemas/Subscription' "400": - $ref: '#/components/responses/Generic400' + $ref: "#/components/responses/Generic400" "401": - $ref: '#/components/responses/Generic401' + $ref: "#/components/responses/Generic401" "403": - $ref: '#/components/responses/Generic403' + $ref: "#/components/responses/Generic403" "500": - $ref: '#/components/responses/Generic500' + $ref: "#/components/responses/Generic500" "503": - $ref: '#/components/responses/Generic503' + $ref: "#/components/responses/Generic503" /subscriptions/{subscriptionId}: get: tags: - apiName subscription - summary: 'Retrieve a apiName event subscription' + summary: "Retrieve a apiName event subscription" description: retrieve apiName subscription information for a given subscription. operationId: retrieveApiNameSubscription security: - openId: - - api-name:read + - api-name:read parameters: - $ref: "#/components/parameters/SubscriptionId" - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" responses: "200": description: OK headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: '#/components/schemas/Subscription' + $ref: "#/components/schemas/Subscription" "400": - $ref: '#/components/responses/SubscriptionIdRequired' + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -195,32 +195,32 @@ paths: delete: tags: - apiName subscription - summary: 'Delete a apiName event subscription' + summary: "Delete a apiName event subscription" operationId: deleteApiNameSubscription description: delete a given apiName subscription. security: - openId: - - api-name:delete + - api-name:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" responses: "204": description: apiName subscription deleted headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" "202": description: Request accepted to be processed. It applies for async deletion process. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: '#/components/schemas/SubscriptionAsync' + $ref: "#/components/schemas/SubscriptionAsync" "400": - $ref: '#/components/responses/SubscriptionIdRequired' + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -243,7 +243,7 @@ components: description: Subscription identifier that was obtained from the create event subscription operation required: true schema: - $ref: '#/components/schemas/SubscriptionId' + $ref: "#/components/schemas/SubscriptionId" x-correlator: name: x-correlator in: header @@ -272,7 +272,7 @@ components: message: type: string description: Detailed error description - + SubscriptionRequest: description: The request for creating a event-type event subscription type: object @@ -291,8 +291,8 @@ components: example: "https://endpoint.example.com/webhook" sinkCredential: allOf: - - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. - - $ref: '#/components/schemas/SinkCredential' + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" types: description: | Camara Event types eligible to be delivered by this subscription. @@ -302,9 +302,16 @@ components: items: type: string config: - $ref: '#/components/schemas/Config' + $ref: "#/components/schemas/Config" discriminator: propertyName: protocol + mapping: + HTTP: "#/components/schemas/HTTPSubscriptionRequest" + MQTT3: "#/components/schemas/MQTTSubscriptionRequest" + MQTT5: "#/components/schemas/MQTTSubscriptionRequest" + AMQP: "#/components/schemas/AMQPSubscriptionRequest" + NATS: "#/components/schemas/NATSSubscriptionRequest" + KAFKA: "#/components/schemas/ApacheKafkaSubscriptionRequest" Protocol: type: string @@ -323,7 +330,7 @@ components: - subscriptionDetail properties: subscriptionDetail: - $ref: '#/components/schemas/CreateSubscriptionDetail' + $ref: "#/components/schemas/CreateSubscriptionDetail" subscriptionExpireTime: type: string format: date-time @@ -344,13 +351,13 @@ components: SinkCredential: type: object properties: - credentialType: - type: string - enum: - - PLAIN - - ACCESSTOKEN - - REFRESHTOKEN - description: "The type of the credential." + credentialType: + type: string + enum: + - PLAIN + - ACCESSTOKEN + - REFRESHTOKEN + description: "The type of the credential." discriminator: propertyName: credentialType required: @@ -388,7 +395,7 @@ components: accessTokenType: description: OPTIONAL. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string - enum: + enum: - Bearer required: - accessToken @@ -434,50 +441,77 @@ components: Subscription: description: Represents a event-type subscription. + type: object required: + - sink + - protocol + - config + - types + - id - startsAt - - subscriptionId - allOf: - - $ref: '#/components/schemas/SubscriptionRequest' - - type: object - properties: - id: - type: string - description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). - example: 1119920371 - startsAt: - type: string - format: date-time - description: Date when the event subscription will begin/began - expiresAt: - type: string - format: date-time - description: Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. - status: - type: string - description: |- - Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details: - - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet. - - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative. - - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted. - - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` event. - - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its metainformation is kept). - enum: - - ACTIVATION_REQUESTED - - ACTIVE - - EXPIRED - - DEACTIVATE - - DELETED - required: - - id - - startsAt + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/webhook" + sinkCredential: + $ref: '#/components/schemas/SinkCredential' + types: + description: | + Camara Event types eligible to be delivered by this subscription. + Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided + at API project level. + type: array + items: + type: string + config: + $ref: '#/components/schemas/Config' + id: + type: string + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). + example: 1119920371 + startsAt: + type: string + format: date-time + description: Date when the event subscription will begin/began + expiresAt: + type: string + format: date-time + description: Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. + status: + type: string + description: |- + Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details: + - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet. + - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative. + - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted. + - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` event. + - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its metainformation is kept). + enum: + - ACTIVATION_REQUESTED + - ACTIVE + - EXPIRED + - DEACTIVATE + - DELETED + discriminator: + propertyName: protocol + mapping: + HTTP: '#/components/schemas/HTTPSubscriptionResponse' + MQTT3: '#/components/schemas/MQTTSubscriptionResponse' + MQTT5: '#/components/schemas/MQTTSubscriptionResponse' + AMQP: '#/components/schemas/AMQPSubscriptionResponse' + NATS: '#/components/schemas/NATSSubscriptionResponse' + KAFKA: '#/components/schemas/ApacheKafkaSubscriptionResponse' SubscriptionAsync: description: Response for a event-type subscription request managed asynchronously (Creation or Deletion) type: object properties: - id: - $ref: '#/components/schemas/SubscriptionId' + id: + $ref: "#/components/schemas/SubscriptionId" SubscriptionId: type: string @@ -497,29 +531,29 @@ components: type: string description: identifier of this event, that must be unique in the source context. source: - $ref: '#/components/schemas/Source' + $ref: "#/components/schemas/Source" type: - $ref: '#/components/schemas/Event-typeNotification' + $ref: "#/components/schemas/Event-typeNotification" 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) - enum: + enum: - "1.0" datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' enum: - - application/json + - application/json data: type: object description: Event details payload described in each CAMARA API and referenced by its type time: $ref: "#/components/schemas/DateTime" discriminator: - propertyName: 'type' + propertyName: "type" mapping: - org.camaraproject.api-name.v0.event-type: '#/components/schemas/Event-typeEvent' - org.camaraproject.api-name.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' + org.camaraproject.api-name.v0.event-type: "#/components/schemas/Event-typeEvent" + org.camaraproject.api-name.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds" Source: type: string @@ -538,26 +572,26 @@ components: type: string format: date-time description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. - example: '2018-04-05T17:31:00Z' + example: "2018-04-05T17:31:00Z" Event-typeEvent: - description: event structure for event-type event + description: event structure for event-type event allOf: - - $ref: '#/components/schemas/CloudEvent' + - $ref: "#/components/schemas/CloudEvent" - type: object EventSubscriptionEnds: - description: event structure for event subscription ends + description: event structure for event subscription ends allOf: - - $ref: '#/components/schemas/CloudEvent' + - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: - $ref: '#/components/schemas/SubscriptionEnds' + $ref: "#/components/schemas/SubscriptionEnds" SubscriptionEnds: description: Event detail structure for SUBSCRIPTION_ENDS event - type : object + type: object required: - terminationReason - subscriptionId @@ -580,31 +614,38 @@ components: - NETWORK_TERMINATED - SUBSCRIPTION_EXPIRED - HTTPSubscriptionRequest: allOf: - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/HTTPSettings" + + HTTPSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" - type: object properties: protocolSettings: $ref: "#/components/schemas/HTTPSettings" HTTPSettings: - type: object - properties: - headers: - type: object - description: |- - A set of key/value pairs that is copied into the HTTP request as custom headers. - - NOTE: Use/Applicability of this concept has not been discussed in Commonalities under the scope of Meta Release v0.4. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it. - additionalProperties: - type: string - method: - type: string - description: The HTTP method to use for sending the message. - enum: - - POST + type: object + properties: + headers: + type: object + description: |- + A set of key/value pairs that is copied into the HTTP request as custom headers. + + NOTE: Use/Applicability of this concept has not been discussed in Commonalities under the scope of Meta Release v0.4. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it. + additionalProperties: + type: string + method: + type: string + description: The HTTP method to use for sending the message. + enum: + - POST MQTTSubscriptionRequest: allOf: @@ -614,6 +655,14 @@ components: protocolSettings: $ref: "#/components/schemas/MQTTSettings" + MQTTSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/MQTTSettings" + MQTTSettings: type: object properties: @@ -635,6 +684,14 @@ components: AMQPSubscriptionRequest: allOf: - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/AMQPSettings" + + AMQPSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" - type: object properties: protocolSettings: @@ -653,7 +710,7 @@ components: linkProperties: type: object additionalProperties: - type: string + type: string ApacheKafkaSubscriptionRequest: allOf: @@ -663,33 +720,49 @@ components: protocolSettings: $ref: "#/components/schemas/ApacheKafkaSettings" + ApacheKafkaSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/ApacheKafkaSettings" + ApacheKafkaSettings: type: object properties: - topicName: - type: string - partitionKeyExtractor: - type: string - clientId: - type: string - ackMode: - type: integer + topicName: + type: string + partitionKeyExtractor: + type: string + clientId: + type: string + ackMode: + type: integer required: - topicName NATSSubscriptionRequest: allOf: - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/NATSSettings" + + NATSSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" - type: object properties: protocolSettings: $ref: "#/components/schemas/NATSSettings" - + NATSSettings: type: object properties: - subject: - type: string + subject: + type: string required: - subject responses: @@ -697,7 +770,7 @@ components: description: Problem with the client request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -722,7 +795,7 @@ components: description: Problem with the client request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -735,7 +808,7 @@ components: description: Authentication problem with the client request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -749,7 +822,7 @@ components: description: Client does not have sufficient permission headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -769,7 +842,7 @@ components: description: Client does not have sufficient permission headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -782,7 +855,7 @@ components: description: Resource Not Found headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -795,7 +868,7 @@ components: description: Conflict headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -832,7 +905,7 @@ components: description: Server error headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -845,7 +918,7 @@ components: description: Service unavailable. Typically the server is down. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -858,7 +931,7 @@ components: description: Problem with the client request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: From d14ddfc22ff7c5a01de3dff173f4d2842219b81a Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:20:32 +0200 Subject: [PATCH 44/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 8fa67ed8..3b9415bb 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -33,7 +33,7 @@ paths: /subscriptions: post: tags: - - apiName subscription + - Subscription summary: "Create a apiName event subscription" description: Create a apiName event subscription operationId: createApiNameSubscription From d8a33166fb3a558f49d74a519d4d7f45fc08100c Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:20:46 +0200 Subject: [PATCH 45/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 3b9415bb..4419f656 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -26,7 +26,7 @@ servers: default: camaraAPI description: apiName will be replaced in WG by its value and not modelled as a variable tags: - - name: apiName subscription + - name: Subscription description: Operations to manage event subscriptions on event-type event paths: From 1608aa55e19f2331d722d0609f91ac15d5822480 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:22:34 +0200 Subject: [PATCH 46/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 4419f656..6229d686 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -125,7 +125,7 @@ paths: $ref: "#/components/responses/Generic503" get: tags: - - apiName subscription + - Subscription summary: "Retrieve a list of apiName event subscription" description: Retrieve a list of apiName event subscription(s) operationId: retrieveApiNameSubscriptionList From 315cf0c28119c81264685686c48d73d3fb9b1c30 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:23:22 +0200 Subject: [PATCH 47/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 6229d686..480edb47 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -52,8 +52,6 @@ paths: notifications: "{$request.body#/sink}": post: - tags: - - notifications callback summary: "notifications callback" description: | Important: this endpoint is to be implemented by the API consumer. From 067f8fe7a35b4c320ba47ae6deac6abf7234c544 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:23:47 +0200 Subject: [PATCH 48/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 480edb47..8c7f218f 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -158,7 +158,7 @@ paths: /subscriptions/{subscriptionId}: get: tags: - - apiName subscription + - Subscription summary: "Retrieve a apiName event subscription" description: retrieve apiName subscription information for a given subscription. operationId: retrieveApiNameSubscription From 24473109b34919ef0bfaeb73359c309cd4929ae1 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:24:05 +0200 Subject: [PATCH 49/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 8c7f218f..802fe8f8 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -192,7 +192,7 @@ paths: $ref: "#/components/responses/Generic503" delete: tags: - - apiName subscription + - Subscription summary: "Delete a apiName event subscription" operationId: deleteApiNameSubscription description: delete a given apiName subscription. From 931177bade55c36a6a687f9bfd4589bba3c9adeb Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:24:47 +0200 Subject: [PATCH 50/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 802fe8f8..f711ff84 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -389,7 +389,7 @@ components: accessTokenExpiresUtc: type: string format: date-time - description: RECOMMENDED. An absolute UTC instant at which the token shall be considered expired. + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. accessTokenType: description: OPTIONAL. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string From d4bca9ddc9b2becd5f0a204c75368a6c9be67da6 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:25:43 +0200 Subject: [PATCH 51/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index f711ff84..369a1fb4 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -391,7 +391,7 @@ components: format: date-time description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. accessTokenType: - description: OPTIONAL. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - Bearer From 9ca3e2d51255b490bf1862717b6062f36812dc38 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:26:21 +0200 Subject: [PATCH 52/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 369a1fb4..86d31093 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -394,7 +394,7 @@ components: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - - Bearer + - bearer required: - accessToken - accessTokenExpiresUtc From 058ab1fade32ee4818626d5149959ab281a89e38 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 21:33:40 +0200 Subject: [PATCH 53/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 86d31093..b5e59e57 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -85,6 +85,7 @@ paths: $ref: "#/components/responses/Generic503" security: - {} + - notificationsBearerAuth: [] responses: "201": From 6278bb1b1c03c16fddccb0f403ee03daa951b83f Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 22:08:34 +0200 Subject: [PATCH 54/68] Update event-subscription-template.yaml Add 422 error for multi event type subscription --- .../event-subscription-template.yaml | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index b5e59e57..a7e308eb 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -116,6 +116,8 @@ paths: $ref: "#/components/responses/Generic409" "415": $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/CreateSubscription422" "429": $ref: "#/components/responses/Generic429" "500": @@ -287,7 +289,7 @@ components: type: string format: url description: The address to which events shall be delivered using the selected protocol. - example: "https://endpoint.example.com/webhook" + example: "https://endpoint.example.com/sink" sinkCredential: allOf: - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. @@ -455,7 +457,7 @@ components: type: string format: url description: The address to which events shall be delivered using the selected protocol. - example: "https://endpoint.example.com/webhook" + example: "https://endpoint.example.com/sink" sinkCredential: $ref: '#/components/schemas/SinkCredential' types: @@ -888,6 +890,21 @@ components: example: code: UNSUPPORTED_MEDIA_TYPE message: "The specified media type is not supported" + CreateSubscription422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PermissionDenied: + value: + status: 422 + code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" + message: "Multi event types subscription not managed" Generic429: description: Too Many Requests headers: From a971895cf8bc2b8e813517c5fdca9664cecd9740 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Sun, 26 May 2024 22:18:10 +0200 Subject: [PATCH 55/68] Update event-subscription-template.yaml Add 410 & 429 for callback --- .../event-subscription-template.yaml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index a7e308eb..5ed3ad80 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -79,6 +79,10 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -878,6 +882,19 @@ components: status: 409 code: CONFLICT message: "The specified resource is in a conflict" + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 410 + code: GONE + message: "The specified resource is no longer available at the requested address" Generic415: description: Unsupported Media Type headers: From 9374db1d4231d1ce1005af4f3677ad5f513a8e60 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 27 May 2024 16:38:46 +0200 Subject: [PATCH 56/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- .../event-subscription-template.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 5ed3ad80..5b3bef15 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -413,6 +413,18 @@ components: - $ref: "#/components/schemas/AccessTokenCredential" - type: object properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). + type: string + enum: + - Bearer refreshToken: description: REQUIRED. An refresh token credential used to acquire access tokens. type: string From 8c63787792b686951e9d6821e2d32e6a6342102e Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 27 May 2024 16:40:02 +0200 Subject: [PATCH 57/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 5b3bef15..e8abfb3f 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -433,6 +433,9 @@ components: format: uri description: REQUIRED. A URL at which the refresh token can be traded for an access token. required: + - accessToken + - accessTokenExpiresUtc + - accessTokenType - refreshToken - refreshTokenEndpoint From f75a72675a2c6062fd484de23872b048e8eb3b9c Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 27 May 2024 16:41:28 +0200 Subject: [PATCH 58/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- .../camara-cloudevents/event-subscription-template.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index e8abfb3f..261de5b6 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -806,6 +806,11 @@ components: status: 400 code: "INVALID_PROTOCOL" message: "Only HTTP is supported" + InvalidCredential: + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" InvalidToken: value: status: 400 From b2c7b724595b736a49802186720a3dd1580a8b07 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 11:36:40 +0200 Subject: [PATCH 59/68] Update event-subscription-template.yaml Took latest comments from Pedro. --- .../event-subscription-template.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 261de5b6..970cb11c 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -365,6 +365,10 @@ components: description: "The type of the credential." discriminator: propertyName: credentialType + mapping: + PLAIN: "#/components/schemas/PlainCredential" + ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" + REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential" required: - credentialType PlainCredential: @@ -410,7 +414,7 @@ components: type: object description: An access token credential with a refresh token. allOf: - - $ref: "#/components/schemas/AccessTokenCredential" + - $ref: "#/components/schemas/SinkCredential" - type: object properties: accessToken: @@ -424,7 +428,7 @@ components: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - - Bearer + - bearer refreshToken: description: REQUIRED. An refresh token credential used to acquire access tokens. type: string @@ -535,7 +539,7 @@ components: SubscriptionId: type: string - description: The unique identifier of the subscription in the scope of the subscription manager. + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. example: qs15-h556-rt89-1298 CloudEvent: @@ -862,7 +866,7 @@ components: value: status: 403 code: "SUSBCRIPTION_MISMATCH" - message: "Client mistmatches between tokens used" + message: "Inconsistent access token for requested events subscription" Generic403: description: Client does not have sufficient permission headers: From c1f3c49eb66008cea793a56a1e79ace10d3d817d Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 14:08:00 +0200 Subject: [PATCH 60/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 970cb11c..10a756af 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -496,7 +496,7 @@ components: id: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). - example: 1119920371 + example: '1119920371' startsAt: type: string format: date-time From baccfdac3872870178de7e7b8a27e14a9e54ed01 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 14:17:06 +0200 Subject: [PATCH 61/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- .../event-subscription-template.yaml | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 10a756af..2de49c63 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -583,14 +583,17 @@ components: type: string format: uri-reference minLength: 1 - description: "Identifies the context in which an event happened in the specific Provider Implementation." - example: - - https://github.com/cloudevents - - mailto:cncf-wg-serverless@lists.cncf.io - - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - cloudevents/spec/pull/123 - - /sensors/tn-1234567/alerts - - 1-555-123-4567 + 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" DateTime: type: string From c38654f287100456ccc6a82af22f455349dde734 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 14:39:39 +0200 Subject: [PATCH 62/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 2de49c63..a975e2a4 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -932,6 +932,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: 415 code: UNSUPPORTED_MEDIA_TYPE message: "The specified media type is not supported" CreateSubscription422: From b5a14a9c57533ad2f483b0f618b79c931f6c4003 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 14:58:31 +0200 Subject: [PATCH 63/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index a975e2a4..76663e23 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -960,6 +960,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: 429 code: TOO_MANY_REQUESTS message: "Endpoint does not support as many requests per time slot" Generic500: From 22c7b875ae3b2a8b852860284327d40e900231b3 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 15:04:51 +0200 Subject: [PATCH 64/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 76663e23..4af1503c 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -350,7 +350,7 @@ components: type: boolean description: | Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. - Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered + Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered Up to API project decision to keep it. SinkCredential: From 1d1d5ec170810d5bf03d6fbff9637bfdb3c9d8a4 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 15:04:58 +0200 Subject: [PATCH 65/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 4af1503c..f425ad94 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -655,7 +655,7 @@ components: - type: object properties: protocolSettings: - $ref: "#/components/schemas/HTTPSettings" + $ref: "#/components/schemas/HTTPSettings" HTTPSettings: type: object From 7910c30d7b49ff578a47c789212f08e4908b5227 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 15:05:06 +0200 Subject: [PATCH 66/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index f425ad94..918b79a8 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -722,7 +722,7 @@ components: - type: object properties: protocolSettings: - $ref: "#/components/schemas/AMQPSettings" + $ref: "#/components/schemas/AMQPSettings" AMQPSettings: type: object From ba673b73d6155b6719b45a8e7e02757509880f7b Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 28 May 2024 15:07:45 +0200 Subject: [PATCH 67/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 918b79a8..6e37e78b 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -783,7 +783,7 @@ components: - type: object properties: protocolSettings: - $ref: "#/components/schemas/NATSSettings" + $ref: "#/components/schemas/NATSSettings" NATSSettings: type: object From 07b6ad10dfca548e0159d9e9c38b68a61ef41ecc Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 29 May 2024 08:19:53 +0200 Subject: [PATCH 68/68] Update artifacts/camara-cloudevents/event-subscription-template.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 6e37e78b..00045fb3 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -539,7 +539,7 @@ components: SubscriptionId: type: string - description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). example: qs15-h556-rt89-1298 CloudEvent: