diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index 65af53a..330c2a2 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -1,9 +1,7 @@ openapi: 3.0.3 info: title: Connectivity Insights - version: "0.4.0-rc.1" - contact: - email: sp-coi@lists.camaraproject.org + version: 0.4.0-rc.1 x-camara-commonalities: 0.4.0 description: | With CAMARA Connectivity Insights, application developers gain essential @@ -25,42 +23,60 @@ info: 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 + 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. + + todo: sequence diagram + + # 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. - Following diagram shows the interaction between different components - ![Sequence Diagram](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/main/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. # Authorization and Authentication - [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/ - CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + 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 @@ -94,31 +110,25 @@ servers: `api.example.com` or `api.example.com/somepath` tags: - - name: Quality Insights + - 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. - - name: Connectivity Insights Subscriptions - description: | - Create and manage a subscription to receive periodic connectivity - insights paths: - /network-quality/insights: + /check-network-quality: post: security: - openId: - - connectivity_insights:network_quality_insight:write + - connectivity-insights:check tags: - - Quality Insights - summary: Create an insight + - Network Quality + summary: Check the network quality. description: | - Create an insight. 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. An `insightId` is included - to support polling via the GET operation, or to requrest callbacks - via the Notification Management operations. - operationId: createNetworkQualityInsight + 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. @@ -141,389 +151,18 @@ paths: schema: $ref: "#/components/schemas/NetworkQualityInsightResponse" - /network-quality/insights/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:write - 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" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - 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/CreateSubscription403" - "409": - $ref: "#/components/responses/Generic409" - "415": - $ref: "#/components/responses/Generic415" - "422": - $ref: "#/components/responses/CreateSubscription422" - "429": - $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - 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" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - /network-quality/insights/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/SubscriptionIdRequired" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - 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:write - 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/SubscriptionIdRequired" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - components: securitySchemes: openId: description: OpenID Provider Configuration Information type: openIdConnect 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 headers: x-correlator: description: Correlation id for the different services schema: type: string - 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: url - 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 - 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 - 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. - 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 NetworkQualityInsightRequest: description: | request body to query the network quality for a given device and @@ -541,12 +180,6 @@ components: A list of single ports or port ranges on the application server allOf: - $ref: "#/components/schemas/PortsSpec" - monitoringDataAggregation: - description: frequency of subscription reporting - enum: - - FIFTEEN_MIN - - HOURLY - - DAILY monitoringTimeStamp: type: string format: date-time @@ -556,6 +189,50 @@ components: current date and time is used and network data for the monitoring data aggregation is used to check network performance against the policy 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 @@ -643,7 +320,7 @@ components: anyOf: - required: [publicAddress, privateAddress] - required: [publicAddress, publicPort] - example: {"publicAddress":"84.125.93.10", "publicPort":59765} + example: {"publicAddress": "84.125.93.10", "publicPort": 59765} SingleIpv4Addr: description: A single IPv4 address with no subnet mask @@ -703,13 +380,6 @@ components: - 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 @@ -730,6 +400,7 @@ components: ipv6Address: $ref: "#/components/schemas/ApplicationServerIpv6Address" minProperties: 1 + ApplicationServerIpv4Address: type: string example: "192.168.0.1/24" @@ -753,157 +424,6 @@ components: - 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 - example: 2023-01-17T13:18:23.682Z - description: | - The subscription expiration time (in date-time format) requested by - the API consumer. Up to API project decision to keep it. - 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. Up to API project decision to keep it. - 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. - Example: Consumer request Roaming event. If consumer sets - initialEvent to true and device is in roaming situation, an event - is triggered Up to API project decision to keep it. - 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." - 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: url - 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.connectivityinsights.v0.policy-not-met, - org.camaraproject.connectivityinsights.v0.policy-met - config: - $ref: "#/components/schemas/Config" - - 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' - - NetworkQualityInsight: - 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: - papplicationProfileId: - $ref: "#/components/schemas/ApplicationProfileId" - 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" PolicyFulfillmentConfidence: type: string @@ -919,125 +439,6 @@ components: 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/Event-typeNotification" - 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.connectivityinsights.v0.networkQuality-event: "#/components/schemas/NetworkQualityTypeEvent" - org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: "#/components/schemas/EventSubscriptionEnds" - - NetworkQualityTypeEvent: - description: event structure for event-type event - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - - 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. Must adhere to RFC 3339. - example: "2018-04-05T17:31:00Z" - - Event-typeNotification: - type: string - description: | - event-type - Event triggered when an event-type event occurred - subscription-ends: Event triggered when the subscription ends - enum: - - org.camaraproject.connectivityinsights.v0.networkQuality-met - - org.camaraproject.connectivityinsights.v0.networkQuality-not-met - - org.camaraproject.connectivityinsights.v0.subscription-ends - ErrorInfo: type: object description: Error information @@ -1057,8 +458,8 @@ components: description: Detailed error description responses: - CreateSubscriptionBadRequest400: - description: Problem with the client request + Generic400: + description: Bad Request headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1067,45 +468,20 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - InvalidArgument: + 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" - InvalidProtocol: - value: - status: 400 - code: "INVALID_PROTOCOL" - message: "Only HTTP is supported" - InvalidCredential: - value: - status: 400 - code: "INVALID_CREDENTIAL" - message: "Only Access token is supported" - InvalidToken: + 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: "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: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: "INVALID_ARGUMENT" - message: | - "Client specified an invalid argument, - request body or query param" + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic401: - description: Authentication problem with the client request + description: Unauthorized headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1113,15 +489,21 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: "UNAUTHENTICATED" - message: | - "Request not authenticated due to missing, invalid, or - expired credentials" - - CreateSubscription403: - description: Client does not have sufficient permission + 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" @@ -1130,21 +512,20 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - PermissionDenied: + 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" - TokenMismatch: + 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: "SUSBCRIPTION_MISMATCH" - message: | - "Inconsistent access token for requested events subscription" - Generic403: - description: Client does not have sufficient permission + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + Generic404: + description: Resource Not Found headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1152,14 +533,21 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: "PERMISSION_DENIED" - message: | - "Client does not have sufficient permissions to perform - this action" - Generic404: - description: Resource 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_DEVICE_NOT_FOUND: + description: Device identifier not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. + Generic405: + description: Method Not Allowed headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1167,10 +555,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "The specified resource is not found" + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. Generic409: description: Conflict headers: @@ -1180,10 +571,25 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: "The specified resource is in a conflict" + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + GENERIC_409_CONFLICT: + description: Duplication of an existing resource + value: + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. Generic410: description: Gone headers: @@ -1193,27 +599,31 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 410 - code: GONE - message: | - "The specified resource is no longer available at the - requested address" + 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. Generic415: description: Unsupported Media Type headers: - X-Correlator: + x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: "The specified media type is not supported" - CreateSubscription422: - description: Unprocessable Entity + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + Generic422: + description: Unprocessable Content headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1222,26 +632,48 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - PermissionDenied: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device value: status: 422 - code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" - message: "Multi event types subscription not managed" + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: The device cannot be identified. Generic429: description: Too Many Requests headers: - X-Correlator: + x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 429 - code: TOO_MANY_REQUESTS - message: "Endpoint does not support as many requests per time slot" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. Generic500: - description: Server error + description: Internal Server Error headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1249,12 +681,31 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: "INTERNAL" - message: "Server error" - Generic503: - description: Service unavailable. Typically the server is down. + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic501: + description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: + description: Bad Gateway headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1262,12 +713,15 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: "UNAVAILABLE" - message: "Service unavailable" - SubscriptionIdRequired: - description: Problem with the client request + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: + description: Service Unavailable headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1276,17 +730,25 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - Generic400: - summary: Schema validation failed + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side value: - status: 400 - code: INVALID_ARGUMENT - message: | - "Client specified an invalid argument, request body or query - param" - subscriptionIdRequired: - summary: subscription id is required + 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: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: subscriptionId" + status: 504 + code: TIMEOUT + message: Request timeout exceeded.