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 6 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
187 changes: 130 additions & 57 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 @@ -115,13 +115,13 @@ paths:
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/CreateSubscription403"
$ref: "#/components/responses/CreateSubscriptionPermissionDenied403"
"409":
$ref: "#/components/responses/Generic409"
"415":
$ref: "#/components/responses/Generic415"
"422":
$ref: "#/components/responses/CreateSubscription422"
$ref: "#/components/responses/Generic422"
"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 +807,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 +843,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 +859,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 +882,18 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
PermissionDenied:
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"
TokenMismatch:
code: PERMISSION_DENIED
message: Client does not have sufficient permissions to perform this action.
GENERIC_403_SUBSCRIPTION_MISMATCH:
Copy link

Choose a reason for hiding this comment

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

I think SUBSCRIPTION_MISMATCH doesn't belong to Generic403, it's subscription specific
Can't we have only 1 403 type like SubscriptionPermissionDenied with 3 examples (permissiondenied, invalidtoken, subscription mismatch), and remove Generic403?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@akoshunyadi I used CreateSubscriptionPermissionDenied403 only for the POST /subscriptions and I have 403_INVALID_TOKEN_CONTEXT specific for the POST
Generic403 is for the GET & DELETE and here we have the GENERIC_403_SUBSCRIPTION_MISMATCH which applies only for GET & DELETE and not POST

Copy link

Choose a reason for hiding this comment

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

For me GenericXXX are types which we could put into/take from the common yaml and use for all APIs, because they don't contain any API specific hints. So I think we can have multiple 403 types here but if *Generic then it should only have generic examples.

Copy link
Contributor

Choose a reason for hiding this comment

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

@bigludo7 I think GENERIC_403_SUBSCRIPTION_MISMATCH is to be used within CreateSubscriptionPermissionDenied403 (Line 896) and within "Generic 403" (Line 875) also applies GENERIC_403_INVALID_TOKEN_CONTEXT

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

humm...hope i was able to follow you
I've defined SubscriptionPermissionDenied403 for all subscription related 403 for the operations and I kept Generic403 as response possible for the callback.

value:
status: 403
code: "SUBSCRIPTION_MISMATCH"
message: "Inconsistent access token for requested events subscription"
Generic403:
CreateSubscriptionPermissionDenied403:
description: Client does not have sufficient permission
headers:
x-correlator:
Expand All @@ -883,10 +902,19 @@ 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."
Generic404:
description: Resource Not Found
headers:
Expand All @@ -896,10 +924,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 +940,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 +962,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 +978,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
Generic422:
Copy link

Choose a reason for hiding this comment

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

I think it should be named specifically, since it contains subscription specific examples

Copy link
Collaborator Author

@bigludo7 bigludo7 Jul 18, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

hummm so I not get it because when I read in the CAMARA_common.yam that we can have in Generic422:

            GENERIC_422_{{SPECIFIC_CODE}}:
              description: Any semantic condition associated to business logic, specifically related to a field or data structure
              value:
                status: 422
                code: { { SPECIFIC_CODE } }
                message: { { SPECIFIC_CODE_MESSAGE } }

(lines 373) I was thinking this is a placeholder for specific code.
What is your understanding @akoshunyadi ?

Copy link

Choose a reason for hiding this comment

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

yes, but I still have the problem that we will have many e.g. Generic422 over all Camara APIs but there are not the same.

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've changed to CreateSubscriptionUnprocessableEntity422 ;)
Hope that fine for @PedroDiez

description: Unprocessable Entity
headers:
x-correlator:
Expand All @@ -949,11 +995,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 +1021,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 +1043,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 +1059,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