From 341cfae1d2d612b2722d8dc8b01834f69527181d Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Fri, 7 Jun 2024 14:37:24 -0400 Subject: [PATCH 01/10] Create connected-network-type.yaml --- .../connected-network-type.yaml | 416 ++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 code/API_definitions/connected-network-type.yaml diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml new file mode 100644 index 00000000..5efef027 --- /dev/null +++ b/code/API_definitions/connected-network-type.yaml @@ -0,0 +1,416 @@ +openapi: 3.0.3 +info: + title: Connected Network Type + description: | + This API provides the customer with the ability to query to which Mobile Communication Technology it is connected to. + + # Introduction + + ## Connected Network Type + + API consumer is able to inquire device's connected network type. + + # Relevant terms and definitions + + * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. + + * **Network Type** : Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. + - `2G`, if device is connected to the 2G network + - `3G`, if device is connected to the 3G network + - `4GLTE`, if device is connected to the 4G network + - `5GNSA`, if device's is connected to the 4G network but using 5G New Radio (NR) capability + - `5GSA`, if device is connected to the 5G network + - `NON3GPP4G`, if device is connected to the 4G network via WiFi network + - `NON3GPP5G`, if device's is connected to the 5G network via WiFi network + + + * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain. + + # API Functionality + + The API exposes following capabilities: + + ## Connected Network Type + + The endpoint `POST /retrieve-network-type` allows to get connected Network Type. + + + ## Further info and support + + (FAQs will be added in a later version of the documentation) + + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/ + +servers: + - url: "{apiRoot}/network-type-retrieval/v0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root +tags: + - name: Connected Network Type + description: Operations to get the network type device is connected to +paths: + /retrieve-network-type: + post: + tags: + - Connected network type + summary: "Get the connected network type" + description: Get the connected network type + operationId: getConnectedNetworkType + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - connected-network-type:read + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RequestConnectedNetworkType" + required: true + responses: + "200": + description: Contains connected network type + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectedNetworkTypeResponse" + examples: + Connected-to-4G: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + connectedNetworkType: 4G + Connected-To-5GNSA: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + connectedNetworkType: 5GNSA + Connected-To-Non3gpp4g: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + connectedNetworkType: NON3GPP4G + Not-Connected: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + connectedNetworkType: NOT_CONNECTED + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/ConnectedNetworkTypePermissionDenied403" + "404": + $ref: "#/components/responses/ConnectedStatusNotFound404" + "422": + $ref: "#/components/responses/ConnectedStatusUnprocessableEntity422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" +components: + 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 + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + schemas: + LastStatusTime: + description: Last time that the associated connected Network Type was updated + type: string + format: date-time + example: "2024-02-20T10:41:38.657Z" + + ConnectedNetworkTypeResponse: + type: object + required: + - connectedNetworkType + properties: + lastStatusTime: + $ref: "#/components/schemas/LastStatusTime" + connectedNetworkType: + $ref: "#/components/schemas/ConnectedNetworkType" + + ConnectedNetworkType: + description: | + * NOT_CONNECTED: The device is not connected to network + * 2G: 2nd Generation Mobile Communication Technology + * 3G: 3rd Generation Mobile Communication Technology + * 4GLTE: 4th Generation Mobile Communication Technology aka LTE + * 5GNSA:4th Generation Mobile Communication Technology aka LTE with device connected 5G New Radio (NR) + * 5GSA: 5th Generation Mobile Communication Technology + * NON3GPP4G: Device connected via non-3GPP Radio Access Technology but connected to 4G Network (e.g. WiFi Calling) + * NON3GPP5G: Device connected via non-3GPP Radio Access Technology but connected to 5G Network (e.g. WiFi Calling) + type: string + enum: + - 2G + - 3G + - 4GLTE + - 5GNSA + - 5GSA + - NON3GPP4G + - NON3GPP5G + - NOT-CONNECTED + + Device: + 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` + + NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + 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 + + RequestConnectedNetworkType: + type: object + properties: + device: + $ref: "#/components/schemas/Device" + required: + - device + + ErrorInfo: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + + responses: + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 400 + code: "INVALID_ARGUMENT" + message: "Client specified an invalid argument, request body or query param" + Generic401: + description: Authentication problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: "UNAUTHENTICATED" + message: "Request not authenticated due to missing, invalid, or expired credentials" + ConnectedNetworkTypePermissionDenied403: + description: | + Client does not have sufficient permission. + In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: + - 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" + InvalidTokenContext: + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: Invalid access token context + ConnectedStatusNotFound404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + NotFound: + value: + status: 404 + code: NOT_FOUND + message: "The specified resource is not found" + DeviceIdentifierNotFound: + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Some identifier cannot be matched to a device + Generic409: + description: Conflict + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: CONFLICT + message: "The specified resource is in a conflict" + ConnectedStatusUnprocessableEntity422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + UnsupportedDeviceIdentifiers: + value: + status: 422 + code: UNSUPPORTED_DEVICE_IDENTIFIERS + message: "None of the provided device identifiers is supported by the implementation" + InconsistentDeviceIdentifiers: + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Device identifiers mismatch + DeviceNotSupported: + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: Service not applicable to the device + Generic500: + description: Server error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 500 + code: "INTERNAL" + message: "Server error" + Generic503: + description: Service unavailable. Typically the server is down. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: "UNAVAILABLE" + message: "Service unavailable" From 3c980bbd0631b9ea55a64a30b91d26e7e1188b0a Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Wed, 12 Jun 2024 19:35:59 -0400 Subject: [PATCH 02/10] Update connected-network-type.yaml --- code/API_definitions/connected-network-type.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 5efef027..5be015b5 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -90,10 +90,10 @@ paths: schema: $ref: "#/components/schemas/ConnectedNetworkTypeResponse" examples: - Connected-to-4G: + Connected-to-4GLTE: value: lastStatusTime: "2024-02-20T10:41:38.657Z" - connectedNetworkType: 4G + connectedNetworkType: 4GLTE Connected-To-5GNSA: value: lastStatusTime: "2024-02-20T10:41:38.657Z" From f7b1c142c774dbbfe2ac31d96a75be0fc482e86c Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Wed, 12 Jun 2024 19:37:32 -0400 Subject: [PATCH 03/10] Update connected-network-type.yaml --- code/API_definitions/connected-network-type.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 5be015b5..96f6e6de 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -173,8 +173,8 @@ components: - 5GSA - NON3GPP4G - NON3GPP5G - - NOT-CONNECTED - + - NOT_CONNECTED + Device: description: | End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. From a0e8804ef44db3a2a81b36d857548b229fa5b694 Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Mon, 18 Nov 2024 14:42:15 -0500 Subject: [PATCH 04/10] Update connected-network-type.yaml Updates: - Use of UNKNOWN for undetermined connection [technology] - Simplified list of connection technologies - Updates to Examples and API documentation in line with above points --- .../connected-network-type.yaml | 47 +++++++------------ 1 file changed, 18 insertions(+), 29 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 96f6e6de..36cf4961 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -16,13 +16,11 @@ info: At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. * **Network Type** : Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. - - `2G`, if device is connected to the 2G network - - `3G`, if device is connected to the 3G network - - `4GLTE`, if device is connected to the 4G network - - `5GNSA`, if device's is connected to the 4G network but using 5G New Radio (NR) capability - - `5GSA`, if device is connected to the 5G network - - `NON3GPP4G`, if device is connected to the 4G network via WiFi network - - `NON3GPP5G`, if device's is connected to the 5G network via WiFi network + - `2G`, if device is connected to the 2G network technology + - `3G`, if device is connected to the 3G network technology + - `4G`, if device is connected to the 4G network technology + - `5G`, if device is connected to the 5G network technology + - `UNKNOWN` if connection [technology] can not be determined * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain. @@ -90,22 +88,18 @@ paths: schema: $ref: "#/components/schemas/ConnectedNetworkTypeResponse" examples: - Connected-to-4GLTE: + Connected-to-4G: value: lastStatusTime: "2024-02-20T10:41:38.657Z" - connectedNetworkType: 4GLTE - Connected-To-5GNSA: + connectedNetworkType: 4G + Connected-to-5G: value: lastStatusTime: "2024-02-20T10:41:38.657Z" - connectedNetworkType: 5GNSA - Connected-To-Non3gpp4g: + connectedNetworkType: 5G + Connected-to-Undetermined: value: lastStatusTime: "2024-02-20T10:41:38.657Z" - connectedNetworkType: NON3GPP4G - Not-Connected: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - connectedNetworkType: NOT_CONNECTED + connectedNetworkType: UNKNOWN "400": $ref: "#/components/responses/Generic400" "401": @@ -156,24 +150,19 @@ components: ConnectedNetworkType: description: | - * NOT_CONNECTED: The device is not connected to network + * UNKNOWN: Used when connection [technology] can not be determined * 2G: 2nd Generation Mobile Communication Technology * 3G: 3rd Generation Mobile Communication Technology - * 4GLTE: 4th Generation Mobile Communication Technology aka LTE - * 5GNSA:4th Generation Mobile Communication Technology aka LTE with device connected 5G New Radio (NR) - * 5GSA: 5th Generation Mobile Communication Technology - * NON3GPP4G: Device connected via non-3GPP Radio Access Technology but connected to 4G Network (e.g. WiFi Calling) - * NON3GPP5G: Device connected via non-3GPP Radio Access Technology but connected to 5G Network (e.g. WiFi Calling) + * 4G: 4th Generation Mobile Communication Technology + * 5G: 5th Generation Mobile Communication Technology + type: string enum: - 2G - 3G - - 4GLTE - - 5GNSA - - 5GSA - - NON3GPP4G - - NON3GPP5G - - NOT_CONNECTED + - 4G + - 5G + - UNKNOWN Device: description: | From 5d94fb059fd6497be5213ae328ba2c4f76136dee Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Wed, 20 Nov 2024 09:01:58 -0500 Subject: [PATCH 05/10] Update connected-network-type.yaml Update v0 - vwip Corrected tag with matching strings --- code/API_definitions/connected-network-type.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 36cf4961..16822aeb 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -50,19 +50,19 @@ externalDocs: url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/network-type-retrieval/v0" + - url: "{apiRoot}/network-type-retrieval/vwip" variables: apiRoot: default: http://localhost:9091 description: API root tags: - - name: Connected Network Type + - name: Connected Network Type description: Operations to get the network type device is connected to paths: /retrieve-network-type: post: tags: - - Connected network type + - Connected Network Type summary: "Get the connected network type" description: Get the connected network type operationId: getConnectedNetworkType From 93e3c7d203737d91242a2148c58c23429d09fcf8 Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Mon, 2 Dec 2024 15:32:41 -0500 Subject: [PATCH 06/10] Update connected-network-type.yaml changed api-name to connected-network-type changed path to /retrieve only added to description of /retrieve method changed schema label from RequestConnectedNetworkType to ConnectedNetworkTypeRequest --- code/API_definitions/connected-network-type.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 16822aeb..1a145693 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -31,7 +31,7 @@ info: ## Connected Network Type - The endpoint `POST /retrieve-network-type` allows to get connected Network Type. + The endpoint `POST /retrieve` allows to get connected Network Type. ## Further info and support @@ -50,7 +50,7 @@ externalDocs: url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/network-type-retrieval/vwip" + - url: "{apiRoot}/connected-network-type/vwip" variables: apiRoot: default: http://localhost:9091 @@ -59,12 +59,12 @@ tags: - name: Connected Network Type description: Operations to get the network type device is connected to paths: - /retrieve-network-type: + /retrieve: post: tags: - Connected Network Type summary: "Get the connected network type" - description: Get the connected network type + description: Get the connected network type to which the user device is connected operationId: getConnectedNetworkType parameters: - $ref: '#/components/parameters/x-correlator' @@ -75,7 +75,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RequestConnectedNetworkType" + $ref: "#/components/schemas/ConnectedNetworkTypeRequest" required: true responses: "200": @@ -242,7 +242,7 @@ components: format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - RequestConnectedNetworkType: + ConnectedNetworkTypeRequest: type: object properties: device: From 06d508536e890b9f27151d971b25bad1519a50a3 Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Fri, 6 Dec 2024 15:30:32 -0500 Subject: [PATCH 07/10] Update code/API_definitions/connected-network-type.yaml Co-authored-by: Eric Murray --- code/API_definitions/connected-network-type.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 1a145693..64a435ff 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -8,7 +8,7 @@ info: ## Connected Network Type - API consumer is able to inquire device's connected network type. + The API consumer is able to query the device's connected network type. The API provider can determine this in various ways. For example, the network type can be inferred from the specific radio cell to which the device is connected, as radio cells only support a single technology. It is important to note that the API does not query the device directly. # Relevant terms and definitions From fa2095268fd9465fac018d9cbdebd9917941f53f Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Fri, 6 Dec 2024 16:18:38 -0500 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Eric Murray --- .../connected-network-type.yaml | 35 ++++++++++++++----- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index 64a435ff..cfd5efb1 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -33,7 +33,19 @@ info: The endpoint `POST /retrieve` allows to get connected Network Type. + # Identifying the device from the access token + This API requires the API consumer to identify a device as the subject of the API as follows: + - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided. + + - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. + + This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. + + ## Error handling: + - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. + + - If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison. ## Further info and support (FAQs will be added in a later version of the documentation) @@ -314,11 +326,6 @@ components: status: 403 code: "PERMISSION_DENIED" message: "Client does not have sufficient permissions to perform this action" - InvalidTokenContext: - value: - status: 403 - code: INVALID_TOKEN_CONTEXT - message: Invalid access token context ConnectedStatusNotFound404: description: Resource Not Found headers: @@ -337,7 +344,7 @@ components: DeviceIdentifierNotFound: value: status: 404 - code: DEVICE_NOT_FOUND + code: IDENTIFIER_NOT_FOUND message: Some identifier cannot be matched to a device Generic409: description: Conflict @@ -365,18 +372,28 @@ components: UnsupportedDeviceIdentifiers: value: status: 422 - code: UNSUPPORTED_DEVICE_IDENTIFIERS + code: UNSUPPORTED_IDENTIFIER message: "None of the provided device identifiers is supported by the implementation" InconsistentDeviceIdentifiers: value: status: 422 - code: DEVICE_IDENTIFIERS_MISMATCH + code: IDENTIFIER_MISMATCH message: Device identifiers mismatch DeviceNotSupported: value: status: 422 - code: DEVICE_NOT_APPLICABLE + code: SERVICE_NOT_APPLICABLE message: Service not applicable to the device + UnnecessaryDeviceIdentifier: + value: + status: 422 + code: UNNECESSARY_IDENTIFIER + message: The device is already identified by the access token + MissingIdentifier: + value: + status: 422 + code: MISSING_IDENTIFIER + message: The device cannot be identified Generic500: description: Server error headers: From 14362a4496d90f96e2f19da73e9592bf4dcf0ca6 Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Wed, 11 Dec 2024 16:13:44 -0500 Subject: [PATCH 09/10] Update connected-network-type.yaml --- code/API_definitions/connected-network-type.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index cfd5efb1..eb1eb6dd 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -15,10 +15,10 @@ info: * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. - * **Network Type** : Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. - - `2G`, if device is connected to the 2G network technology - - `3G`, if device is connected to the 3G network technology - - `4G`, if device is connected to the 4G network technology + * **Network Type** : Network Type is intended to provide insight into connected network's capabilities from standards perspective, and to reflect the mobile technology that would be displayed by the device to the end user where applicable. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. + - `2G`, if device is connected to the 2G network technology (alternative indicators such as "G" or "E" may be displayed on the device) + - `3G`, if device is connected to the 3G network technology (alternative indicators such as "H" or "H+" may be displayed on the device) + - `4G`, if device is connected to the 4G network technology (alternative indicators such as "LTE" or "LTE+" may be displayed on the device) - `5G`, if device is connected to the 5G network technology - `UNKNOWN` if connection [technology] can not be determined From 9052723c5d61253db51950b4ea03b59972a2e9b9 Mon Sep 17 00:00:00 2001 From: Murat Karabulut <88037779+gmuratk@users.noreply.github.com> Date: Tue, 17 Dec 2024 10:15:44 -0500 Subject: [PATCH 10/10] Update code/API_definitions/connected-network-type.yaml Co-authored-by: Eric Murray --- code/API_definitions/connected-network-type.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/code/API_definitions/connected-network-type.yaml b/code/API_definitions/connected-network-type.yaml index eb1eb6dd..ea1758b5 100644 --- a/code/API_definitions/connected-network-type.yaml +++ b/code/API_definitions/connected-network-type.yaml @@ -259,8 +259,6 @@ components: properties: device: $ref: "#/components/schemas/Device" - required: - - device ErrorInfo: type: object