Closed PedroDiez closed 7 months ago
PedroDiez
commented
10 months ago Update 06/SEP:
1) Enhancement in Look&Feel of Specific Exceptions ** Pending to make analysis across WGs
2) Notifications endpoint alignment: ** Pending to have the guidelines agreed. Commonalities PRs 43 and 65
PedroDiez
commented
9 months ago 03/OCT: Notifications endpoint alignment. Commonalities PR#65 is merged. So this is ready to be applied
PedroDiez
commented
8 months ago Notifications aligment Issue: https://github.com/camaraproject/CarrierBillingCheckOut/issues/112
PedroDiez
commented
8 months ago AP: @PedroDiez Action Point to provide info to the WG. Deadline is 16th October
PedroDiez
commented
8 months ago <html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
API | Operation specific exceptions within exception code | Define exceptions within an Object (proposed for better Look&Feel) -- | -- | -- Quality On Demand | YES "400": description: Invalid input for createSession operation content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic400: summary: Some parameter combinations or parameter values provided are not schema compliant value: status: 400 code: INVALID_ARGUMENT message: "Schema validation failed at ..." DeviceMissing: summary: Device must be specified value: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: device" InsufficientDeviceProperties: summary: Device must be identified by at least one parameter value: status: 400 code: INVALID_ARGUMENT message: "Insufficient properties specified: device"... | Home Devices QoD | | YES (also as it is renderized appear in examples) 409 Requested QoS can't be set. In addition to regular CONFLICT scenario to handle conflict with the current state of the target resource, another scenarios may exist: HOME_DEVICES_QOD.TOO_MANY_DEVICES: Exceeded the maximum quantity of devices with non-default QoS behaviour. HOME_DEVICES_QOD.RSSI_BELOW_THRESHOLD: RSSI from device is below allowed threshold. HOME_DEVICES_QOD.QOS_TOO_HIGH: Requested QoS is higher than the maximum QoS allowed. HOME_DEVICES_QOD.OCCUPANCY_ABOVE_THRESHOLD: The occupancy is above the allowed threshold. HOME_DEVICES_QOD.NOT_CONNECTED_TO_REQUIRED_INTERFACE: Device is not connected to the required interface (e.g. WiFi 5GHz interface). HOME_DEVICES_QOD.NOT_SUPPORTED_REQUIRED_INTERFACE: Device does not support required interface (e.g. WiFi 5GHz interface). HOME_DEVICES_QOD.QOS_ALREADY_SET_TO_DEFAULT: Device QoS is already set to default value. That UX is due to define specific object setQosConflict409: description: \| Requested QoS can't be set. In addition to regular CONFLICT scenario to handle conflict with the current state of the target resource, another scenarios may exist: - HOME_DEVICES_QOD.TOO_MANY_DEVICES: Exceeded the maximum quantity of devices with non-default QoS behaviour. - HOME_DEVICES_QOD.RSSI_BELOW_THRESHOLD: RSSI from device is below allowed threshold. - HOME_DEVICES_QOD.QOS_TOO_HIGH: Requested QoS is higher than the maximum QoS allowed. - HOME_DEVICES_QOD.OCCUPANCY_ABOVE_THRESHOLD: The occupancy is above the allowed threshold. - HOME_DEVICES_QOD.NOT_CONNECTED_TO_REQUIRED_INTERFACE: Device is not connected to the required interface (e.g. WiFi 5GHz interface). - HOME_DEVICES_QOD.NOT_SUPPORTED_REQUIRED_INTERFACE: Device does not support required interface (e.g. WiFi 5GHz interface). - HOME_DEVICES_QOD.QOS_ALREADY_SET_TO_DEFAULT: Device QoS is already set to default value. headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Conflict: value: status: 409 code: CONFLICT message: Conflict with the current state of the target resource TooManyDevices: value: status: 409 code: HOME_DEVICES_QOD.TOO_MANY_DEVICES message: Exceeded the maximum quantity of devices with non-default QoS behaviour RssiBelowThreshold: value: status: 409 code: HOME_DEVICES_QOD.RSSI_BELOW_THRESHOLD message: RSSI from device is below allowed threshold QosTooHigh: value: status: 409 code: HOME_DEVICES_QOD.QOS_TOO_HIGH message: Requested QoS is higher than the maximum QoS allowed OccupancyAboveThreshold: value: status: 409 code: HOME_DEVICES_QOD.OCCUPANCY_ABOVE_THRESHOLD message: The occupancy is above the allowed threshold NotConnectedToRequiredInterface: value: status: 409 code: HOME_DEVICES_QOD.NOT_CONNECTED_TO_REQUIRED_INTERFACE message: Device is not connected to the required interface (e.g. WiFi 5GHz interface) NotSupportedRequiredInterface: value: status: 409 code: HOME_DEVICES_QOD.NOT_SUPPORTED_REQUIRED_INTERFACE message: Device does not support required interface (e.g. WiFi 5GHz interface) QosAlreadySetToDefault: value: status: 409 code: HOME_DEVICES_QOD.QOS_ALREADY_SET_TO_DEFAULT message: Device QoS is already set to default value Device Status | N/A (No specific error yet) | N/A (No specific error yet) Device Location | Location Verification - N/A (No specific error yet) | Location Verification - N/A (No specific error yet) Location Retrieval - YES RetrieveLocationBadRequest400: description: \|- Problem with the client request. In addition to regular scenario of `INVALID_ARGUMENT`, another scenarios may exist: - maxAge threshold cannot be satisfied content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: InvalidArgument: value: status: 400 code: INVALID_ARGUMENT message: 'Invalid input' MaxAgeIssue: value: status: 400 code: LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT message: 'maxAge threshold cannot be satisfied' SIM SWAP | N/A (No specific error yet) | N/A (No specific error yet) Number Verification | | YES PhoneNumberVerificationPermissionDenied403: description: \| Client does not have sufficient permission. In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: - Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`) - Phone number cannot be deducted from access token context.(`{"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) headers: X-Correlator: description: Correlation id for the different services schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: PermissionDenied: value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action UserNotAuthenticatedByMobileNetwork: value: status: 403 code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK message: Client must authenticate via the mobile network to use this service InvalidTokenContext: value: status: 403 code: NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT message: Phone number cannot be deducted from access token context One Time Password | | YES ValidateCodeBadRequestError400: description: \|- Problem with the client request. In addition to regular scenario of `INVALID_ARGUMENT`, another scenarios may exist: - Too many unsuccessful attempts (`{"code": "ONE_TIME_PASSWORD_SMS.VERIFICATION_FAILED","message": "The maximum number of attempts for this authenticationId was exceeded without providing a valid OTP"}`) - Expired authenticationId (`{"code": "ONE_TIME_PASSWORD_SMS.VERIFICATION_EXPIRED","message": "The authenticationId is no longer valid"}`) - OTP is not valid for the provided authenticationId (`{"code": "ONE_TIME_PASSWORD_SMS.INVALID_OTP","message": "The provided OTP is not valid for this authenticationId"}`) Blockchain Public Address | | YES InvalidCurrencyForBlockchain400: description: \| Problem with the client request. In addition to regular scenario of INVALID_ARGUMENT, other exceptions may exist. - Indicated Currency is not valid for the Blockchain ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY","message": "Indicated currency is not found") - Currency indication is required ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.CURRENCY_REQUIRED","message": "One currency is required") Edge Cloud | N/A (No specific error yet) | N/A (No specific error yet)
Problem description
Several topics to be addressed. To be reviewed on next meeting. Target version: Include within v0.2 or v0.3 (based on we agree to include within v0.2 or next one)
- Enhancement in Look&Feel of Specific Exceptions:
Example, instead of defining operation specific exceptions within exception code. Just define an object for them
` PaymentPermissionDenied403: description: | Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist:
content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic403: summary: Forbidden value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." PhoneNumberRequired: summary: Phone Number not provided and cannot be obtained from Authorization context value: status: 403 code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED message: "Phone Number is required" PhoneNumberMismatch: summary: Phone Number provided not matching Authorization context value: status: 403 code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT message: "Phone Number does not match with Authorization context" UnauthorizedAmount: summary: Unauthorized amount requested value: status: 403 code: CARRIER_BILLING.UNAUTHORIZED_AMOUNT message: "Unauthorized amount requested" UserMobileAccumulatedThresholdAmountOverpassed: summary: Accumulated threshold amount for the user's mobile account overpassed value: status: 403 code: CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED message: "Unathorized payment request. Accumulated user mobile payments over`
Then look and feel is better for API devs:
- Notifications endpoint alignment: