From baa0cedccd616fe57adce5f4ec2440420c5fcba0 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Thu, 17 Oct 2024 20:14:01 -0600 Subject: [PATCH 1/7] chore: in-progress work that copies in templates --- .../network_access_management.yaml | 578 ++++++++++++++---- 1 file changed, 475 insertions(+), 103 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 748176b..dc06606 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 @@ -1317,12 +1317,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 @@ -1356,6 +1369,112 @@ components: description: ID of the reboot request to find schemas: + TimePeriod: + properties: + startDate: + type: string + format: date-time + description: An instant of time, starting of the TimePeriod. + endDate: + type: string + format: date-time + description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. + required: + - startDate + + 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 + + TODODevice: + description: | + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + The developer can choose to provide the below specified device identifiers: + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device. + NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 + + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@domain.com" + + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + publicAddress: "84.125.93.10" + publicPort: 59765 + + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" + + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + DateTime: type: string format: date-time @@ -2292,23 +2411,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 @@ -2905,150 +3007,420 @@ components: value: *reboot-request-list responses: + # NetworkNotRemovable400: + # description: Network not removable + # 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. + # value: + # status: 400 + # code: NETWORK_NOT_REMOVABLE + # message: "Network not removable: ..." + # Generic: + # summary: Invalid Argument + # value: *generic-400-example 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: 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: NETWORK_NOT_REMOVABLE - message: "Network not removable: ..." - Generic: - summary: Invalid Argument - value: *generic-400-example + code: OUT_OF_RANGE + message: Client specified an invalid range. + GENERIC_400_{{SPECIFIC_CODE}}: + description: Specific Syntax Exception regarding a field that is relevant in the context of the API + value: + status: 400 + code: { { SPECIFIC_CODE } } + message: { { SPECIFIC_CODE_MESSAGE } } 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. + + # DefaultDeviceNotSupported403: + # description: Default device not supported + # 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. + # value: + # status: 403 + # code: DEFAULT_DEVICE_NOT_SUPPORTED + # message: "Default device not supported: ..." + # Generic: + # summary: Forbidden + # value: *generic-403-example 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." + GENERIC_403_{{SPECIFIC_CODE}}: + description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API + value: + status: 403 + code: { { SPECIFIC_CODE } } + message: { { SPECIFIC_CODE_MESSAGE } } + + 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_{{SPECIFIC_CODE}}: + description: Specific conflict situation that is relevant in the context of the API + value: + status: 409 + code: { { SPECIFIC_CODE } } + message: { { SPECIFIC_CODE_MESSAGE } } + + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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. + 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 } } + + Generic429: + description: Too Many Requests + 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_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. From f8b2128e1e2bd788aeb86d36af086222aed601d9 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Thu, 31 Oct 2024 19:07:54 -0600 Subject: [PATCH 2/7] fix: error indentation --- .../network_access_management.yaml | 70 +++---------------- 1 file changed, 8 insertions(+), 62 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index dc06606..7956c73 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -3007,24 +3007,6 @@ components: value: *reboot-request-list responses: - # NetworkNotRemovable400: - # description: Network not removable - # 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. - # value: - # status: 400 - # code: NETWORK_NOT_REMOVABLE - # message: "Network not removable: ..." - # Generic: - # summary: Invalid Argument - # value: *generic-400-example Generic400: description: Bad Request headers: @@ -3047,12 +3029,6 @@ components: status: 400 code: OUT_OF_RANGE message: Client specified an invalid range. - GENERIC_400_{{SPECIFIC_CODE}}: - description: Specific Syntax Exception regarding a field that is relevant in the context of the API - value: - status: 400 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } Generic401: description: Unauthorized @@ -3077,24 +3053,6 @@ components: code: AUTHENTICATION_REQUIRED message: New authentication is required. - # DefaultDeviceNotSupported403: - # description: Default device not supported - # 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. - # value: - # status: 403 - # code: DEFAULT_DEVICE_NOT_SUPPORTED - # message: "Default device not supported: ..." - # Generic: - # summary: Forbidden - # value: *generic-403-example Generic403: description: Forbidden headers: @@ -3117,12 +3075,6 @@ components: status: 403 code: INVALID_TOKEN_CONTEXT message: "{{field}} is not consistent with access token." - GENERIC_403_{{SPECIFIC_CODE}}: - description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API - value: - status: 403 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } Generic404: description: Not found @@ -3146,21 +3098,21 @@ components: status: 404 code: SERVICE_SITE_NOT_FOUND message: | - Service site identifier(s) not found: { { ServiceSiteId } }. + 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 } }. + 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 } }. + Network identitifer(s) not found: {{NetworkId}}. Generic405: description: Method Not Allowed @@ -3224,12 +3176,13 @@ components: status: 409 code: CONFLICT message: A specified resource duplicate entry found. - GENERIC_409_{{SPECIFIC_CODE}}: - description: Specific conflict situation that is relevant in the context of the API + GENERIC_409_NETWORK_NOT_REMOVABLE: + description: The specified network cannot be removed value: status: 409 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: NETWORK_NOT_REMOVABLE + message: | + The specified network cannot be removed: {{NetworkId}}: {{reason}} Generic410: description: Gone @@ -3310,12 +3263,6 @@ components: status: 422 code: UNIDENTIFIABLE_DEVICE message: The device cannot be identified. - 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 } } Generic429: description: Too Many Requests @@ -3407,7 +3354,6 @@ components: status: 503 code: UNAVAILABLE message: Service Unavailable. - Generic504: description: Gateway Timeout headers: From 6b15206578744fb9649ac1b48cf30035a69c09b9 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Thu, 31 Oct 2024 19:23:19 -0600 Subject: [PATCH 3/7] fix: update refs --- .../network_access_management.yaml | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 7956c73..ec04ff6 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -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,7 +672,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" "501": @@ -741,7 +741,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" "501": @@ -805,9 +805,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": @@ -870,9 +870,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": @@ -913,13 +913,13 @@ 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": @@ -984,7 +984,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/NetworkNotFound404" + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "501": @@ -1026,13 +1026,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 +1084,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" "501": @@ -1148,7 +1148,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/DefaultDeviceNotSupported403" + $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" "501": @@ -1204,9 +1204,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 +1265,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 +1306,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": From b21c691e7f7a3fc0d8a46bafb3a5a29459283007 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Mon, 4 Nov 2024 15:39:19 -0700 Subject: [PATCH 4/7] fix: remove models not currently in use --- .../network_access_management.yaml | 98 ------------------- 1 file changed, 98 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index ec04ff6..a1d064c 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1369,19 +1369,6 @@ components: description: ID of the reboot request to find schemas: - TimePeriod: - properties: - startDate: - type: string - format: date-time - description: An instant of time, starting of the TimePeriod. - endDate: - type: string - format: date-time - description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. - required: - - startDate - ErrorInfo: type: object required: @@ -1399,91 +1386,6 @@ components: type: string description: Friendly Code to describe the error - TODODevice: - description: | - End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. - The developer can choose to provide the below specified device identifiers: - * `ipv4Address` - * `ipv6Address` - * `phoneNumber` - * `networkAccessIdentifier` - NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device. - NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. - type: object - properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/DeviceIpv4Addr" - ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" - minProperties: 1 - - PhoneNumber: - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" - - NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. - type: string - example: "123456789@domain.com" - - DeviceIpv4Addr: - type: object - description: | - The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). - - If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. - - If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) - - In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. - properties: - publicAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - privateAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - publicPort: - $ref: "#/components/schemas/Port" - anyOf: - - required: [publicAddress, privateAddress] - - required: [publicAddress, publicPort] - example: - publicAddress: "84.125.93.10" - publicPort: 59765 - - SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" - - Port: - description: TCP or UDP port number - type: integer - minimum: 0 - maximum: 65535 - - DeviceIpv6Address: - description: | - The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). - type: string - format: ipv6 - example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - - DateTime: - type: string - format: date-time - description: | - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or - 2023-07-03T12:27:08.312Z) - example: &date-time "2023-07-03T14:27:08.312+02:00" - ServiceSiteId: type: string minLength: 1 From d75ab54f3bc25106357350ec60731fe1c96c8e2b Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Mon, 4 Nov 2024 15:40:29 -0700 Subject: [PATCH 5/7] fix: restore date/time --- code/API_definitions/network_access_management.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index a1d064c..97af6b6 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1386,6 +1386,15 @@ components: type: string description: Friendly Code to describe the error + DateTime: + type: string + format: date-time + description: | + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or + 2023-07-03T12:27:08.312Z) + example: &date-time "2023-07-03T14:27:08.312+02:00" + ServiceSiteId: type: string minLength: 1 From 7e169f20834d0ecdcc65ae37d1590db592969aef Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Mon, 4 Nov 2024 15:43:40 -0700 Subject: [PATCH 6/7] style: restore original positioning of models --- .../network_access_management.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 97af6b6..ed96060 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1369,6 +1369,15 @@ components: description: ID of the reboot request to find schemas: + DateTime: + type: string + format: date-time + description: | + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or + 2023-07-03T12:27:08.312Z) + example: &date-time "2023-07-03T14:27:08.312+02:00" + ErrorInfo: type: object required: @@ -1386,15 +1395,6 @@ components: type: string description: Friendly Code to describe the error - DateTime: - type: string - format: date-time - description: | - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or - 2023-07-03T12:27:08.312Z) - example: &date-time "2023-07-03T14:27:08.312+02:00" - ServiceSiteId: type: string minLength: 1 From 93561ed3c7e876f6c806c489c5749d1036e2dab2 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Thu, 14 Nov 2024 01:23:06 -0700 Subject: [PATCH 7/7] fix: remove 501 from bare bones required endpoints --- code/API_definitions/network_access_management.yaml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index ed96060..f4df86f 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -675,8 +675,6 @@ paths: $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -744,8 +742,6 @@ paths: $ref: "#/components/responses/Generic403" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -810,8 +806,6 @@ paths: $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -875,8 +869,6 @@ paths: $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" @@ -922,8 +914,6 @@ paths: $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503"