diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 748176b..f4df86f 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -126,10 +126,10 @@ info: may be used. If an end-user replaces the equipment, all existing isolated networks SHOULD be synced to the new device representing this mesh. Alternatively, a synthetic hardware address may also be used if the specification for the address type allows. - version: wip license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip x-camara-commonalities: 0.4.0 contact: email: sp-nam@lists.camaraproject.org @@ -254,7 +254,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/ServiceSiteNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -318,7 +318,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/ServiceSiteNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -375,7 +375,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/ServiceSiteNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -508,7 +508,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/DeviceNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -562,7 +562,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/DeviceNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -607,13 +607,13 @@ paths: "204": description: Successfully inserted, removed, or replaced the configuration for many networks on the device "400": - $ref: "#/components/responses/NetworkNotRemovable400" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/DeviceOrNetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -672,11 +672,9 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -741,11 +739,9 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -805,13 +801,11 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -870,13 +864,11 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -913,17 +905,15 @@ paths: "204": description: Successfully deleted the network "400": - $ref: "#/components/responses/NetworkNotRemovable400" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -984,7 +974,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -1026,13 +1016,13 @@ paths: "204": description: Successfully inserted, removed, or replaced the network from the configuration of many devices "400": - $ref: "#/components/responses/NetworkNotRemovable400" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/DeviceOrNetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -1084,7 +1074,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" "501": @@ -1148,7 +1138,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" "501": @@ -1204,9 +1194,9 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -1265,9 +1255,9 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -1306,9 +1296,9 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -1317,12 +1307,25 @@ paths: $ref: "#/components/responses/Generic503" components: + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + securitySchemes: openId: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + siteId: name: siteId in: path @@ -1365,6 +1368,23 @@ components: 2023-07-03T12:27:08.312Z) example: &date-time "2023-07-03T14:27:08.312+02:00" + ErrorInfo: + type: object + required: + - message + - status + - code + properties: + message: + type: string + description: A human readable description of what the event represent + status: + type: integer + description: HTTP response status code + code: + type: string + description: Friendly Code to describe the error + ServiceSiteId: type: string minLength: 1 @@ -2292,23 +2312,6 @@ components: modifiedAt: *date-time modifiedBy: &reboot-modified-by2 "user-4" - ErrorInfo: - type: object - 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 - required: - - status - - code - - message - examples: BaseServiceSite: summary: Base Service Site @@ -2906,149 +2909,365 @@ components: responses: Generic400: - description: Invalid input - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: &generic-400-example - status: 400 - code: INVALID_ARGUMENT - message: "Schema validation failed: ..." - - NetworkNotRemovable400: - description: Network not removable + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: - NetworkNotRemovable: - summary: Network Not Removable Error - description: | - Output when attempting to delete or remove a network that can only be replaced. + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception value: status: 400 - code: NETWORK_NOT_REMOVABLE - message: "Network not removable: ..." - Generic: - summary: Invalid Argument - value: *generic-400-example + 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. Generic401: description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: "Authorization failed: ..." + 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: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: &generic-403-example - status: 403 - code: PERMISSION_DENIED - message: "Operation not allowed: ..." - - DefaultDeviceNotSupported403: - description: Default device not supported + 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: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: - DefaultDeviceNotSupported: - summary: Default Device Not Supported Error - description: | - Output with scopes for a default device but for an unsupported resource owner. + GENERIC_404_NOT_FOUND: + description: Resource is not found value: - status: 403 - code: DEFAULT_DEVICE_NOT_SUPPORTED - message: "Default device not supported: ..." - Generic: - summary: Forbidden - value: *generic-403-example - - ServiceSiteNotFound404: - description: Service site(s) not found + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + GENERIC_404_SERVICE_SITE_NOT_FOUND: + description: Service site identitier not found + value: + status: 404 + code: SERVICE_SITE_NOT_FOUND + message: | + Service site identifier(s) not found: {{ServiceSiteId}}. + GENERIC_404_DEVICE_NOT_FOUND: + description: Device identifier(s) not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: | + Device identifier(s) not found: {{DeviceId}}. + GENERIC_404_NETWORK_NOT_FOUND: + description: Network identitier(s) not found + value: + status: 404 + code: NETWORK_NOT_FOUND + message: | + Network identitifer(s) not found: {{NetworkId}}. + + Generic405: + description: Method Not Allowed + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "Service site ID(s) do not exist: [...]" - - DeviceNotFound404: - description: Device(s) not found + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "Device ID(s) do not exist: [...]" - - NetworkNotFound404: - description: Network(s) not found + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + + Generic409: + description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "Network ID(s) do not exist: [...]" - - DeviceOrNetworkNotFound404: - description: Device(s) and/or network(s) not found + 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. + GENERIC_409_CONFLICT: + description: Duplication of an existing resource + value: + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. + GENERIC_409_NETWORK_NOT_REMOVABLE: + description: The specified network cannot be removed + value: + status: 409 + code: NETWORK_NOT_REMOVABLE + message: | + The specified network cannot be removed: {{NetworkId}}: {{reason}} + + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "Device ID(s) do not exist: [...]; Network ID(s) do not exist: [...]" + 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. + + Generic412: + description: Failed precondition + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_412_FAILED_PRECONDITION: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 412 + code: FAILED_PRECONDITION + message: Request cannot be executed in the current system state. + + Generic415: + description: Unsupported Media Type + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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: + description: Unprocessable Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + 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. + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: The device cannot be identified. + + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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: Internal server error + description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL_SERVER_ERROR - message: "Internal 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. Generic501: description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 501 - code: NOT_IMPLEMENTED - message: "Service not implemented for the specified endpoint" + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + + Generic502: + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. Generic503: - description: Service unavailable + description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: SERVICE_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. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded.