From f827289c566e66053f99d2bdbef967fbeb7e6b98 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Fri, 4 Sep 2026 19:38:00 +0200 Subject: [PATCH] feat(qos-profiles): seed API and test definitions from QualityOnDemand source/r4.1 --- code/API_definitions/qos-profiles.yaml | 678 ++++++++++++++++++ .../qos-profiles-getQosProfile.feature | 149 ++++ .../qos-profiles-retrieveQoSProfiles.feature | 292 ++++++++ 3 files changed, 1119 insertions(+) create mode 100644 code/API_definitions/qos-profiles.yaml create mode 100644 code/Test_definitions/qos-profiles-getQosProfile.feature create mode 100644 code/Test_definitions/qos-profiles-retrieveQoSProfiles.feature diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml new file mode 100644 index 0000000..a4478b6 --- /dev/null +++ b/code/API_definitions/qos-profiles.yaml @@ -0,0 +1,678 @@ +openapi: 3.0.3 +info: + title: QoS Profiles + description: | + The Quality-of-Service (QoS) Profiles API provides a set of predefined network performance characteristics, such as latency, throughput, and priority, identified by a unique name. These profiles allow API consumers to specify the desired network behavior for their application's data traffic, ensuring optimal performance. By selecting an appropriate QoS profile, API consumers can request stable latency (reduced jitter) or throughput for specific data flows between client devices and application servers when used by the Quality-On-Demand APIs. + + # Introduction + + QoS Profiles are used in conjunction with other Quality-On-Demand APIs, to offer the API consumer the capability to request for stable latency (reduced jitter) or throughput for some specified application data flows between application clients (within a user device) and Application Servers (backend services). The API consumer has a pre-defined set of Quality of Service (QoS) profiles which they could choose from depending on their latency or throughput requirements. The QoS profiles are defined by the API provider and are mapped to the connectivity characteristics of the supported networks. + + # API functionality + + The QoS Profiles API provides the following functionality: + - Discover all QoS profiles offered by the API provider + - Discover the available QoS profiles for a specific device + - Retrieve the characteristics of a specific QoS profile by name + + How QoS profiles are mapped to connectivity characteristics are subject to agreements between the API provider and the API consumer. Within the CAMARA project, you can find a sample for such a mapping of QoS profiles. [CAMARA QoS Profiles Mapping Table (REFERENCE DRAFT)](https://github.com/camaraproject/QualityOnDemand/blob/main/documentation/API_documentation/QoSProfile_Mapping_Table.md) + + + + # 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 + + The two operations defined by this API (`getQosProfile` and `retrieveQoSProfiles`) both allow the API consumer to use a three-legged access token to specify a target device as a query filter. When provided, only profiles available to the specified target device will be returned. Additionally, when a two-legged access token is used, the operation `retrieveQoSProfiles` allows the API consumer to optionally specify the target device in the request body. + + Hence, for the `retrieveQoSProfiles` operation: + - When invoked using a two-legged access token, the optional input device object will be used as filter if present. + + - When invoked using a three-legged access token, this optional identifier in the request body MUST NOT be provided, as the device to filter 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 device 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. + + # Multi-SIM scenario handling + + In multi-SIM scenarios where more than one mobile device is associated with a phone number (e.g. a smartphone with an associated smartwatch), it might not be possible to uniquely identify a single device from that phone number. When filtering QoS profiles by device in such scenarios, one of the following options should be used: + - Use the authorisation code flow to obtain a 3-legged access token, which will automatically identify the intended device + - Identify the intended device from a unique identifier for that device, such as its source IP address and port + - Check with the SIM provider whether a unique "secondary" phone number is already associated with each device, and use the secondary phone number to identify the intended device if available + + + + # Additional CAMARA error responses + + The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. + + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + + As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + + + + + # Request body strictness + + This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. + + + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip + x-camara-commonalities: 0.8.0 + + +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/QualityOnDemand + +servers: + - url: "{apiRoot}/qos-profiles/vwip" + variables: + apiRoot: + default: http://localhost:9091 + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` + +tags: + - name: QoS Profiles + description: Manage QoS Profiles + +paths: + /retrieve-qos-profiles: + post: + tags: + - QoS Profiles + summary: Retrieve QoS profiles + description: | + Returns all QoS Profiles that match the given criteria. + **NOTES:** + - The access token may be either a 2-legged or 3-legged access token. + - If the access token is 3-legged, all returned QoS Profiles will be available to the subject (device) associated with the access token. + - If the access token is 2-legged and a device filter is provided, all returned QoS Profiles will be available to that device. If multiple device identifiers are provided within the device property, only QoS Profiles available to the device identifier chosen by the implementation will be returned, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user. + - This call uses the POST method instead of GET to comply with the CAMARA Commonalities guidelines for sending sensitive or complex data in API calls. Since the device field may contain personally identifiable information, it should not be sent via GET. Additionally, this call may include complex data structures. + [CAMARA API Design Guidelines](https://github.com/camaraproject/Commonalities/blob/r3.3/documentation/API-design-guidelines.md#post-or-get-for-transferring-sensitive-or-complex-data) + + security: + - openId: + - qos-profiles:read + operationId: retrieveQoSProfiles + parameters: + - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" + requestBody: + description: Parameters to query QoS Profiles for a given device + content: + application/json: + schema: + $ref: "#/components/schemas/QosProfileDeviceRequest" + required: true + responses: + "200": + description: Contains information about QoS Profiles + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + content: + application/json: + schema: + type: array + maxItems: 100 + items: + $ref: "#/components/schemas/QosProfile" + examples: + List of QoS Profiles: + $ref: "#/components/examples/LIST_OF_QOS_PROFILES" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/RetrieveQosProfilesNotFound404" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + + /qos-profiles/{name}: + get: + tags: + - QoS Profiles + summary: "Get QoS Profile for a given name" + operationId: getQosProfile + description: | + Returns a QoS Profile that matches the given name. + + The access token may be either a 2-legged or 3-legged access token. If the access token is 3-legged, a QoS Profile is only returned if available to all subjects associated with the access token. + + security: + - openId: + - qos-profiles:read + parameters: + - name: name + in: path + description: Qos Profile name + required: true + schema: + $ref: "#/components/schemas/QosProfileName" + - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" + responses: + "200": + description: Contains information about QoS Profiles + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/QosProfile" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/NotFound404" + "429": + $ref: "#/components/responses/Generic429" + +components: + securitySchemes: + openId: + $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId" + + schemas: + QosProfile: + description: | + Data type with attributes of a QosProfile + type: object + properties: + name: + $ref: "#/components/schemas/QosProfileName" + description: + description: | + A description of the QoS profile. + type: string + maxLength: 1024 + # Excludes control characters (C0 except TAB/LF/CR, DEL, C1) so that + # multiline descriptions remain valid + pattern: '^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]*$' + example: "QoS profile for video streaming" + status: + $ref: "#/components/schemas/QosProfileStatusEnum" + countryAvailability: + description: | + A list of countries, and optionally networks, for which the API provider makes the profile available. + - When profiles are filtered for a specific device (i.e. using a 3-legged access token or an explicit device filter parameter), the profile can be used by that device in any of these countries when connected to any of the listed networks (assuming roaming is permitted for networks that are not the device's home network), or the API provider's own network if no networks are listed + - When there is no device filter, availability for a given country means that the QoS profile may be available to some devices connected to the listed networks in that country (or to the API provider’s default network if none are listed). However, this does not imply that the profile is available to all devices, or that a particular device will be able to use the profile across all listed countries or networks. In particular, the response does not provide enough information to determine availability for roaming for specific devices; consumers should query the API with a specific device identifier to get definitive availability. + - If this field is not present in the QoS profile, no assumption can be made about the availability of the profile in any given country or for any given network + allOf: + - $ref: "#/components/schemas/Availability" + targetMinUpstreamRate: + description: | + This is the target minimum upload speed for the QoS profile. + It represents the minimum rate that the network attempts to deliver. + Please note that this is a target value—the network might not always be able to provide this rate under all conditions. + It helps ensure that applications like video calls or live streaming perform consistently. + allOf: + - $ref: "#/components/schemas/Rate" + maxUpstreamRate: + description: | + The maximum best effort data + allOf: + - $ref: "#/components/schemas/Rate" + maxUpstreamBurstRate: + description: | + When defined, this is the maximum upstream burst rate for the QoS profile, that will enable + the network to burst data at a higher rate than the maxUpstreamRate for a period of time. + allOf: + - $ref: "#/components/schemas/Rate" + targetMinDownstreamRate: + description: | + This is the target minimum download speed for the QoS profile. + It represents the minimum rate that the network attempts to deliver. + Please note that this is a target value—the network might not always be able to provide this rate under all conditions. + It helps ensure that applications like video calls or live streaming perform consistently. + allOf: + - $ref: "#/components/schemas/Rate" + maxDownstreamRate: + description: | + The maximum best effort rate + allOf: + - $ref: "#/components/schemas/Rate" + maxDownstreamBurstRate: + description: | + When defined, this is the maximum downstream burst rate for the QoS profile, that will enable + the network to burst data at a higher rate than the maxDownstreamRate for a period of time. + This can result in improved user experience when there is additional network capacity. + For instance, when a user is streaming a video, the network can burst data at a higher rate + to fill the buffer, and then return to the maxUpstreamRate once the buffer is full. + allOf: + - $ref: "#/components/schemas/Rate" + minDuration: + description: | + The shortest time period that this profile can be deployed. + allOf: + - $ref: "#/components/schemas/Duration" + maxDuration: + description: | + The maximum time period that this profile can be deployed. + Overall session duration must not exceed this value. This includes the initial requested duration plus any extensions. + allOf: + - $ref: "#/components/schemas/Duration" + priority: + type: integer + example: 20 + description: | + Priority levels allow efficient resource allocation and ensure optimal performance + for various services in each technology, with the highest priority traffic receiving + preferential treatment. + The lower value the higher priority. + Not all access networks use the same priority range, so this priority will be + scaled to the access network's priority range. + format: int32 + minimum: 1 + maximum: 100 + packetDelayBudget: + description: | + The packet delay budget is the maximum allowable one-way latency between the customer's device + and the gateway from the operator's network to other networks. By limiting the delay, the network + can provide an acceptable level of performance for various services, such as voice calls, + video streaming, and data. + The end-to-end or round trip latency will be about two times this value plus the latency not controlled + by the operator + allOf: + - $ref: "#/components/schemas/Duration" + jitter: + description: | + The jitter requirement aims to limit the maximum variation in round-trip + packet delay for the 99th percentile of traffic, following ITU Y.1540 + standards. It considers only acknowledged packets in a session, which are + packets that receive a confirmation of receipt from the recipient (e.g., + using TCP). This requirement helps maintain consistent latency, essential + for real-time applications such as VoIP, video calls, and gaming. + allOf: + - $ref: "#/components/schemas/Duration" + packetErrorLossRate: + type: integer + description: | + This field specifies the acceptable level of data loss during transmission. + The value is an exponent of 10, so a value of 3 means that up to 10⁻³, or 0.1%, of the + data packets may be lost. This setting is part of a broader system that categorizes + different types of network traffic (like phone calls, video streams, or data transfers) + to ensure they perform reliably on the network. + format: int32 + minimum: 1 + maximum: 10 + example: 3 + l4sQueueType: + type: string + enum: + - non-l4s-queue + - l4s-queue + - mixed-queue + description: | + + **NOTE**: l4sQueueType is experimental and could change or be removed in a future release. + + Specifies the type of queue for L4S (Low Latency, Low Loss, Scalable Throughput) traffic management. L4S is an advanced queue management approach designed to provide ultra-low latency and high throughput for internet traffic, particularly beneficial for interactive applications such as gaming, video conferencing, and virtual reality. + + **Queue Type Descriptions:** + + - **non-l4s-queue**: + A traditional queue used for legacy internet traffic that does not utilize L4S enhancements. It provides standard latency and throughput levels. + + - **l4s-queue**: + A dedicated queue optimized for L4S traffic, delivering ultra-low latency, low loss, and scalable throughput to support latency-sensitive applications. + + - **mixed-queue**: + A shared queue that can handle both L4S and traditional traffic, offering a balance between ultra-low latency for L4S flows and compatibility with non-L4S flows. + + externalDocs: + description: For more details, refer to the L4S standard. + url: https://datatracker.ietf.org/doc/rfc9330/ + serviceClass: + type: string + description: | + + **NOTE**: serviceClass is experimental and could change or be removed in a future release. + + The name of a Service Class, representing a QoS Profile designed to provide optimized behavior for a specific application type. While DSCP values are commonly associated with Service Classes, their use may vary across network segments and may not be applied throughout the entire end-to-end QoS session. This aligns with the serviceClass concept used in HomeDevicesQoQ for consistent terminology. + + Service classes define specific QoS behaviors that map to DSCP (Differentiated Services Code Point) values or Microsoft QoS traffic types. + + The supported mappings are: + 1. Values aligned with the [RFC4594](https://datatracker.ietf.org/doc/html/rfc4594) guidelines for differentiated traffic classes. + 2. Microsoft [QOS_TRAFFIC_TYPE](https://learn.microsoft.com/en-us/windows/win32/api/qos2/ne-qos2-qos_traffic_type) values for Windows developers. + + **Supported Service Classes**: + + | Service Class Name | DSCP Name | DSCP value (decimal) | DCSP value (binary) | Microsoft Value | Application Examples | + |-----------------------|-----------|----------------------|---------------------|-----------------|----------------------------------------------------------------------| + | Microsoft Voice | CS7 | 56 | 111000 | 4,5 | Microsoft QOSTrafficTypeVoice and QOSTrafficTypeControl | + | Microsoft Audio/Video | CS5 | 40 | 101000 | 2,3 | Microsoft QOSTrafficTypeExcellentEffort and QOSTrafficTypeAudioVideo | + | Real-Time Interactive | CS4 | 32 | 100000 | | Video conferencing and Interactive gaming | + | Multimedia Streaming | AF31 | 26 | 011010 | | Streaming video and audio on demand | + | Broadcast Video | CS3 | 24 | 011000 | | Broadcast TV & live events | + | Low-Latency Data | AF21 | 18 | 010010 | | Client/server transactions Web-based ordering | + | High-Throughput Data | AF11 | 10 | 001010 | | Store and forward applications | + | Low-Priority Data | CS1 | 8 | 001000 | 1 | Any flow that has no BW assurance - also: | + | | | | | | Microsoft QOSTrafficTypeBackground | + | Standard | DF(CS0) | 0 | 000000 | 0 | Undifferentiated applications - also: | + | | | | | | Microsoft QOSTrafficTypeBestEffort | + enum: + - microsoft_voice # Microsoft QOSTrafficTypeVoice or Control + - microsoft_audio_video # Microsoft QOSTrafficTypeExcellentEffort or AudioVideo + - real_time_interactive # Video conferencing and interactive gaming + - multimedia_streaming # Streaming video or audio on demand + - broadcast_video # Broadcast TV and live events + - low_latency_data # Client/server transactions Web-based ordering + - high_throughput_data # Store and forward applications + - low_priority_data # Low-priority background traffic + - standard # Default traffic class + example: real_time_interactive + required: + - name + - status + + QosProfileName: + description: | + A unique name for identifying a specific QoS profile. + This may follow different formats depending on the service providers implementation. + Some options addresses: + - A UUID style string + - Support for predefined profile names like `QOS_E`, `QOS_S`, `QOS_M`, and `QOS_L` + - A searchable descriptive name + type: string + example: voice + minLength: 3 + maxLength: 256 + pattern: "^[a-zA-Z0-9_.-]+$" + + Rate: + description: Specification of rate + type: object + properties: + value: + description: Quantity of rate + type: integer + example: 10 + format: int32 + minimum: 0 + maximum: 1024 + unit: + $ref: "#/components/schemas/RateUnitEnum" + + Duration: + description: Specification of duration + type: object + properties: + value: + description: Quantity of duration + type: integer + example: 12 + format: int32 + minimum: 1 + maximum: 2147483647 + unit: + $ref: "#/components/schemas/TimeUnitEnum" + + TimeUnitEnum: + description: Units of time + type: string + enum: + - Days + - Hours + - Minutes + - Seconds + - Milliseconds + - Microseconds + - Nanoseconds + + QosProfileStatusEnum: + description: | + The current status of the QoS Profile + - `ACTIVE`- QoS Profile is available to be used + - `INACTIVE`- QoS Profile is not currently available to be deployed + - `DEPRECATED`- QoS profile is actively being used in a QoS session, but can not be deployed in new QoS sessions + type: string + enum: + - ACTIVE + - INACTIVE + - DEPRECATED + + RateUnitEnum: + description: Units of rate + type: string + enum: + - bps + - kbps + - Mbps + - Gbps + - Tbps + + QosProfileDeviceRequest: + description: | + Request object for QoS Profiles for a given device + type: object + properties: + device: + $ref: "#/components/schemas/Device" + name: + $ref: "#/components/schemas/QosProfileName" + status: + $ref: '#/components/schemas/QosProfileStatusEnum' + + Availability: + description: A list of countries, and optionally networks, for which the API provider makes the profile available + type: array + maxItems: 250 + items: + description: A country, and optionally the networks within that country, for which the API provider makes the QoS profile available + type: object + required: + - countryName + properties: + countryName: + description: The two letter ISO 3166-2 country code for the country in which the QoS profile is available in at least one network + type: string + pattern: ^[A-Z]{2}$ + maxLength: 2 + example: "GB" + networks: + description: A list of networks within the country for which the QoS profile is available from the API provider + type: array + maxItems: 100 + items: + description: The network identifier. For mobile networks, this is the PLMN Identifier (MCC + MNC), which is a 5 or 6 digit integer. + type: string + pattern: '^[0-9]{5,6}$' + maxLength: 6 + example: "23591" + example: ["23591", "23415"] + example: {"countryName": "GB", "networks": ["23591", "23415"]} + example: [{"countryName": "GB", "networks": ["23591", "23415"]}, {"countryName": "DE", "networks": ["26202"]}] + + Device: + $ref: "../common/CAMARA_common.yaml#/components/schemas/Device" + + ErrorInfo: + $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" + + responses: + Generic400: + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" + + Generic401: + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" + + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/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. + + NotFound404: + description: Not found + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/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. + + RetrieveQosProfilesNotFound404: + description: Not found + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/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: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - SERVICE_NOT_APPLICABLE + - UNSUPPORTED_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_UNSUPPORTED_IDENTIFIER: + description: None of the provided identifiers is supported by the implementation + value: + status: 422 + code: UNSUPPORTED_IDENTIFIER + message: The identifier provided is not supported. + 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: + $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" + + examples: + LIST_OF_QOS_PROFILES: + summary: A list of QoS profiles with a single entry + description: Example response when requesting a list of QoS profiles + value: + - name: "voice" + description: "QoS profile for high-quality interactive voice" + status: "ACTIVE" + targetMinUpstreamRate: + value: 100 + unit: "kbps" + targetMinDownstreamRate: + value: 100 + unit: "kbps" + minDuration: + value: 1 + unit: "Days" + maxDuration: + value: 10 + unit: "Days" + priority: 10 + packetDelayBudget: + value: 50 + unit: "Milliseconds" + jitter: + value: 5 + unit: "Milliseconds" + packetErrorLossRate: 3 + l4sQueueType: "non-l4s-queue" diff --git a/code/Test_definitions/qos-profiles-getQosProfile.feature b/code/Test_definitions/qos-profiles-getQosProfile.feature new file mode 100644 index 0000000..aa2cce2 --- /dev/null +++ b/code/Test_definitions/qos-profiles-getQosProfile.feature @@ -0,0 +1,149 @@ +Feature: CAMARA QoS Profiles API, vwip - Operation getQosProfile + # Input to be provided by the implementation to the tester + # + # Implementation indications: + # * apiRoot: API root of the server URL + # + # Testing assets: + # * The name of an existing QoS profile + # + # References to OAS spec schemas refer to schemas specified in qos-profiles.yaml, + # unless the path points to "../common/CAMARA_common.yaml", in which case the + # schema is the one synced from CAMARA Commonalities. + + Background: Common getQosProfile setup + Given an environment at "apiRoot" + And the resource "/qos-profiles/vwip/qos-profiles/{name}" + And the header "Authorization" is set to a valid access token + And the header "x-correlator" complies with the schema at "../common/CAMARA_common.yaml#/components/schemas/XCorrelator" + And the path param "name" is set by default to an existing QoS profile name + + ############################ Happy Path Scenarios ############################################# + + @qos_profiles_getQosProfile_01_generic_success_scenario + Scenario: Common validations for any success scenario + # Valid testing device and default request body compliant with the schema + Given an existing QoS profile + And the path parameter "name" is set to the value for that QoS profile + When the request "getQosProfile" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response body complies with the OAS schema at "/components/schemas/QosProfile" + And the response property "$.name" value is equal to path param "name" + # TBC: Add additional constraints, such as max* properties must be higher than min* equivalent properties, etc + + ############################ Error Scenarios ############################################# + + # Syntax Error scenarios + + @qos_profiles_getQosProfile_400.01_name_does_not_match_regex + Scenario: Path parameter name doesn't match the defined regular expression + Given path parameter "name" does not match the regular expression "^[a-zA-Z0-9_.-]+$" + When the request "getQosProfile" is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + @qos_profiles_getQosProfile_400.02_invalid_name_length + Scenario: Path parameter name has an invalid length + Given path parameter "name" has a length not between 3 and 256 + When the request "getQosProfile" is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + @qos_profiles_getQosProfile_400.03_invalid_x-correlator + Scenario: Invalid x-correlator header + Given the header "x-correlator" does not comply with the schema at "../common/CAMARA_common.yaml#/components/schemas/XCorrelator" + When the request "getQosProfile" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + # Service Error scenarios + + ## Authentication/Authorization errors + + # Generic 401 errors + + @qos_profiles_getQosProfile_401.01_no_authorization_header + Scenario: Error response for no header "Authorization" + Given the header "Authorization" is not sent + When the request "getQosProfile" is sent + Then the response status code is 401 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + # In this case both codes could make sense depending on whether the access token can be refreshed or not + @qos_profiles_getQosProfile_401.02_expired_access_token + Scenario: Error response for expired access token + Given the header "Authorization" is set to an expired access token + When the request "getQosProfile" is sent + Then the response status code is 401 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + @qos_profiles_getQosProfile_401.03_invalid_access_token + Scenario: Error response for invalid access token + Given the header "Authorization" is set to an invalid access token + When the request "getQosProfile" is sent + Then the response status code is 401 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + # Generic 403 errors + + @qos_profiles_getQosProfile_403.01_missing_access_token_scope + Scenario: Missing access token scope + Given the header "Authorization" is set to an access token that does not include scope "qos-profiles:read" + When the request "getQosProfile" is sent + Then the response status code is 403 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 403 + And the response property "$.code" is "PERMISSION_DENIED" + And the response property "$.message" contains a user friendly text + + # Generic 404 errors + + @qos_profiles_getQosProfile_404.01_not_found + Scenario: name of a non-existing QoS profile + Given the path parameter "name" is set to a random string compliant with the pattern + When the request "getQosProfile" is sent + Then the response status code is 404 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 404 + And the response property "$.code" is "NOT_FOUND" + And the response property "$.message" contains a user friendly text + + # Generic 429 errors + + @qos_profiles_getQosProfile_429.01_too_many_requests + # To test this scenario the environment has to be configured to reject requests reaching the threshold limit set. + Scenario: Request is rejected due to threshold policy + Given a valid request for "getQosProfile" + And the header "Authorization" is set to a valid access token + And the threshold of requests has been reached + When the request "getQosProfile" is sent + Then the response status code is 429 + And the response property "$.status" is 429 + And the response property "$.code" is "TOO_MANY_REQUESTS" + And the response property "$.message" contains a user friendly text diff --git a/code/Test_definitions/qos-profiles-retrieveQoSProfiles.feature b/code/Test_definitions/qos-profiles-retrieveQoSProfiles.feature new file mode 100644 index 0000000..218624c --- /dev/null +++ b/code/Test_definitions/qos-profiles-retrieveQoSProfiles.feature @@ -0,0 +1,292 @@ +Feature: CAMARA QoS Profiles API, vwip - Operation retrieveQoSProfiles + # Input to be provided by the implementation to the tester + # + # Implementation indications: + # * apiRoot: API root of the server URL + # * List of device identifier types which are not supported, among: phoneNumber, ipv4Address, ipv6Address. + # For this version, CAMARA does not allow the use of networkAccessIdentifier, so it is considered by default as not supported. + # + # Testing assets: + # * The name of an existing QoS profile + # * If some QoS Profile is restricted for some devices, provide the QoS profile name and device + # * A device object identifying a device commercialized by the implementation for which the service is not applicable, if any + # + # References to OAS spec schemas refer to schemas specified in qos-profiles.yaml, + # unless the path points to "../common/CAMARA_common.yaml", in which case the + # schema is the one synced from CAMARA Commonalities. + + Background: Common retrieveQoSProfiles setup + Given an environment at "apiRoot" + And the resource "/qos-profiles/vwip/retrieve-qos-profiles" + And the header "Content-Type" is set to "application/json" + And the header "Authorization" is set to a valid access token + And the header "x-correlator" complies with the schema at "../common/CAMARA_common.yaml#/components/schemas/XCorrelator" + # Properties not explicitly overwritten in the Scenarios can take any values compliant with the schema + And the request body is set by default to a request body compliant with the schema at "/components/schemas/QosProfileDeviceRequest" + + ############################ Happy Path Scenarios ############################################# + + @qos_profiles_retrieveQoSProfiles_01_generic_success_scenario + Scenario: Common validations for any success scenario + # Valid testing device and default request body compliant with the schema + Given a request body compliant with the schema at "/components/schemas/QosProfileDeviceRequest" + When the request "retrieveQoSProfiles" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And each item of the response array, if any, complies with the OAS schema at "/components/schemas/QosProfile" + # TBC: Add additional constraints, such as max* properties must be higher than min* equivalent properties, etc + + @qos_profiles_retrieveQoSProfiles_02_filter_by_name_only + Scenario: Retrieve QoS profiles only by name + Given the request body property "$.name" is set to an existing QoS profile name + And the request body properties "$.device" and "$.status" are not included + When the request "retrieveQoSProfiles" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response array has only one item which complies with the OAS schema at "/components/schemas/QosProfile" + And the response property "$[0].name" value is equal to the request body property "$.name" + + @qos_profiles_retrieveQoSProfiles_03_filter_by_status_only + Scenario Outline: Retrieve QoS profiles only by status + Given the request body property "$.status" is set to the value + And the request body properties "$.device" and "$.name" are not included + When the request "retrieveQoSProfiles" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And each item of the response array, if any, complies with the OAS schema at "/components/schemas/QosProfile" + And each item of the response array, if any, has property "$[*].status" equal to + + Examples: + | status | + | ACTIVE | + | INACTIVE | + | DEPRECATED | + + @qos_profiles_retrieveQoSProfiles_04_return_restricted_profiles + Scenario: Return QoS Profiles restricted to certain devices + Given that implementation has QoS Profiles restricted to certain devices + And a device suitable for the restricted QoS Profiles is provided in the request body or identified by the access token + And the request body properties "$.name" and "$.status" are not included + When the request "retrieveQoSProfiles" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And each item of the response array complies with the OAS schema at "/components/schemas/QosProfile" + And the restricted QoS Profiles are returned in the response + + @qos_profiles_retrieveQoSProfiles_05_not_return_restricted_profiles + Scenario: Do not return restricted QoS Profiles restricted to certain devices + Given that implementation has QoS Profiles restricted to certain devices + And no device is provided in the request body or identified by the access token + And the request body properties "$.name" and "$.status" are not included + When the request "retrieveQoSProfiles" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And each item of the response array complies with the OAS schema at "/components/schemas/QosProfile" + And no restricted QoS Profile is included in the response + + @qos_profiles_retrieveQoSProfiles_06_device_qos_profiles_not_found + Scenario: Device has no QoS profiles associated + Given a device for which the service is not applicable, provided in the request body or identified by the access token + When the request "retrieveQoSProfiles" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response body is [] + + ############################ Error Scenarios ############################################# + + # Error scenarios for management of input parameter device (C01) + + @qos_profiles_retrieveQoSProfiles_C01.01_device_empty + Scenario: The device value is an empty object + Given the header "Authorization" is set to a valid access token which does not identify a single device + And the request body property "$.device" is set to: {} + When the HTTP "POST" request is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + @qos_profiles_retrieveQoSProfiles_C01.02_device_identifiers_not_schema_compliant + Scenario Outline: Some device identifier value does not comply with the schema + Given the header "Authorization" is set to a valid access token which does not identify a single device + And the request body property "" does not comply with the OAS schema at "" + When the HTTP "POST" request is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + Examples: + | device_identifier | oas_spec_schema | + | $.device.phoneNumber | ../common/CAMARA_common.yaml#/components/schemas/PhoneNumber | + | $.device.ipv4Address | ../common/CAMARA_common.yaml#/components/schemas/DeviceIpv4Address | + | $.device.ipv6Address | ../common/CAMARA_common.yaml#/components/schemas/DeviceIpv6Address | + | $.device.networkAccessIdentifier | ../common/CAMARA_common.yaml#/components/schemas/NetworkAccessIdentifier | + + # This scenario may happen e.g. with 2-legged access tokens, which do not identify a single device. + @qos_profiles_retrieveQoSProfiles_C01.03_device_not_found + Scenario: Some identifier cannot be matched to a device + Given the header "Authorization" is set to a valid access token which does not identify a single device + And the request body property "$.device" is compliant with the schema but does not identify a valid device + When the HTTP "POST" request is sent + Then the response status code is 404 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 404 + And the response property "$.code" is "IDENTIFIER_NOT_FOUND" + And the response property "$.message" contains a user friendly text + + @qos_profiles_retrieveQoSProfiles_C01.04_unnecessary_device + Scenario: Device not to be included when it can be deduced from the access token + Given the header "Authorization" is set to a valid access token identifying a device + And the request body property "$.device" is set to a valid device + When the HTTP "POST" request is sent + Then the response status code is 422 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 422 + And the response property "$.code" is "UNNECESSARY_IDENTIFIER" + And the response property "$.message" contains a user-friendly text + + @qos_profiles_retrieveQoSProfiles_C01.06_unsupported_device + Scenario: None of the provided device identifiers is supported by the implementation + Given that some types of device identifiers are not supported by the implementation + And the header "Authorization" is set to a valid access token which does not identify a single device + And the request body property "$.device" only includes device identifiers not supported by the implementation + When the HTTP "POST" request is sent + Then the response status code is 422 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 422 + And the response property "$.code" is "UNSUPPORTED_IDENTIFIER" + And the response property "$.message" contains a user-friendly text + + # When the service is only offered to certain types of devices or subscriptions, e.g. IoT, B2C, etc. + @qos_profiles_retrieveQoSProfiles_C01.07_device_not_supported + Scenario: Service not available for the device + Given that the service is not available for all devices commercialized by the operator + And a valid device, identified by the token or provided in the request body, for which the service is not applicable + When the HTTP "POST" request is sent + Then the response status code is 422 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 422 + And the response property "$.code" is "SERVICE_NOT_APPLICABLE" + And the response property "$.message" contains a user-friendly text + + # Syntax Error scenarios + + @qos_profiles_retrieveQoSProfiles_400.01_schema_not_compliant + Scenario: Invalid Argument. Generic Syntax Exception + Given the request body is set to any value which is not compliant with the schema at "/components/schemas/QosProfileDeviceRequest" + When the request "retrieveQoSProfiles" is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + @qos_profiles_retrieveQoSProfiles_400.02_no_request_body + Scenario: Missing request body + Given the request body is not included + When the request "retrieveQoSProfiles" is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + # Scenario "empty_request_body" ({} => 400) does not apply to this operation: + # QosProfileDeviceRequest has no required properties, so an empty object is a + # valid request returning all profiles (see scenario 05_not_return_restricted_profiles) + + @qos_profiles_retrieveQoSProfiles_400.03_invalid_x-correlator + Scenario: Invalid x-correlator header + Given the header "x-correlator" does not comply with the schema at "../common/CAMARA_common.yaml#/components/schemas/XCorrelator" + When the request "retrieveQoSProfiles" is sent + Then the response status code is 400 + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text + + # Service Error scenarios + + ## Authentication/Authorization errors + + # Generic 401 errors + + @qos_profiles_retrieveQoSProfiles_401.01_no_authorization_header + Scenario: Error response for no header "Authorization" + Given the header "Authorization" is not sent + And the request body is set to a valid request body + When the request "retrieveQoSProfiles" is sent + Then the response status code is 401 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + # In this case both codes could make sense depending on whether the access token can be refreshed or not + @qos_profiles_retrieveQoSProfiles_401.02_expired_access_token + Scenario: Error response for expired access token + Given the header "Authorization" is set to an expired access token + And the request body is set to a valid request body + When the request "retrieveQoSProfiles" is sent + Then the response status code is 401 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + @qos_profiles_retrieveQoSProfiles_401.03_invalid_access_token + Scenario: Error response for invalid access token + Given the header "Authorization" is set to an invalid access token + And the request body is set to a valid request body + When the request "retrieveQoSProfiles" is sent + Then the response status code is 401 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 401 + And the response property "$.code" is "UNAUTHENTICATED" + And the response property "$.message" contains a user friendly text + + # Generic 403 errors + + @qos_profiles_retrieveQoSProfiles_403.01_missing_access_token_scope + Scenario: Missing access token scope + Given the header "Authorization" is set to an access token that does not include scope "qos-profiles:read" + When the request "retrieveQoSProfiles" is sent + Then the response status code is 403 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 403 + And the response property "$.code" is "PERMISSION_DENIED" + And the response property "$.message" contains a user friendly text + + # Generic 429 errors + + @qos_profiles_retrieveQoSProfiles_429.01_too_many_requests + # To test this scenario the environment has to be configured to reject requests reaching the threshold limit set. + Scenario: Request is rejected due to threshold policy + Given a valid request for "retrieveQoSProfiles" + And the header "Authorization" is set to a valid access token + And the threshold of requests has been reached + When the request "retrieveQoSProfiles" is sent + Then the response status code is 429 + And the response property "$.status" is 429 + And the response property "$.code" is "TOO_MANY_REQUESTS" + And the response property "$.message" contains a user friendly text