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. # Relevant terms and definitions * **Identifier for the device**: 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. * **Identifier for the application server**: IPv4 and/or IPv6 address of the application server (application backend) * **Notification URL and token**: Developers may provide a callback URL on which notifications can be received from the service provider. This is an optional parameter. # API functionality Following diagram shows the interaction between different components ![Sequence Diagram](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r2.2/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png) ### Notification callback This endpoint describes the event notification received on subscription listener side when the event occurred. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document. **WARNING**: This callback endpoint must be exposed on the listener side as `POST /{$request.body#/sink}` will be posted by the connectivity insights resource server to the webhook url provided by notification listener. ### Data Minimization #### phoneNumber presence: These rules apply for subscription: - If 3-legged access token is used, the POST and GET{id} requests & responses must NOT provide thev``phoneNumber``. For GET (list) only subscription(s) for this exactly phone number is/are retrieved (implicit filtering). - If 2-legged access token is used, for POST and GET{id}, the presence of``phoneNumber`` in the request & response is mandatory. For GET (list)the device identifier (``phoneNumber``) could be used as filtering criteria. #### sinkCredential presence: ``sinkCredential`` is only present in POST request and not provided in POST or GET response. # 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 `phoneNumber` identifier, which therefore MUST be provided. - When a three-legged access token is used however, this optional `phoneNumber` 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 `phoneNumber` identifier 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 `phoneNumber` identifier 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-subscriptions/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: Connectivity Insights Subscriptions description: | Create and manage a subscription to receive periodic connectivity insights paths: /subscriptions: post: tags: - Connectivity Insights Subscriptions description: "Create a Connectivity insights subscription for a device" summary: "Create a Connectivity insights subscription for a device" operationId: createSubscription parameters: - $ref: "#/components/parameters/x-correlator" security: - openId: - connectivity-insights-subscriptions:org.camaraproject.connectivity-insights-subscriptions.v0.network-quality:create requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionRequest" required: true callbacks: notifications: "{$request.body#/sink}": post: summary: "Subscription notification callback" description: | Important: this endpoint is to be implemented by the API consumer.The Connectivity Insights server will call this endpoint whenever a connectivity event occurs that changes the netowrk's ability to meet the application's demands for a given device. operationId: postNotification parameters: - $ref: "#/components/parameters/x-correlator" requestBody: required: true content: application/cloudevents+json:: schema: $ref: "#/components/schemas/CloudEvent" responses: "204": description: Successful notification headers: x-correlator: $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "410": $ref: "#/components/responses/Generic410" "429": $ref: "#/components/responses/Generic429" security: - {} - notificationsBearerAuth: [] responses: "201": description: Created headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/Subscription" "202": description: | Request accepted to be processed. It applies for async creation process. headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/SubscriptionAsync" "400": $ref: "#/components/responses/CreateSubscriptionBadRequest400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/SubscriptionPermissionDenied403" "409": $ref: "#/components/responses/Generic409" "422": $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422" "429": $ref: "#/components/responses/Generic429" get: tags: - Connectivity Insights Subscriptions summary: "Retrieve a list of apiName event subscription" operationId: getSubscriptionList description: | Operation to list subscriptions authorized to be retrieved by the provided access token. parameters: - $ref: "#/components/parameters/x-correlator" security: - openId: - connectivity-insights-subscriptions:read responses: "200": description: List of event subscription details headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: type: array minItems: 0 items: $ref: "#/components/schemas/Subscription" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" /subscriptions/{subscriptionId}: get: tags: - Connectivity Insights Subscriptions summary: "Operation to retrieve a subscription based on the provided ID" operationId: getSubscription description: Retrieve a given subscription by ID security: - openId: - connectivity-insights-subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: "#/components/parameters/x-correlator" responses: "200": description: OK headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/Subscription" "400": $ref: "#/components/responses/SubscriptionIdRequired400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" delete: tags: - Connectivity Insights Subscriptions summary: "Operation to delete a subscription" operationId: deleteSubscription description: Delete a given subscription by ID security: - openId: - connectivity-insights-subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: "#/components/parameters/x-correlator" responses: "204": description: apiName subscription deleted headers: x-correlator: $ref: "#/components/headers/x-correlator" "202": description: | Request accepted to be processed. It applies for async deletion process. headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/SubscriptionAsync" "400": $ref: "#/components/responses/SubscriptionIdRequired400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" components: securitySchemes: openId: type: openIdConnect description: Common security scheme for all CAMARA APIs openIdConnectUrl: https://example.com/.well-known/openid-configuration notificationsBearerAuth: description: Bearer authorization for notifications type: http scheme: bearer bearerFormat: "{$request.body#/sinkCredential.credentialType}" parameters: SubscriptionId: name: subscriptionId in: path description: | Subscription identifier that was obtained from the create event subscription operation required: true schema: $ref: "#/components/schemas/SubscriptionId" x-correlator: name: x-correlator in: header description: Correlation id for the different services schema: type: string pattern: ^[a-zA-Z0-9-]{0,55}$ example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" headers: x-correlator: description: Correlation id for the different services schema: type: string pattern: ^[a-zA-Z0-9-]{0,55}$ schemas: 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 Subscription: description: Represents a event-type subscription. type: object required: - sink - protocol - config - types - id - startsAt properties: protocol: $ref: "#/components/schemas/Protocol" sink: type: string format: uri description: | The address to which events shall be delivered using the selected protocol. example: "https://endpoint.example.com/sink" types: description: | Camara Event types eligible to be delivered by this subscription. Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array items: type: string config: $ref: "#/components/schemas/Config" subscriptionId: type: string description: | The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). example: "1119920371" startsAt: type: string format: date-time description: Date when the event subscription will begin/began 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" expiresAt: type: string format: date-time description: | Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. 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" status: type: string description: |- Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details: - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet. - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative. - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted. - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event. - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its metainformation is kept). enum: - ACTIVATION_REQUESTED - ACTIVE - EXPIRED - DEACTIVE - DELETED discriminator: propertyName: protocol mapping: HTTP: "#/components/schemas/HTTPSubscriptionResponse" MQTT3: "#/components/schemas/MQTTSubscriptionResponse" MQTT5: "#/components/schemas/MQTTSubscriptionResponse" AMQP: "#/components/schemas/AMQPSubscriptionResponse" NATS: "#/components/schemas/NATSSubscriptionResponse" KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse" SubscriptionAsync: description: | Response for a event-type subscription request managed asynchronously (Creation or Deletion) type: object properties: subscriptionId: $ref: "#/components/schemas/SubscriptionId" SubscriptionId: type: string description: | The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). example: qs15-h556-rt89-1298 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 Protocol: type: string enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] description: | Identifier of a delivery protocol. Only HTTP is allowed for now example: "HTTP" 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 Config: description: | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` Specific event type attributes must be defined in `subscriptionDetail` Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. type: object required: - subscriptionDetail properties: subscriptionDetail: $ref: "#/components/schemas/CreateSubscriptionDetail" subscriptionExpireTime: type: string format: date-time description: | The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it. 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" subscriptionMaxEvents: type: integer description: | Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Note on combined usage of `initialEvent` and `subscriptionMaxEvents`: If an event is triggered following `initialEvent` set to `true`, this event will be counted towards `subscriptionMaxEvents`. minimum: 1 example: 5 initialEvent: type: boolean description: | Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. SinkCredential: type: object description: | A sink credential provides authentication or authorization information properties: credentialType: type: string enum: - PLAIN - ACCESSTOKEN - REFRESHTOKEN description: | The type of the credential. Note: Type of the credential - MUST be set to ACCESSTOKEN for now discriminator: propertyName: credentialType mapping: PLAIN: "#/components/schemas/PlainCredential" ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential" required: - credentialType CreateSubscriptionDetail: description: The detail of the requested event subscription type: object properties: 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" applicationProfileId: $ref: "#/components/schemas/ApplicationProfileId" required: - device - applicationProfileId SubscriptionRequest: description: The request for creating a event-type event subscription type: object required: - sink - protocol - config - types properties: protocol: $ref: "#/components/schemas/Protocol" sink: type: string format: uri description: | The address to which events shall be delivered using the selected protocol. example: "https://endpoint.example.com/sink" sinkCredential: $ref: "#/components/schemas/SinkCredential" types: description: | Camara Event types eligible to be delivered by this subscription. Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array items: type: string example: org.camaraproject.connectivity-insights-subscriptions.v0.network-quality config: $ref: "#/components/schemas/Config" NetworkQualityInsight: 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: papplicationProfileId: $ref: "#/components/schemas/ApplicationProfileId" 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" 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 Source: type: string format: uri-reference minLength: 1 description: | Identifies the context in which an event happened, as a non-empty `URI-reference` like: - URI with a DNS authority: * https://github.com/cloudevents * mailto:cncf-wg-serverless@lists.cncf.io - Universally-unique URN with a UUID: * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - Application-specific identifier: * /cloudevents/spec/pull/123 * 1-555-123-4567 example: "https://notificationSendServer12.supertelco.com" CloudEvent: description: The Cloud-Event used for the callback. required: - id - source - specversion - type - time properties: id: type: string description: | identifier of this event, that must be unique in the source context. source: $ref: "#/components/schemas/Source" type: $ref: "#/components/schemas/EventTypeNotification" specversion: type: string description: | Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) enum: - "1.0" datacontenttype: type: string description: | 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' enum: - application/json data: $ref: "#/components/schemas/NetworkQualityInsight" time: $ref: "#/components/schemas/DateTime" discriminator: propertyName: "type" mapping: org.camaraproject.connectivity-insights-subscriptions.v0.network-quality: "#/components/schemas/EventNetworkQuality" org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: "#/components/schemas/EventSubscriptionEnds" EventNetworkQuality: description: event structure for Network Quality allOf: - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: $ref: "#/components/schemas/NetworkQualityInsight" EventSubscriptionEnds: description: event structure for event subscription ends allOf: - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: $ref: "#/components/schemas/SubscriptionEnds" SubscriptionEnds: description: Event detail structure for SUBSCRIPTION_ENDS event type: object required: - terminationReason - subscriptionId properties: terminationReason: $ref: "#/components/schemas/TerminationReason" subscriptionId: $ref: "#/components/schemas/SubscriptionId" terminationDescription: type: string TerminationReason: type: string description: | - NETWORK_TERMINATED - API server stopped sending notification - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached enum: - MAX_EVENTS_REACHED - NETWORK_TERMINATED - SUBSCRIPTION_EXPIRED - ACCESS_TOKEN_EXPIRED DateTime: type: string format: date-time description: | Timestamp of when the occurrence happened. 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" EventTypeNotification: type: string description: | event-type - Event triggered when an event-type event occurred subscription-ends: Event triggered when the subscription ends enum: - org.camaraproject.connectivity-insights-subscriptions.v0.network-quality - org.camaraproject.connectivity-insights-subscriptions.v0.subscription-ends 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: CreateSubscriptionBadRequest400: description: Problem with the client 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 - INVALID_PROTOCOL - INVALID_CREDENTIAL - INVALID_TOKEN 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. GENERIC_400_INVALID_PROTOCOL: description: Invalid protocol for events subscription management value: status: 400 code: INVALID_PROTOCOL message: Only HTTP is supported GENERIC_400_INVALID_CREDENTIAL: description: Invalid sink credential type value: status: 400 code: INVALID_CREDENTIAL message: Only Access token is supported GENERIC_400_INVALID_TOKEN: description: Invalid token type for sink credential of type ACCESSTOKEN value: status: 400 code: INVALID_TOKEN message: Only bearer token is supported Generic400: description: Problem with the client 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 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. SubscriptionIdRequired400: description: Problem with the client 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 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_SUBSCRIPTION_ID_REQUIRED: description: subscription id is required value: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: subscriptionId" Generic401: description: Authentication problem with the client request 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: Client does not have sufficient permission 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 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. SubscriptionPermissionDenied403: description: Client does not have sufficient permission 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 - SUBSCRIPTION_MISMATCH 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_SUBSCRIPTION_MISMATCH: description: Inconsistent access token for requested subscription value: status: 403 code: "SUBSCRIPTION_MISMATCH" message: "Inconsistent access token for requested events subscription" Generic404: description: Resource 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 examples: GENERIC_404_NOT_FOUND: description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. Generic409: description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 409 code: enum: - ABORTED - ALREADY_EXISTS 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. Generic410: description: Gone headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 410 code: enum: - GONE 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. CreateSubscriptionUnprocessableEntity422: description: Unprocessable Entity headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 422 code: enum: - SERVICE_NOT_APPLICABLE - MISSING_IDENTIFIER - UNNECESSARY_IDENTIFIER examples: GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service not applicable for the provided identifier value: status: 422 code: SERVICE_NOT_APPLICABLE message: The service is not available for the provided identifier. GENERIC_422_MISSING_IDENTIFIER: description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token value: status: 422 code: MISSING_IDENTIFIER message: The device cannot be identified. GENERIC_422_UNNECESSARY_IDENTIFIER: description: An explicit identifier is provided when a device or phone number has already been identified from the access token value: status: 422 code: UNNECESSARY_IDENTIFIER message: The device is already identified by the access token. 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.