openapi: 3.0.3 info: title: Connectivity Insights version: 0.4.0 x-camara-commonalities: 0.4.0 description: | With CAMARA Connectivity Insights, application developers gain essential visibility into network quality. This enables them to make informed decisions that enhance the end-user experience for their applications. # Introduction The Connectivity Insights API allows an application developer to ask the network the likelihood that an application's networking requirements can be met for a given end user session. This information helps a developer ensure their end users are able to get the best experience while using the application over their current network. Depending on the answer the network gives, the developer may decide to request a network boost (via the CAMARA QoD API) , and/or apply specific changes on the application side e.g. adjusting the resolution of the video stream upwards or downwards. # API functionality Prerequisite: authorisation and authentication Usage: 1. create an application profile using the Connectivity Insights `application-profiles` API 2. Request: POST `check-network-quality`, passing the `applicationProfileId` obtained in step 1, the address/port of an application server, and at least one device identifier. 3. Response: The network will indicate whether it can or cannot meet the application requirements. 3. Optional: use the `connectivity-insights-subscriptions` API to receive notifications of network quality. Following diagram shows the interaction between different components ![Sequence Diagram](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/main/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png) # Identifying the device This can be achieved either by passing at least one device identifier in the POST request body, or, from the 3-legged access token where implemented by the operator. Device identifiers in POST request body: * `IPv4-Address` or `IPv6-Address`. This is the public IP address of the user device: this can be obtained by an application hosted on that device calling a public IP address API (e.g. GET https://api.ipify.org?format=json) * If you provide an `IPv4-Address` or `IPv6-Address`: for certain operators you may be required to also provide a `Public-port` header. * `Phone-Number` . The international E.164 format (starting with country code), e.g. +4407123123456 * `Network-Access-Identifier` (where available from the API host operator) NOTE1: the network operators 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. ### Authorization and authentication The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: Product documentation at CAMARA. url: https://github.com/camaraproject/ConnectivityInsights servers: - url: "{apiRoot}/connectivity-insights/v0.4" variables: apiRoot: default: http://localhost:9091 description: | API root, defined by service provider, e.g. `api.example.com` or `api.example.com/somepath` tags: - name: Network Quality description: | Read the network's level of confidence that it can meet the quality thresholds for a given application profile and end user device. paths: /check-network-quality: post: security: - openId: - connectivity-insights:check tags: - Network Quality summary: Check the network quality. description: | Check the network quality. The response shows the network's current level of confidence that it can meet an application profile's quality thresholds for a given end user device. operationId: checkNetworkQuality requestBody: description: | An `ApplicationProfileId` and one or more device identifiers. Together these allow the network to calculate whether the thresholds defined in the application profile can be met for the particular connected device. content: application/json: schema: $ref: "#/components/schemas/NetworkQualityInsightRequest" required: true responses: "200": description: OK headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/NetworkQualityInsightResponse" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" "422": $ref: "#/components/responses/Generic422" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" components: securitySchemes: openId: description: OpenID Provider Configuration Information type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration headers: x-correlator: description: Correlation id for the different services schema: type: string schemas: NetworkQualityInsightRequest: description: | request body to query the network quality for a given device and application profile type: object properties: applicationProfileId: $ref: "#/components/schemas/ApplicationProfileId" device: $ref: "#/components/schemas/Device" applicationServer: $ref: "#/components/schemas/ApplicationServer" applicationServerPorts: description: | A list of single ports or port ranges on the application server allOf: - $ref: "#/components/schemas/PortsSpec" monitoringTimeStamp: type: string format: date-time description: | this is an optional input parameter. A future data and time can be provided for predictive data. If no value is provided then the current date and time is used and network data for the monitoring data aggregation is used to check network performance against the application profile defined. NetworkQualityInsightResponse: type: object description: the network's confidence level at being able to meet the network demands of a given policy for a given terminal device. properties: packetDelayBudget: $ref: "#/components/schemas/PolicyFulfillmentConfidence" targetMinDownstreamRate: $ref: "#/components/schemas/PolicyFulfillmentConfidence" targetMinUpstreamRate: $ref: "#/components/schemas/PolicyFulfillmentConfidence" packetlossErrorRate: $ref: "#/components/schemas/PolicyFulfillmentConfidence" jitter: $ref: "#/components/schemas/PolicyFulfillmentConfidence" additionalKPIs: $ref: "#/components/schemas/AdditionalKpis" AdditionalKpis: description: additional information about connectivity quality type: object properties: signalStrength: description: | rough indication of the end user device radio signal conditions type: string enum: - excellent - good - fair - poor - no signal connectivityType: description: | the access technology connecting the user device to the operator network type: string enum: - 5G-SA - 5G-NSA - 4G - 3G 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` NOTE1: 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. 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 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" 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, optionally prefixed with '+'. type: string pattern: '^\+?[0-9]{5,15}$' example: "123456789" 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" 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). The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts. type: string format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 Port: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 PortsSpec: description: Specification of several TCP or UDP ports type: object minProperties: 1 properties: ranges: description: Range of TCP or UDP ports type: array minItems: 1 items: type: object required: - from - to properties: from: $ref: "#/components/schemas/Port" to: $ref: "#/components/schemas/Port" ports: description: Array of TCP or UDP ports type: array minItems: 1 items: $ref: "#/components/schemas/Port" example: ranges: - from: 5010 to: 5020 ports: - 5060 - 5070 ApplicationServer: description: | A server hosting backend applications to deliver some business logic to clients. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` The Operator will use this information to calculate the end to end network performance in scenarios where its feasible. type: object properties: ipv4Address: $ref: "#/components/schemas/ApplicationServerIpv4Address" ipv6Address: $ref: "#/components/schemas/ApplicationServerIpv6Address" minProperties: 1 ApplicationServerIpv4Address: type: string example: "192.168.0.1/24" description: | IPv4 address may be specified in form
as: - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. ApplicationServerIpv6Address: type: string example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" description: | IPv6 address may be specified in form
as: - address - The /128 subnet is optional for single addresses: - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - address/mask - an IP v6 number with a mask: - 2001:db8:85a3:8d3::0/64 - 2001:db8:85a3:8d3::/64 PolicyFulfillmentConfidence: type: string description: | a plain-language indicator of how confident the network is to meet a given network demand. enum: - meets the application requirements - unable to meet the application requirements ApplicationProfileId: description: Identifier for the Application Profile type: string format: uuid ErrorInfo: type: object description: Error information required: - status - code - message properties: status: type: integer description: HTTP status code returned along with this error response code: type: string description: Code given to this error message: type: string description: Detailed error description responses: Generic400: description: Bad Request headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: 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. Generic401: description: Unauthorized headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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. Generic403: description: Forbidden headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' 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: phoneNumber 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: GENERIC_404_NOT_FOUND: description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. Generic422: description: Unprocessable Content headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_422_NOT_SUPPORTED: description: Not Supported value: status: 422 code: NOT_SUPPORTED message: Service not supported for this phoneNumber UNIDENTIFIABLE_PHONE_NUMBER: description: The phone number is not included in the request and the phone number information cannot be derived from the 3-legged access token value: status: 422 code: UNIDENTIFIABLE_PHONE_NUMBER message: The phone number cannot be identified Generic500: description: Internal Server Error headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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. Generic503: description: Service Unavailable headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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.