From 0a1513012281c3e899f4eb29f9550bfa3e2a533f Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 25 Jan 2023 13:44:50 +0100 Subject: [PATCH 1/5] Align error format with Commonalities guidelines As discussed in issue [#97](https://github.com/camaraproject/QualityOnDemand/issues/97), we have to align current error model and examples to the guidelines: - Add new `status` property - Created new `Generic500` response and $ref all previous instances --- code/API_definitions/qod-api.yaml | 78 +++++++++++++++---------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml index ea3c1d69e3..da6ae6facc 100644 --- a/code/API_definitions/qod-api.yaml +++ b/code/API_definitions/qod-api.yaml @@ -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": @@ -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}: @@ -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: @@ -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: @@ -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: @@ -369,9 +349,14 @@ components: ErrorInfo: type: object required: + - status - code - message properties: + status: + type: string + pattern: "^[4-5][0-9]{2}$" + description: HTTP status code returned along with this error response code: type: string description: Code given to this error @@ -454,6 +439,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: "400" code: INVALID_INPUT message: "Schema validation failed at ..." Generic401: @@ -463,6 +449,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: "401" code: UNAUTHORIZED message: "Authorization failed: ..." Generic403: @@ -472,6 +459,7 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: "403" code: FORBIDDEN message: "Operation not allowed: ..." SessionNotFound404: @@ -481,8 +469,19 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: "404" code: NOT_FOUND message: "Session Id does not exist" + Generic500: + description: Server error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: "500" + code: INTERNAL + message: "Session could not be deleted" Generic503: description: Service unavailable content: @@ -490,5 +489,6 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" example: + status: "503" code: SERVICE_UNAVAILABLE message: "Service unavailable" From 4050c21e91b33936bd66dc3f2df07cd227bb1f42 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 25 Jan 2023 14:45:21 +0100 Subject: [PATCH 2/5] Update code/API_definitions/qod-api.yaml --- code/API_definitions/qod-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml index da6ae6facc..deb04b6054 100644 --- a/code/API_definitions/qod-api.yaml +++ b/code/API_definitions/qod-api.yaml @@ -481,7 +481,7 @@ components: example: status: "500" code: INTERNAL - message: "Session could not be deleted" + message: "Internal server error: ..." Generic503: description: Service unavailable content: From c43b46bbad7fd4ee17e9c950274372489d03c255 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Thu, 26 Jan 2023 10:56:29 +0100 Subject: [PATCH 3/5] Update qod-api.yaml Schemas for GenericXXX responses must restrict the ErrorInfo model to the allowed values at `status` and `code` for every specific response --- code/API_definitions/qod-api.yaml | 66 ++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml index deb04b6054..7d2e97fe54 100644 --- a/code/API_definitions/qod-api.yaml +++ b/code/API_definitions/qod-api.yaml @@ -437,7 +437,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + type: string + enum: ["400"] + code: + type: string + enum: ["INVALID_INPUT"] example: status: "400" code: INVALID_INPUT @@ -447,7 +456,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + type: string + enum: ["401"] + code: + type: string + enum: ["UNAUTHORIZED"] example: status: "401" code: UNAUTHORIZED @@ -457,7 +475,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + type: string + enum: ["403"] + code: + type: string + enum: ["FORBIDDEN"] example: status: "403" code: FORBIDDEN @@ -467,7 +494,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + type: string + enum: ["404"] + code: + type: string + enum: ["NOT_FOUND"] example: status: "404" code: NOT_FOUND @@ -477,7 +513,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + type: string + enum: ["500"] + code: + type: string + enum: ["INTERNAL"] example: status: "500" code: INTERNAL @@ -487,7 +532,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + type: string + enum: ["503"] + code: + type: string + enum: ["SERVICE_UNAVAILABLE"] example: status: "503" code: SERVICE_UNAVAILABLE From 68b16ecb22be1777c6932c4dbddbce4e175ba3ac Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 8 Feb 2023 13:20:41 +0100 Subject: [PATCH 4/5] Update qod-api.yaml - `status` is now an integer - `code` values aligned with Commonalities (INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED...) - Specific schemas defined for all errors, so `ErrorInfo` schema is not used. I have created a new issue in Commonalities to decide whether to reference specific model per error or the common model: . When a common approach is decided we should align this to it. --- code/API_definitions/qod-api.yaml | 276 ++++++++++++++++++------------ 1 file changed, 170 insertions(+), 106 deletions(-) diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml index 41bbef4aca..a605ace736 100644 --- a/code/API_definitions/qod-api.yaml +++ b/code/API_definitions/qod-api.yaml @@ -50,53 +50,53 @@ paths: schema: $ref: "#/components/schemas/SessionInfo" "400": - description: Invalid input + description: Invalid input for createSession operation content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: "#/components/schemas/Error400" examples: Generic400: summary: Schema validation failed value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Schema validation failed at ..." MsisdnRequired: summary: msisdn is required as part of ueId value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Expected property is missing: ueId.msisdn" IPv4Required: summary: ipv4addr is required as part of ueId value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Expected property is missing: ueId.ipv4addr" IPRequired: summary: Some IP address is required as part of ueId value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Expected property is missing: ueId.ipv4addr or ueId.ipv6addr" UePortsRequired: summary: uePorts is required value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Expected property is missing: uePorts" QoSRequired: summary: qos is required value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Expected property is missing: qos" UePortsRangesNotAllowed: summary: Ranges at uePorts are not allowed value: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Ranges not allowed: uePorts" "401": $ref: "#/components/responses/Generic401" @@ -107,9 +107,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: "#/components/schemas/Error409" example: - status: "409" + status: 409 code: CONFLICT message: "Another session is created for the same UE" "500": @@ -346,23 +346,6 @@ components: type: string enum: - SESSION_TERMINATED - ErrorInfo: - type: object - required: - - status - - code - - message - properties: - status: - type: string - pattern: "^[4-5][0-9]{2}$" - description: HTTP status code returned along with this error response - code: - type: string - description: Code given to this error - message: - type: string - description: Detailed error description UeId: type: object minProperties: 1 @@ -431,100 +414,190 @@ components: required: - severity - description + ErrorInfo: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP status code returned along with this error response + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + Error400: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 400 + code: + type: string + enum: + - INVALID_ARGUMENT + message: + type: string + Error401: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 401 + code: + type: string + enum: + - UNAUTHENTICATED + message: + type: string + Error403: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 403 + code: + type: string + enum: + - PERMISSION_DENIED + message: + type: string + Error404: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 404 + code: + type: string + enum: + - NOT_FOUND + message: + type: string + Error409: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 409 + code: + type: string + enum: + - CONFLICT + message: + type: string + Error500: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 500 + code: + type: string + enum: + - INTERNAL + message: + type: string + Error503: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + enum: + - 503 + code: + type: string + enum: + - UNAVAILABLE + message: + type: string responses: Generic400: description: Invalid input content: application/json: schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - type: string - enum: ["400"] - code: - type: string - enum: ["INVALID_INPUT"] + $ref: "#/components/schemas/Error400" example: - status: "400" - code: INVALID_INPUT + status: 400 + code: INVALID_ARGUMENT message: "Schema validation failed at ..." Generic401: description: Unauthorized content: application/json: schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - type: string - enum: ["401"] - code: - type: string - enum: ["UNAUTHORIZED"] + $ref: "#/components/schemas/Error401" example: - status: "401" - code: UNAUTHORIZED + status: 401 + code: UNAUTHENTICATED message: "Authorization failed: ..." Generic403: description: Forbidden content: application/json: schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - type: string - enum: ["403"] - code: - type: string - enum: ["FORBIDDEN"] + $ref: "#/components/schemas/Error403" example: - status: "403" - code: FORBIDDEN + status: 403 + code: PERMISSION_DENIED message: "Operation not allowed: ..." SessionNotFound404: description: Session not found content: application/json: schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - type: string - enum: ["404"] - code: - type: string - enum: ["NOT_FOUND"] + $ref: "#/components/schemas/Error404" example: - status: "404" + status: 404 code: NOT_FOUND message: "Session Id does not exist" Generic500: - description: Server error + description: Internal server error content: application/json: schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - type: string - enum: ["500"] - code: - type: string - enum: ["INTERNAL"] + $ref: "#/components/schemas/Error500" example: - status: "500" + status: 500 code: INTERNAL message: "Internal server error: ..." Generic503: @@ -532,17 +605,8 @@ components: content: application/json: schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - type: string - enum: ["503"] - code: - type: string - enum: ["SERVICE_UNAVAILABLE"] + $ref: "#/components/schemas/Error503" example: - status: "503" - code: SERVICE_UNAVAILABLE + status: 503 + code: UNAVAILABLE message: "Service unavailable" From 1e58c7f71c7cccbe548b0e2b28df69f72c995b45 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Thu, 9 Feb 2023 16:32:34 +0100 Subject: [PATCH 5/5] Update qod-api.yaml Resolving conflicts with updated main --- code/API_definitions/qod-api.yaml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml index a289ef01c2..b0b31b0136 100644 --- a/code/API_definitions/qod-api.yaml +++ b/code/API_definitions/qod-api.yaml @@ -390,18 +390,6 @@ components: enum: - QOS_STATUS_CHANGED - ErrorInfo: - type: object - required: - - code - - message - properties: - code: - type: string - description: Code given to this error - message: - type: string - description: Detailed error description UeId: type: object minProperties: 1