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

Align error format with Commonalities guidelines #104

Merged
merged 7 commits into from
Feb 10, 2023
Merged

Align error format with Commonalities guidelines #104

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0a15130
Align error format with Commonalities guidelines
jlurien Jan 25, 2023
4050c21
Update code/API_definitions/qod-api.yaml
jlurien Jan 25, 2023
c43b46b
Update qod-api.yaml
jlurien Jan 26, 2023
c27657b
Merge branch 'main' into chore/errors-alignment-with-guidelines
jlurien Feb 2, 2023
68b16ec
Update qod-api.yaml
jlurien Feb 8, 2023
c4416ba
Merge branch 'main' into chore/errors-alignment-with-guidelines
jlurien Feb 9, 2023
1e58c7f
Update qod-api.yaml
jlurien Feb 9, 2023
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
78 changes: 39 additions & 39 deletions code/API_definitions/qod-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,37 +58,44 @@ paths:
examples:
Generic400:
summary: Schema validation failed
value:
value:
status: "400"
code: INVALID_INPUT
message: "Schema validation failed at ..."
MsisdnRequired:
summary: msisdn is required as part of ueId
value:
value:
status: "400"
code: INVALID_INPUT
message: "Expected property is missing: ueId.msisdn"
IPv4Required:
summary: ipv4addr is required as part of ueId
value:
value:
status: "400"
code: INVALID_INPUT
message: "Expected property is missing: ueId.ipv4addr"
IPRequired:
summary: Some IP address is required as part of ueId
value:
value:
status: "400"
code: INVALID_INPUT
message: "Expected property is missing: ueId.ipv4addr or ueId.ipv6addr"
UePortsRequired:
summary: uePorts is required
value:
value:
status: "400"
code: INVALID_INPUT
message: "Expected property is missing: uePorts"
QoSRequired:
summary: qos is required
value:
value:
status: "400"
code: INVALID_INPUT
message: "Expected property is missing: qos"
UePortsRangesNotAllowed:
summary: Ranges at uePorts are not allowed
value:
value:
status: "400"
code: INVALID_INPUT
message: "Ranges not allowed: uePorts"
"401":
Expand All @@ -102,17 +109,11 @@ paths:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "409"
code: CONFLICT
message: "Another session is created for the same UE"
"500":
description: Server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
code: INTERNAL
message: "Session could not be created"
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
/sessions/{sessionId}:
Expand Down Expand Up @@ -142,14 +143,7 @@ paths:
"404":
$ref: "#/components/responses/SessionNotFound404"
"500":
description: Server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
code: INTERNAL
message: "Could not get session information"
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
delete:
Expand All @@ -174,14 +168,7 @@ paths:
"404":
$ref: "#/components/responses/SessionNotFound404"
"500":
description: Server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
code: INTERNAL
message: "Session could not be deleted"
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
/notifications:
Expand Down Expand Up @@ -210,14 +197,7 @@ paths:
"403":
$ref: "#/components/responses/Generic403"
"500":
description: Server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
code: INTERNAL
message: "Failed to handle notification"
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
security:
Expand Down Expand Up @@ -369,9 +349,14 @@ components:
ErrorInfo:
type: object
required:
- status
- code
- message
properties:
status:
type: string
pattern: "^[4-5][0-9]{2}$"
hdamker marked this conversation as resolved.
Show resolved Hide resolved
description: HTTP status code returned along with this error response
code:
type: string
description: Code given to this error
Expand Down Expand Up @@ -454,6 +439,7 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "400"
code: INVALID_INPUT
message: "Schema validation failed at ..."
Generic401:
Expand All @@ -463,6 +449,7 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "401"
code: UNAUTHORIZED
message: "Authorization failed: ..."
Generic403:
Expand All @@ -472,6 +459,7 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "403"
code: FORBIDDEN
message: "Operation not allowed: ..."
SessionNotFound404:
Copy link
Collaborator

Choose a reason for hiding this comment

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

Why not Generic404 as Generic403, Generic401 ?
All these errors are specialization of ErrorInfo ... usage is to define a type or @type field as discriminator in ErrorInfo to help deserializer to manage subtype deserialization.

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 could have named it Generic404 as well, but as the only case in this API for 404 was Session Not Found, I chose a more specific name and added an explicit message in the example. Problem with Generic responses is that example has to be generic as well. For automatic API publishing in a web portal it is convenient to embed good examples in the spec, but for client generation purposes it may complicate things.

I can change the name to Generic404 if that is more coherent with the rest of responses

Expand All @@ -481,14 +469,26 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "404"
code: NOT_FOUND
message: "Session Id does not exist"
Generic500:
description: Server error
Copy link
Collaborator

Choose a reason for hiding this comment

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

A better naming would be "Internal Server Error" for the description of a 500 - Internal Server Error.

content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "500"
code: INTERNAL
message: "Session could not be deleted"
hdamker marked this conversation as resolved.
Show resolved Hide resolved
jlurien marked this conversation as resolved.
Show resolved Hide resolved
Generic503:
description: Service unavailable
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: "503"
code: SERVICE_UNAVAILABLE
message: "Service unavailable"