Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Alignement of event-subscription-template.yaml with CAMARA_common.yaml for the errors #251

Merged
merged 8 commits into from
Jul 22, 2024
Merged

Alignement of event-subscription-template.yaml with CAMARA_common.yaml for the errors #251

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e3e9da1
Update event-subscription-template.yaml
bigludo7 Jul 17, 2024
debe75b
Updates after first discussion with Pedro Diez
bigludo7 Jul 17, 2024
5b17a7b
Update artifacts/camara-cloudevents/event-subscription-template.yaml
bigludo7 Jul 18, 2024
6226bfe
Update artifacts/camara-cloudevents/event-subscription-template.yaml
bigludo7 Jul 18, 2024
63a48a0
Update artifacts/camara-cloudevents/event-subscription-template.yaml
bigludo7 Jul 18, 2024
2ec3423
Fixed event-subscription-template follwing Pedro review
bigludo7 Jul 18, 2024
56ed7a6
Update event-subscription-template.yaml
bigludo7 Jul 18, 2024
fc9b611
Update event-subscription-template.yaml for 403
bigludo7 Jul 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 134 additions & 62 deletions artifacts/camara-cloudevents/event-subscription-template.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,6 @@ paths:
application/cloudevents+json:
schema:
$ref: "#/components/schemas/CloudEvent"

responses:
"204":
description: Successful notification
Expand Down Expand Up @@ -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":
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about other errorcodes in the guideline; e.g. 405,406,501 , I think those ones would make a sense here.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not add them because they were not in the initial yaml.
Regarding 405 & 406 I'm fine to add them. @PedroDiez WDYT?
Regarding 501 with @PedroDiez we think that this API will "not work" if all operation are not implemented. Indeed, it you provide subscription you must provide POST/GET/DELETE

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer not doing now. And it is fair point of discussion.

Because there is no common guideline about to mention explicitly HTTP codes that are usually managed at API-GW Infras. We need a guideline first to agree on which HTTP codes are traversal to be explicitly mention in every API and which not (as assumed that any implementation will manage it accordingly). If not we will again have misaligment among APIs.

To me is an issue for discussion for the next MetaRelease Spring 25

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fine for me to discuss it later.

Expand Down Expand Up @@ -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"
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand Down