diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index 7269870..aff167e 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -66,7 +66,6 @@ paths: application/cloudevents+json: schema: $ref: "#/components/schemas/CloudEvent" - responses: "204": description: Successful notification @@ -115,13 +114,13 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/CreateSubscription403" + $ref: "#/components/responses/SubscriptionPermissionDenied403" "409": $ref: "#/components/responses/Generic409" "415": $ref: "#/components/responses/Generic415" "422": - $ref: "#/components/responses/CreateSubscription422" + $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422" "429": $ref: "#/components/responses/Generic429" "500": @@ -807,22 +806,29 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - InvalidArgument: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception value: status: 400 - code: "INVALID_ARGUMENT" - message: "Client specified an invalid argument, request body or query param" - InvalidProtocol: + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + GENERIC_400_INVALID_PROTOCOL: value: status: 400 code: "INVALID_PROTOCOL" message: "Only HTTP is supported" - InvalidCredential: + GENERIC_400_INVALID_CREDENTIAL: value: status: 400 code: "INVALID_CREDENTIAL" message: "Only Access token is supported" - InvalidToken: + GENERIC_400_INVALID_TOKEN: value: status: 400 code: "INVALID_TOKEN" @@ -836,10 +842,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: "INVALID_ARGUMENT" - message: "Client specified an invalid argument, request body or query param" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + 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: @@ -849,12 +858,20 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: "UNAUTHENTICATED" - message: "Request not authenticated due to missing, invalid, or expired credentials" - - CreateSubscription403: + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + Generic403: description: Client does not have sufficient permission headers: x-correlator: @@ -864,17 +881,13 @@ components: 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: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 - code: "SUBSCRIPTION_MISMATCH" - message: "Inconsistent access token for requested events subscription" - Generic403: + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + SubscriptionPermissionDenied403: description: Client does not have sufficient permission headers: x-correlator: @@ -883,10 +896,24 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: "PERMISSION_DENIED" - message: "Client does not have sufficient permissions to perform this action" + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + GENERIC_403_SUBSCRIPTION_MISMATCH: + value: + status: 403 + code: "SUBSCRIPTION_MISMATCH" + message: "Inconsistent access token for requested events subscription" Generic404: description: Resource Not Found headers: @@ -896,10 +923,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "The specified resource is not found" + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. Generic409: description: Conflict headers: @@ -909,10 +939,19 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: "The specified resource is in a conflict" + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. Generic410: description: Gone headers: @@ -922,10 +961,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 410 - code: GONE - message: "The specified resource is no longer available at the requested address" + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. Generic415: description: Unsupported Media Type headers: @@ -935,11 +977,14 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: "The specified media type is not supported" - CreateSubscription422: + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format + CreateSubscriptionUnprocessableEntity422: description: Unprocessable Entity headers: x-correlator: @@ -949,11 +994,23 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - PermissionDenied: + GENERIC_422_MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED: value: status: 422 code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" message: "Multi event types subscription not managed" + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. Generic429: description: Too Many Requests headers: @@ -963,10 +1020,19 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 429 - code: TOO_MANY_REQUESTS - message: "Endpoint does not support as many requests per time slot" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. Generic500: description: Server error headers: @@ -976,10 +1042,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: "INTERNAL" - message: "Server error" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. Generic503: description: Service unavailable. Typically the server is down. headers: @@ -989,10 +1058,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: "UNAVAILABLE" - message: "Service unavailable" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. SubscriptionIdRequired: description: Problem with the client request headers: