openapi: 3.0.3 info: title: Connectivity Insights version: 0.5.0 x-camara-commonalities: 0.5 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/r2.2/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png) # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. # 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. 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.5" 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" "429": $ref: "#/components/responses/Generic429" components: securitySchemes: openId: type: openIdConnect description: Common security scheme for all CAMARA APIs openIdConnectUrl: https://example.com/.well-known/openid-configuration headers: x-correlator: description: Correlation id for the different services schema: type: string pattern: ^[a-zA-Z0-9-]{0,55}$ 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. 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: "2023-07-03T12:27:08.312Z" NetworkQualityInsightResponse: type: object description: the network's confidence level at being able to meet the network demands of a given application for a given terminal device. properties: packetDelayBudget: $ref: "#/components/schemas/NetworkQualityThresholdsConfidence" targetMinDownstreamRate: $ref: "#/components/schemas/NetworkQualityThresholdsConfidence" targetMinUpstreamRate: $ref: "#/components/schemas/NetworkQualityThresholdsConfidence" packetlossErrorRate: $ref: "#/components/schemas/NetworkQualityThresholdsConfidence" jitter: $ref: "#/components/schemas/NetworkQualityThresholdsConfidence" 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 NetworkQualityThresholdsConfidence: 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: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - OUT_OF_RANGE 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. 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: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED - AUTHENTICATION_REQUIRED 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: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED - INVALID_TOKEN_CONTEXT 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: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 404 code: enum: - NOT_FOUND - IDENTIFIER_NOT_FOUND examples: GENERIC_404_NOT_FOUND: description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. GENERIC_404_IDENTIFIER_NOT_FOUND: description: Some identifier cannot be matched to a device value: status: 404 code: IDENTIFIER_NOT_FOUND message: Device identifier 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_IDENTIFIER_MISMATCH: description: Inconsistency between device identifiers not pointing to the same device value: status: 422 code: IDENTIFIER_MISMATCH message: Provided identifiers are not consistent. GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service is not available for the provided device value: status: 422 code: SERVICE_NOT_APPLICABLE message: The Service is not available for the provided device. GENERIC_422_MISSING_IDENTIFIER: description: An identifier is not included in the request and the device or phone number identificationinformation cannot be derived from the 3-legged access token value: status: 422 code: MISSING_IDENTIFIER message: The device cannot be identified. Generic429: description: Too Many Requests headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 429 code: enum: - QUOTA_EXCEEDED - TOO_MANY_REQUESTS examples: GENERIC_429_QUOTA_EXCEEDED: description: Request is rejected due to exceeding a business quota limit value: status: 429 code: QUOTA_EXCEEDED message: Out of resource quota. GENERIC_429_TOO_MANY_REQUESTS: description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached value: status: 429 code: TOO_MANY_REQUESTS message: Rate limit reached.