Skip to content

Commit b720866

Browse files
rartychrartych
authored
Merge pull request #418 from tlohmar/main
Clarification of the protocol and sink properties in the subscription…
2 parents d9bdebb + b2c10b7 commit b720866

File tree

1 file changed

+6
-6
lines changed

1 file changed

+6
-6
lines changed

‎documentation/API-design-guidelines.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ This document captures guidelines for the API design in CAMARA project. These gu
8383
- [subscription-ends event](#subscription-ends-event)
8484
- [Error definition for event notification](#error-definition-for-event-notification)
8585
- [Correlation Management](#correlation-management)
86-
- [Security Considerations](#security-considerations)
86+
- [Notifications Security Considerations](#notifications-security-considerations)
8787
- [Abuse Protection](#abuse-protection)
8888
- [Notification examples](#notification-examples)
8989
- [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier)
@@ -1668,8 +1668,8 @@ Providing this capability is optional for any CAMARA API depending on UC require
16681668
If this capability is present in CAMARA API, the following attributes **must** be used in the POST request :
16691669
16701670
| attribute name | type | attribute description | cardinality |
1671-
|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
1672-
| sink | string | https callback address where the notification must be POST-ed, `format: uri` should be used to require a string that is compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). | mandatory |
1671+
|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
1672+
| sink | string | https callback address where the notification must be POST-ed, `format: uri` should be used to require a string that is compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). The [security considerations](#notifications-security-considerations) should be followed. | mandatory |
16731673
| sinkCredential | object | Sink credential provides authentication or authorization information necessary to enable delivery of events to a target. In order to be updated in future this object is polymorphic. See detail below. It is RECOMMENDED for subscription consumer to provide credential to protect notification endpoint. | optional |
16741674
16751675
Several types of `sinkCredential` could be available in the future, but for now only access token credential is managed.
@@ -1759,8 +1759,8 @@ The following table provides `/subscriptions` attributes
17591759
17601760
| name | type | attribute description | cardinality |
17611761
|----------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
1762-
| protocol | string | Identifier of a delivery protocol. **Only** `HTTP` **is allowed for now**. | Mandatory |
1763-
| sink | string | The address to which events shall be delivered, using the HTTP protocol, `format: uri` should be used to require a string that is compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). | mandatory |
1762+
| protocol | string | Identifier of a delivery protocol for the event notifications. The values follow the definitions of the [CloudEvent specification](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#protocol). **Only** `HTTP` **is allowed for now**. | mandatory |
1763+
| sink | string | The URL, to which event notifications shall be sent - `format: uri` should be used to require a string that is compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). The URI-scheme shall be set according to the definition of the `protocol` value, e.g. the URI-scheme is `https` when `HTTP`is the value of the `protocol` property. The [security considerations](#notifications-security-considerations) should be followed. | mandatory |
17641764
| sinkCredential | object | Sink credential provides authorization information necessary to enable delivery of events to a target. In order to be updated in future this object is polymorphic. See detail below. To protect the notification endpoint providing sinkCredential is RECOMMENDED. <br> The sinkCredential must **not** be present in `POST` and `GET` responses. | optional |
17651765
| types | string | Type of event subscribed. This attribute **must** be present in the `POST` request. It is required by API project to provide an enum for this attribute. `type` must follow the format: `org.camaraproject.<api-name>.<api-version>.<event-name>` with the `api-version` with letter `v` and the major version like ``org.camaraproject.device-roaming-subscriptions.v1.roaming-status`` - Note: An array of types could be passed **but as of now only one value MUST passed**. Use of multiple value will be open later at API level. | mandatory |
17661766
| config | object | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like ``subscriptionExpireTime``, ``subscriptionMaxEvents`` or ``initialEvent``. See detail below. | mandatory |
@@ -1999,7 +1999,7 @@ To manage correlation between the subscription management and the event notifica
19991999
20002000
Note: There is no normative enforcement to use any of these patterns, and they could be used on agreement between API consumer & providers.
20012001
2002-
#### Security Considerations
2002+
#### Notifications Security Considerations
20032003
20042004
As notifications may carry sensitive information, privacy and security have to be considered.
20052005

0 commit comments

Comments
 (0)