From cf3896f7385421edc3cdc35acd11810dd660f9f7 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Thu, 2 May 2024 21:18:32 +0200 Subject: [PATCH 1/7] x-correlator_guideline_format_convention --- artifacts/CAMARA_common.yaml | 638 +++++++++++---------- artifacts/notification-as-cloud-event.yaml | 56 +- documentation/API-design-guidelines.md | 10 +- 3 files changed, 360 insertions(+), 344 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index a0fe5a35..1169f667 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -1,326 +1,340 @@ openapi: 3.0.3 info: - title: Camara common data types - description: Common data types for Camara APIs - contact: - email: sp-com@lists.camaraproject.org - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.4.0 + title: Camara common data types + description: Common data types for Camara APIs + contact: + email: sp-com@lists.camaraproject.org + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 0.4.0 paths: {} components: - schemas: - TimePeriod: - properties: - startDate: - type: string - format: date-time - description: An instant of time, starting of the TimePeriod. - endDate: - type: string - format: date-time - description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. - required: - - startDate - ErrorInfo: - type: object - required: - - message - - status - - code - properties: - message: - type: string - description: A human readable description of what the event represent - status: - type: integer - description: HTTP response status code - code: - type: string - description: Friendly Code to describe the error - Device: - description: | - End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. - The developer can choose to provide the below specified device identifiers: - * `ipv4Address` - * `ipv6Address` - * `phoneNumber` - * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. - type: object - properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/DeviceIpv4Addr" - ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" - minProperties: 1 + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + schemas: + TimePeriod: + properties: + startDate: + type: string + format: date-time + description: An instant of time, starting of the TimePeriod. + endDate: + type: string + format: date-time + description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. + required: + - startDate + ErrorInfo: + type: object + required: + - message + - status + - code + properties: + message: + type: string + description: A human readable description of what the event represent + status: + type: integer + description: HTTP response status code + code: + type: string + description: Friendly Code to describe the error + Device: + description: | + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + The developer can choose to provide the below specified device identifiers: + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 - PhoneNumber: - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" - NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. - type: string - example: "123456789@domain.com" + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@domain.com" - DeviceIpv4Addr: - type: object - description: | - The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). - If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. - If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) - In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. - properties: - publicAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - privateAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - publicPort: - $ref: "#/components/schemas/Port" - anyOf: - - required: [publicAddress, privateAddress] - - required: [publicAddress, publicPort] - example: - publicAddress: "84.125.93.10" - publicPort: 59765 + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + publicAddress: "84.125.93.10" + publicPort: 59765 - SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" - Port: - description: TCP or UDP port number - type: integer - minimum: 0 - maximum: 65535 + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 - DeviceIpv6Address: - description: | - The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). - type: string - format: ipv6 - example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - responses: - InvalidArgument: - description: Invalid Argument - 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 - Conflict: - description: Conflict - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: Request could not be processed due to a conflict - FailedPrecondition: - description: Failed precondition - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 412 - code: FAILED_PRECONDITION - message: Request cannot be executed in the current system state. - OutOfRange: - description: Out of Range - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: OUT_OF_RANGE - message: Client specified an invalid range - Unauthenticated: - description: Not Authenticated - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired - PermissionDenied: - description: Permission denied - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform - NotFound: - description: Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: The specified resource is not found. - Aborted: - description: Aborted - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: ABORTED - message: Request aborted. - AlreadyExists: - description: Already Exists - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: ALREADY_EXISTS - message: The resource that a client tried to create already exists. - TooManyRequests: - description: Too Many Requests - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 429 - code: TOO_MANY_REQUESTS - message: Either out of resource quota or reaching rate limiting. - Internal: - description: Internal Error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: Unknown server error.Typically a server bug. - BadGateway: - description: Bad Gateway - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 502 - code: BAD_GATEWAY - message: Couldn't reach an upstream internal service. - Unavailable: - description: Service Unavailable - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: UNAVAILABLE - message: Service unavailable - Timeout: - description: Timeout - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 504 - code: TIMEOUT - message: Request timeout exceeded - NotImplemented: - description: Not Implemented - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 501 - code: NOT_IMPLEMENTED - message: This functionality is not implemented yet - AuthenticationRequired: - description: Authentication Required - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required - NotFoundAndOutOfRange: - description: Out Of Range and Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - OutOfRange: - value: - status: 404 - code: OUT_OF_RANGE - message: Out Of Range - NotFound: - value: - status: 404 - code: NOT_FOUND - message: Not found - MethodNotAllowed: - description: Method not allowed - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 405 - code: METHOD_NOT_ALLOWED - message: The requested method is not allowed/supported on the target - NotAcceptable: - description: Not Acceptable - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 406 - code: NOT_ACCEPTABLE - message: The server can't produce a response matching the content requested - by the client through Accept-* headers - UnsupportedMediaType: - description: Unsupported Media Type - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: The server refuses to accept the request because the payload format - is in an unsupported format. + responses: + InvalidArgument: + description: Invalid Argument + 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 + Conflict: + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: CONFLICT + message: Request could not be processed due to a conflict + FailedPrecondition: + description: Failed precondition + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 412 + code: FAILED_PRECONDITION + message: Request cannot be executed in the current system state. + OutOfRange: + description: Out of Range + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range + Unauthenticated: + description: Not Authenticated + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired + PermissionDenied: + description: Permission denied + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + Aborted: + description: Aborted + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: ABORTED + message: Request aborted. + AlreadyExists: + description: Already Exists + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + TooManyRequests: + description: Too Many Requests + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + Internal: + description: Internal Error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 500 + code: INTERNAL + message: Unknown server error.Typically a server bug. + BadGateway: + description: Bad Gateway + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 502 + code: BAD_GATEWAY + message: Couldn't reach an upstream internal service. + Unavailable: + description: Service Unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: UNAVAILABLE + message: Service unavailable + Timeout: + description: Timeout + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded + NotImplemented: + description: Not Implemented + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet + AuthenticationRequired: + description: Authentication Required + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required + NotFoundAndOutOfRange: + description: Out Of Range and Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + OutOfRange: + value: + status: 404 + code: OUT_OF_RANGE + message: Out Of Range + NotFound: + value: + status: 404 + code: NOT_FOUND + message: Not found + MethodNotAllowed: + description: Method not allowed + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target + NotAcceptable: + description: Not Acceptable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 406 + code: NOT_ACCEPTABLE + message: + The server can't produce a response matching the content requested + by the client through Accept-* headers + UnsupportedMediaType: + description: Unsupported Media Type + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: + The server refuses to accept the request because the payload format + is in an unsupported format. diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 1da50997..f327853e 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -74,7 +74,7 @@ paths: URL, i.e.: notifications won't be sent to /event-notification/vX/your_webhook_notification_url. operationId: sendEvent parameters: - - $ref: "#/components/parameters/X-Correlator" + - $ref: "#/components/parameters/x-correlator" requestBody: required: true content: @@ -89,23 +89,23 @@ paths: 201: description: Created headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" 202: description: Accepted headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" 204: description: No Content headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" 200: description: Ok headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -208,13 +208,13 @@ components: time: $ref: "#/components/schemas/DateTime" headers: - X-Correlator: + x-correlator: description: Correlation id for the different services schema: type: string parameters: - X-Correlator: - name: X-Correlator + x-correlator: + name: x-correlator in: header description: Correlation id for the different services schema: @@ -224,8 +224,8 @@ components: Generic400: description: Problem with the client request headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -237,8 +237,8 @@ components: Generic401: description: Authentication problem with the client request headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -250,8 +250,8 @@ components: Generic403: description: Client does not have sufficient permission headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -263,8 +263,8 @@ components: Generic410: description: Gone headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -275,8 +275,8 @@ components: Generic415: description: Unsupported Media Type headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -287,8 +287,8 @@ components: Generic429: description: Too Many Requests headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -299,8 +299,8 @@ components: Generic500: description: Server error headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -312,8 +312,8 @@ components: Generic503: description: Service unavailable. Typically the server is down. headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 878aadad..a2a1d5ab 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -846,11 +846,13 @@ With the aim of standardizing the request observability and traceability process | Name | Description | Type | Location | Required by API Consumer | Required in OAS Definition | Example | |---|---|---|---|---|---|---| -| `X-Correlator`| Service correlator to make E2E observability | String | Request/Response | No | Yes | b4333c46-49c0-4f62-80d7-f0ef930f1c46 | +| `x-correlator`| Service correlator to make E2E observability | String | Request/Response | No | Yes | b4333c46-49c0-4f62-80d7-f0ef930f1c46 | -When the API Consumer includes the "X-Correlator" header in the request, the API provider must include it in the response with the same value that was used in the request. Otherwise, it is optional to include the "X-Correlator" header in the response with any valid value. Recommendation is to use UUID for values. +When the API Consumer includes the "x-correlator" header in the request, the API provider must include it in the response with the same value that was used in the request. Otherwise, it is optional to include the "x-correlator" header in the response with any valid value. Recommendation is to use UUID for values. -In notification scenarios (i.e. POST request sent towards the listener to the `webhook.notificationUrl` indicated), the use of the "X-Correlator" is supported for the same aim as well. When the API request includes the "X-Correlator" header, it is recommended for the listener to include it in the response with the same value as was used in the request. Otherwise, it is optional to include the "X-Correlator" header in the response with any valid value. +In notification scenarios (i.e. POST request sent towards the listener to the `webhook.notificationUrl` indicated), the use of the "x-correlator" is supported for the same aim as well. When the API request includes the "x-correlator" header, it is recommended for the listener to include it in the response with the same value as was used in the request. Otherwise, it is optional to include the "x-correlator" header in the response with any valid value. + +NOTE: HTTP headers are case insensitive. The use of the naming `x-correlator` is a guideline to align the format across CAMARA APIs. ## 10. Security @@ -1501,7 +1503,7 @@ For consistency across CAMARA APIs, the uniform CloudEvents model must be used w | ... | ... | Specific attribute(s) related to the notification event | ... | -Note: For operational and troubleshooting purposes it is relevant to accommodate use of `X-Correlator` header attribute. API listener implementations have to be ready to support and receive this data. +Note: For operational and troubleshooting purposes it is relevant to accommodate use of `x-correlator` header attribute. API listener implementations have to be ready to support and receive this data. Specific event notification type "subscription-ends" is defined to inform listener about subscription termination. It is used when the `subscriptionExpireTime` or `subscriptionMaxEvents` has been reached, or, if the API server has to stop sending notification prematurely. For this specific event, the `data` must feature `terminationReason` attribute. Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example if a client request a `subscriptionMaxEvents` to 2, later, received 2 notification, then a third notification will be send for "subscription-ends") From f6cc8fd6bc527a970662b6ef1635eead92894d27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Fri, 17 May 2024 16:38:51 +0200 Subject: [PATCH 2/7] Update artifacts/CAMARA_common.yaml Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> --- artifacts/CAMARA_common.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 1169f667..d6dad6ef 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -7,7 +7,8 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.4.0 + version: wip + paths: {} components: headers: From b0b5906f0f7a649d208499c1c360c4c1859ebe96 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 17 May 2024 16:55:59 +0200 Subject: [PATCH 3/7] adding_410_common_yaml_and_fix_typos_in_cloud_event --- artifacts/CAMARA_common.yaml | 11 +++++++++++ artifacts/notification-as-cloud-event.yaml | 3 +++ 2 files changed, 14 insertions(+) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index d6dad6ef..199babec 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -339,3 +339,14 @@ components: message: The server refuses to accept the request because the payload format is in an unsupported format. + Gone: + description: Gone + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 410 + code: GONE + message: + Access to the target resource is no longer available. diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index f327853e..7594248e 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -270,6 +270,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: 400 code: GONE message: "Access to the target resource is no longer available." Generic415: @@ -282,6 +283,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: 415 code: UNSUPPORTED_MEDIA_TYPE message: "The specified media type is not supported" Generic429: @@ -294,6 +296,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 bc75a74079dfffd7a95f23e254974b5dda18c374 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 17 May 2024 16:58:16 +0200 Subject: [PATCH 4/7] fix_status_typo --- artifacts/notification-as-cloud-event.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 7594248e..4f0a5b44 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -270,7 +270,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 400 + status: 410 code: GONE message: "Access to the target resource is no longer available." Generic415: From 45fe0ded6f93cf4c31ef1e830a1091526e669e9d Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Thu, 23 May 2024 14:51:33 +0200 Subject: [PATCH 5/7] Update CAMARA_common.yaml 1-space indentation for compliance with current style --- artifacts/CAMARA_common.yaml | 674 +++++++++++++++++------------------ 1 file changed, 337 insertions(+), 337 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 199babec..be3c4b6b 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -1,352 +1,352 @@ openapi: 3.0.3 info: - title: Camara common data types - description: Common data types for Camara APIs - contact: - email: sp-com@lists.camaraproject.org - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + title: Camara common data types + description: Common data types for Camara APIs + contact: + email: sp-com@lists.camaraproject.org + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip paths: {} components: - headers: - x-correlator: - description: Correlation id for the different services - schema: - type: string - parameters: - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - type: string - schemas: - TimePeriod: - properties: - startDate: - type: string - format: date-time - description: An instant of time, starting of the TimePeriod. - endDate: - type: string - format: date-time - description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. - required: - - startDate - ErrorInfo: - type: object - required: - - message - - status - - code - properties: - message: - type: string - description: A human readable description of what the event represent - status: - type: integer - description: HTTP response status code - code: - type: string - description: Friendly Code to describe the error - Device: - description: | - End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. - The developer can choose to provide the below specified device identifiers: - * `ipv4Address` - * `ipv6Address` - * `phoneNumber` - * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. - type: object - properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/DeviceIpv4Addr" - ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" - minProperties: 1 + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + schemas: + TimePeriod: + properties: + startDate: + type: string + format: date-time + description: An instant of time, starting of the TimePeriod. + endDate: + type: string + format: date-time + description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. + required: + - startDate + ErrorInfo: + type: object + required: + - message + - status + - code + properties: + message: + type: string + description: A human readable description of what the event represent + status: + type: integer + description: HTTP response status code + code: + type: string + description: Friendly Code to describe the error + Device: + description: | + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + The developer can choose to provide the below specified device identifiers: + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 - PhoneNumber: - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" - NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. - type: string - example: "123456789@domain.com" + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@domain.com" - DeviceIpv4Addr: - type: object - description: | - The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). - If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. - If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) - In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. - properties: - publicAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - privateAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - publicPort: - $ref: "#/components/schemas/Port" - anyOf: - - required: [publicAddress, privateAddress] - - required: [publicAddress, publicPort] - example: - publicAddress: "84.125.93.10" - publicPort: 59765 + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + publicAddress: "84.125.93.10" + publicPort: 59765 - SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" - Port: - description: TCP or UDP port number - type: integer - minimum: 0 - maximum: 65535 + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 - DeviceIpv6Address: - description: | - The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). - type: string - format: ipv6 - example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - responses: - InvalidArgument: - description: Invalid Argument - 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 - Conflict: - description: Conflict - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: Request could not be processed due to a conflict - FailedPrecondition: - description: Failed precondition - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 412 - code: FAILED_PRECONDITION - message: Request cannot be executed in the current system state. - OutOfRange: - description: Out of Range - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: OUT_OF_RANGE - message: Client specified an invalid range - Unauthenticated: - description: Not Authenticated - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired - PermissionDenied: - description: Permission denied - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform - NotFound: - description: Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: The specified resource is not found. - Aborted: - description: Aborted - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: ABORTED - message: Request aborted. - AlreadyExists: - description: Already Exists - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: ALREADY_EXISTS - message: The resource that a client tried to create already exists. - TooManyRequests: - description: Too Many Requests - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 429 - code: TOO_MANY_REQUESTS - message: Either out of resource quota or reaching rate limiting. - Internal: - description: Internal Error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: Unknown server error.Typically a server bug. - BadGateway: - description: Bad Gateway - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 502 - code: BAD_GATEWAY - message: Couldn't reach an upstream internal service. - Unavailable: - description: Service Unavailable - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: UNAVAILABLE - message: Service unavailable - Timeout: - description: Timeout - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 504 - code: TIMEOUT - message: Request timeout exceeded - NotImplemented: - description: Not Implemented - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 501 - code: NOT_IMPLEMENTED - message: This functionality is not implemented yet - AuthenticationRequired: - description: Authentication Required - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required - NotFoundAndOutOfRange: - description: Out Of Range and Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - OutOfRange: - value: - status: 404 - code: OUT_OF_RANGE - message: Out Of Range - NotFound: - value: - status: 404 - code: NOT_FOUND - message: Not found - MethodNotAllowed: - description: Method not allowed - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 405 - code: METHOD_NOT_ALLOWED - message: The requested method is not allowed/supported on the target - NotAcceptable: - description: Not Acceptable - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 406 - code: NOT_ACCEPTABLE - message: - The server can't produce a response matching the content requested - by the client through Accept-* headers - UnsupportedMediaType: - description: Unsupported Media Type - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: - The server refuses to accept the request because the payload format - is in an unsupported format. - Gone: - description: Gone - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 410 - code: GONE - message: - Access to the target resource is no longer available. + responses: + InvalidArgument: + description: Invalid Argument + 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 + Conflict: + description: Conflict + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: CONFLICT + message: Request could not be processed due to a conflict + FailedPrecondition: + description: Failed precondition + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 412 + code: FAILED_PRECONDITION + message: Request cannot be executed in the current system state. + OutOfRange: + description: Out of Range + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range + Unauthenticated: + description: Not Authenticated + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired + PermissionDenied: + description: Permission denied + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + Aborted: + description: Aborted + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: ABORTED + message: Request aborted. + AlreadyExists: + description: Already Exists + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + TooManyRequests: + description: Too Many Requests + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + Internal: + description: Internal Error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 500 + code: INTERNAL + message: Unknown server error.Typically a server bug. + BadGateway: + description: Bad Gateway + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 502 + code: BAD_GATEWAY + message: Couldn't reach an upstream internal service. + Unavailable: + description: Service Unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: UNAVAILABLE + message: Service unavailable + Timeout: + description: Timeout + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded + NotImplemented: + description: Not Implemented + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet + AuthenticationRequired: + description: Authentication Required + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required + NotFoundAndOutOfRange: + description: Out Of Range and Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + OutOfRange: + value: + status: 404 + code: OUT_OF_RANGE + message: Out Of Range + NotFound: + value: + status: 404 + code: NOT_FOUND + message: Not found + MethodNotAllowed: + description: Method not allowed + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target + NotAcceptable: + description: Not Acceptable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 406 + code: NOT_ACCEPTABLE + message: + The server can't produce a response matching the content requested + by the client through Accept-* headers + UnsupportedMediaType: + description: Unsupported Media Type + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: + The server refuses to accept the request because the payload format + is in an unsupported format. + Gone: + description: Gone + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 410 + code: GONE + message: + Access to the target resource is no longer available From be90a650cebb65eade10facbcb35073ee812b5fb Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 29 May 2024 19:31:50 +0200 Subject: [PATCH 6/7] delete_415_error_update_sink_info --- artifacts/notification-as-cloud-event.yaml | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 0618c286..e7283e84 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -99,8 +99,6 @@ paths: $ref: "#/components/responses/Generic403" 410: $ref: "#/components/responses/Generic410" - 415: - $ref: "#/components/responses/Generic415" 429: $ref: "#/components/responses/Generic429" 500: @@ -112,7 +110,7 @@ components: notificationsBearerAuth: type: http scheme: bearer - bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + bearerFormat: "{$request.body#/sinkCredential.credentialType}" schemas: ErrorInfo: type: object @@ -256,19 +254,6 @@ components: status: 410 code: GONE message: "Access to the target resource is no longer available." - Generic415: - description: Unsupported Media Type - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: "The specified media type is not supported" Generic429: description: Too Many Requests headers: From afe30cd73953a29fe800a11d26ecd7d8b4de10cf Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 29 May 2024 19:34:56 +0200 Subject: [PATCH 7/7] Trigger CI