From f91fb57651568df014c3b52d5110918952dc9360 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 5 Jun 2024 19:16:54 +0200 Subject: [PATCH 01/16] Create qod-provision.yaml First draft of QoD Provision API --- code/API_definitions/qod-provision.yaml | 970 ++++++++++++++++++++++++ 1 file changed, 970 insertions(+) create mode 100644 code/API_definitions/qod-provision.yaml diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml new file mode 100644 index 0000000000..40081e4c7f --- /dev/null +++ b/code/API_definitions/qod-provision.yaml @@ -0,0 +1,970 @@ +openapi: 3.0.3 +info: + title: QoD Provision API + description: | + The Quality-On-Demand (QoD) Provision API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device or application flows, indefinitely. + + This API sets up the configuration in the network so the requested QoS profile is applied to the specified device or application flows, at any time while the provision is available. The device or application traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provision is revoked. + + # Relevant terms and definitions + + * **QoS profiles and QoS profile labels**: + Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). + + * **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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provision request is accepted, the device may get different IP addresses, but the provision will still apply to the device that was identified during the request process. + + * **Identifier for the application server**: + IPv4 and/or IPv6 address of the application server (application backend). If not specified, the default value is all possible IP addresses, that is `0.0.0.0/0` in IPv4 notation, or `::/0` in IPv6 notation. + + * **App-Flow (between the application client and application server)**: + The precise application data flow the developer wants to prioritize and/or have stable latency or throughput for. This flow is in the current API version determined by the identifiers used for the device and the application server. And it can be further elaborated with details such as ports or port-ranges. Future version of the API might allow more detailed flow identification features. + + - If the application server is not specified, the QoS profile will apply to all flows between the device and the network. + + * **Notification URL and token**: + Developers may provide a callback URL on which notifications about all status change events (eg. provision termination) can be received from the service provider. This is an optional parameter. + + # Resources and Operations overview + The API defines four operations: + + - An operation to setup a new QoD provision for a given device. + - An operation to get the information about a specific QoD provision, identified by its `provisionId`. + - An operation to get all the QoD provisions for a given device. + - An operation to terminate a QoD provision, identified by its `provisionId`. + + + ### Authorization and authentication + + CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. + + It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. + + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip +externalDocs: + description: Product documentation at Camara + url: https://github.com/camaraproject/ +servers: + - url: "{apiRoot}/qod-provision/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: QoD Provision + description: Manage the provision of QoD +paths: + /provisions: + post: + tags: + - QoD Provision + summary: Sets a new QoD provision + description: | + Triggers a new provision in the operator to assign certain QoS Profile to certain device or application flows. + + - If the provision is completed synchronously, the response will be 201 with `status` = `AVAILABLE`. + - If the provision request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. + - If the operator determines synchronously that the provision request cannot be fulfilled, the response will be 201 with `status` = `UNAVAILABLE`. + + - If the request includes a webhook, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. + + NOTE: When the provision status becomes `UNAVAILABLE`, the QoD provision resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. + This behavior allows clients which are not receiving notification events but are polling, to get the provision status information. Before a client can attempt to create a new QoD provision for the same device and flow, they must release the provision resources with an explicit `delete` operation if not yet automatically deleted. + + operationId: createProvision + parameters: + - $ref: "#/components/parameters/x-correlator" + requestBody: + description: Parameters to create a new provision + content: + application/json: + schema: + $ref: "#/components/schemas/CreateProvision" + required: true + callbacks: + notifications: + "{$request.body#/webhook/notificationUrl}": + post: + summary: Provision notifications callback + description: | + Important: this endpoint is to be implemented by the API consumer. + The QoD server will call this endpoint whenever any QoD provision change related event occurs. + Currently only `PROVISION_STATUS_CHANGED` event is defined. + operationId: postProvisionNotification + parameters: + - $ref: "#/components/parameters/x-correlator" + requestBody: + required: true + content: + application/cloudevents+json: + schema: + $ref: "#/components/schemas/CloudEvent" + examples: + PROVISION_STATUS_CHANGED_EXAMPLE: + $ref: "#/components/examples/PROVISION_STATUS_CHANGED_EXAMPLE" + 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" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - {} + - notificationsBearerAuth: [] + responses: + "201": + description: Provision created + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ProvisionInfo" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/DeviceNotFound404" + "409": + $ref: "#/components/responses/ProvisionConflict409" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - openId: + - "qod-provision:provisions:create" + + /provisions/{provisionId}: + get: + tags: + - QoD Provision + summary: Get QoD provision information + description: Querying for QoD provisions resource information details + operationId: getProvision + parameters: + - $ref: "#/components/parameters/provisionId" + - $ref: "#/components/parameters/x-correlator" + responses: + "200": + description: Contains information about active provision + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ProvisionInfo" + examples: + PROVISION_AVAILABLE: + $ref: "#/components/examples/PROVISION_AVAILABLE" + PROVISION_UNAVAILABLE: + $ref: "#/components/examples/PROVISION_UNAVAILABLE" + "400": + $ref: "#/components/responses/Generic400" + "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" + security: + - openId: + - "qod-provision:provisions:read" + + delete: + tags: + - QoD Provision + summary: Deletes a QoD provision + description: | + Release resources related to QoS provision. + + If the notification callback is provided and the provision status was `AVAILABLE`, the client will receive in addition to the response a `PROVISION_STATUS_CHANGED` event with + - `status` as `UNAVAILABLE` and + - `statusInfo` as `DELETE_REQUESTED` + There will be no notification event if the `status` was already `UNAVAILABLE`. + operationId: deleteProvision + parameters: + - $ref: "#/components/parameters/provisionId" + - $ref: "#/components/parameters/x-correlator" + responses: + "204": + description: Provision deleted + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + "400": + $ref: "#/components/responses/Generic400" + "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" + security: + - openId: + - "qod-provision:provisions:delete" + + /provisions/retrieve: + post: + tags: + - QoD Provision + summary: Gets QoD provisions for a given device + description: | + Retrieves all the QoD provisions for a given device. An implementation may allow multiple provisions for the same device. + operationId: retrieveProvisions + parameters: + - $ref: "#/components/parameters/x-correlator" + requestBody: + description: Parameters to retrieve provisions + content: + application/json: + schema: + $ref: "#/components/schemas/RetrieveProvisions" + required: true + responses: + "200": + description: Provision created. An empty array is returned if no provisions are found. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + type: array + minItems: 0 + items: + $ref: "#/components/schemas/ProvisionInfo" + examples: + RETRIEVE_PROVISIONS: + $ref: "#/components/examples/RETRIEVE_PROVISIONS" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/DeviceNotFound404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - openId: + - "qod-provision:provisions:read" + +components: + securitySchemes: + openId: + description: OpenID Connect authentication + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + notificationsBearerAuth: + description: Bearer authentication for notifications + type: http + scheme: bearer + bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + + parameters: + provisionId: + name: provisionId + in: path + description: Provision ID that was obtained from the createProvision operation + required: true + schema: + $ref: "#/components/schemas/ProvisionId" + + 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: + ProvisionId: + description: Provision Identifier in UUID format + type: string + format: uuid + + BaseProvisionInfo: + description: Common attributes of a QoD provision + type: object + properties: + device: + $ref: "#/components/schemas/Device" + applicationServer: + $ref: "#/components/schemas/ApplicationServer" + devicePorts: + description: The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports + allOf: + - $ref: "#/components/schemas/PortsSpec" + applicationServerPorts: + description: A list of single ports or port ranges on the application server. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address. If `applicationServer` is not specified, then `applicationServerPorts` must not be included. + allOf: + - $ref: "#/components/schemas/PortsSpec" + qosProfile: + $ref: "#/components/schemas/QosProfileName" + webhook: + description: Callback URL on which notifications about all status change events of the provision process (eg. provision termination) can be received + type: object + required: + - notificationUrl + properties: + notificationUrl: + type: string + format: uri + example: "https://application-server.com" + description: Allows asynchronous delivery of provision related events + notificationAuthToken: + type: string + minLength: 20 + maxLength: 256 + example: "c8974e592c2fa383d4a3960714" + description: Authentication token for callback API + required: + - device + - qosProfile + + ProvisionInfo: + description: Provision related information. + allOf: + - $ref: "#/components/schemas/BaseProvisionInfo" + - type: object + properties: + provisionId: + $ref: "#/components/schemas/ProvisionId" + startedAt: + description: Date and time when the provision became "AVAILABLE". Not to be returned when `status` is "REQUESTED". Format must follow RFC 3339 and must indicate time zone (UTC or local). + type: string + format: date-time + example: "2024-06-01T12:00:00Z" + status: + $ref: "#/components/schemas/Status" + statusInfo: + $ref: "#/components/schemas/StatusInfo" + messages: + type: array + items: + $ref: "#/components/schemas/Message" + required: + - provisionId + - status + + CreateProvision: + description: Attributes to request a new QoD provision + allOf: + - $ref: "#/components/schemas/BaseProvisionInfo" + + RetrieveProvisions: + description: Attributes to look for QoD provisions + type: object + properties: + device: + $ref: "#/components/schemas/Device" + required: + - device + + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + + PortsSpec: + description: Specification of several TCP or UDP ports + type: object + minProperties: 1 + properties: + ranges: + description: Range of TCP or UDP ports + type: array + minItems: 1 + items: + type: object + required: + - from + - to + properties: + from: + $ref: "#/components/schemas/Port" + to: + $ref: "#/components/schemas/Port" + ports: + description: Array of TCP or UDP ports + type: array + minItems: 1 + items: + $ref: "#/components/schemas/Port" + example: + ranges: + - from: 5010 + to: 5020 + ports: + - 5060 + - 5070 + + 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 profiles QOS_S, QOS_M, QOS_L, and QOS_E + - A searchable descriptive name + The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). + type: string + example: QCI_1_voice + minLength: 3 + maxLength: 256 + format: string + pattern: "^[a-zA-Z0-9_.-]+$" + + CloudEvent: + description: Event compliant with the CloudEvents specification + required: + - id + - source + - specversion + - type + - time + properties: + id: + description: Identifier of this event, that must be unique in the source context. + type: string + source: + description: Identifies the context in which an event happened in the specific Provider Implementation. + type: string + format: uri-reference + type: + description: The type of the event. + type: string + enum: + - "org.camaraproject.qod-provision.vwip.status-changed" + specversion: + description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) + type: string + enum: + - "1.0" + datacontenttype: + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + type: string + enum: + - "application/json" + data: + description: Event notification details payload, which depends on the event type + type: object + time: + description: | + Timestamp of when the occurrence happened. It must follow RFC 3339 + type: string + format: date-time + discriminator: + propertyName: "type" + mapping: + org.camaraproject.qod-provision.vwip.status-changed: "#/components/schemas/EventStatusChanged" + + EventStatusChanged: + description: Event to notify a QoD provision status change + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + type: object + description: Event details depending on the event type + required: + - provisionId + - qosStatus + properties: + provisionId: + $ref: "#/components/schemas/ProvisionId" + status: + $ref: "#/components/schemas/StatusChanged" + statusInfo: + $ref: "#/components/schemas/StatusInfo" + required: + - data + + StatusInfo: + description: | + Reason for the new `status`. Currently `statusInfo` is only applicable when `status` is `UNAVAILABLE`. + * `NETWORK_TERMINATED` - Network terminated the QoD provision + * `DELETE_REQUESTED`- User requested the deletion of the QoD provision + + type: string + enum: + - NETWORK_TERMINATED + - DELETE_REQUESTED + + Device: + description: | + End-user equipment able to connect to the network. Examples of devices include smartphones or IoT sensors/actuators. + + The developer can choose to provide the below specified device identifiers: + + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + + NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 + + ApplicationServer: + description: | + A server hosting backend applications to deliver some business logic to clients. + + The developer can choose to provide the below specified device identifiers: + + * `ipv4Address` + * `ipv6Address` + + If omitted the default value is all possible IP addresses, that is `0.0.0.0/0` in IPv4 notation, or `::/0` in IPv6 notation. + type: object + properties: + ipv4Address: + $ref: "#/components/schemas/ApplicationServerIpv4Address" + ipv6Address: + $ref: "#/components/schemas/ApplicationServerIpv6Address" + minProperties: 1 + + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@domain.com" + + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + { + "publicAddress": "203.0.113.0", + "publicPort": 59765 + } + + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "203.0.113.0" + + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + + The provision shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts. + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + + ApplicationServerIpv4Address: + type: string + example: "198.51.100.0/24" + description: | + IPv4 address may be specified in form
as: + - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. + - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. + In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. + + ApplicationServerIpv6Address: + type: string + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: | + IPv6 address may be specified in form
as: + - address - The /128 subnet is optional for single addresses: + - 2001:db8:85a3:8d3:1319:8a2e:370:7344 + - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 + - address/mask - an IP v6 number with a mask: + - 2001:db8:85a3:8d3::0/64 + - 2001:db8:85a3:8d3::/64 + + Message: + description: Message with additional information + type: object + properties: + severity: + description: Message severity + type: string + enum: ["INFO", "WARNING"] + description: + description: Detailed message text + type: string + required: + - severity + - description + + Status: + description: | + The current status of the requested QoD provision. The status can be one of the following: + * `REQUESTED` - QoD provision has been requested but is still being processed. + * `AVAILABLE` - The requested QoS profile has been provisioned to the device or application flows, and is active. + * `UNAVAILABLE` - The QoD provision request has been processed but is not active. `statusInfo` may provide additional information about the reason for the unavailability. + enum: + - REQUESTED + - AVAILABLE + - UNAVAILABLE + + StatusChanged: + description: | + The current status of a requested or previously available QoD provision. Applicable values in the event are: + * `AVAILABLE` - The requested QoS profile has been provisioned to the device or application flows, and is active. + * `UNAVAILABLE` - A requested or previously available QoD provision is now unavailable. `statusInfo` may provide additional information about the reason for the unavailability. + type: string + enum: + - AVAILABLE + - UNAVAILABLE + + ErrorInfo: + description: Common schema for errors + type: object + properties: + status: + type: integer + description: HTTP status code returned along with this error response + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + required: + - status + - code + - message + + responses: + Generic400: + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + summary: Generic Invalid Argument + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + summary: Generic Out of Range + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_401_UNAUTHENTICATED: + summary: Generic 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: + summary: Generic Authentication Required + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_403_PERMISSION_DENIED: + summary: Generic Permission Denied + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + summary: Invalid access token context + description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + + Generic404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_404_NOT_FOUND: + summary: Generic Not Found + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: "{{resource}} is not found" + + Generic422: + description: Unprocessable entity + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_UNPROCESSABLE_ENTITY: + summary: Unprocessable entity + description: The request was well-formed but was unable to be processed due to semantic errors or not applicable values. This is the generic error code for 422 responses. + value: + status: 422 + code: UNPROCESSABLE_ENTITY + message: "Value not acceptable: ..." + GENERIC_422_DEVICE_NOT_APPLICABLE: + summary: Service not applicable to the device + description: The provided device is not compatible with the requested operation, according to the service provider rules. + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: "The device is not applicable for the requested operation" + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + summary: Device identifiers mismatch + description: Several device identifiers are provided but do not match the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: "The provided device identifiers do not match the same device" + GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: + summary: None of the provided device identifiers is supported by the implementation + description: Message may list the supported device identifiers + value: + status: 422 + code: UNSUPPORTED_DEVICE_IDENTIFIERS + message: "Supported device supported are: ..." + + Generic500: + description: Internal server error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_500_INTERNAL: + summary: Generic Internal + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: "Internal server error" + + Generic503: + description: Service unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_503_UNAVAILABLE: + summary: Generic Unavailable + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: "Service unavailable" + + DeviceNotFound404: + description: Device not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + ERROR_404_DEVICE_NOT_FOUND: + summary: Some identifier cannot be matched to a device + description: One or more of the provided device identifiers do not match any device + value: + status: 404 + code: DEVICE_NOT_FOUND + message: "No device found for a provided identifier" + + ProvisionConflict409: + description: Provision conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PROVISION_409_CONFLICT: + summary: Provision Conflict + description: The requested provision conflicts with an existing one + value: + status: 409 + code: CONFLICT + message: "There is another active provision for the same device and/or flow" + + examples: + PROVISION_AVAILABLE: + summary: QoD provision status is available + description: The provision has become available + value: + device: + ipv4Address: + publicAddress: 203.0.113.0 + publicPort: 59765 + qosProfile: QOS_L + webhook: + notificationUrl: https://application-server.com + provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + startedAt: 2024-05-12T17:32:01Z + status: AVAILABLE + + PROVISION_UNAVAILABLE: + summary: QoD provision status is unavailable + description: The provision could not be created or is not active anymore + value: + duration: 86400 + device: + phoneNumber: "+123456789" + qosProfile: QOS_L + webhook: + notificationUrl: https://application-server.com + provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + startedAt: 2024-05-12T17:32:01Z + status: UNAVAILABLE + statusInfo: NETWORK_TERMINATED + + PROVISION_STATUS_CHANGED_EXAMPLE: + description: Provision status changed + summary: Cloud event example for QoD provision status change to UNAVAILABLE due to + value: + id: 83a0d986-0866-4f38-b8c0-fc65bfcda452 + source: https://api.example.com/qod-provision/vwip/provisions/123e4567-e89b-12d3-a456-426614174000 + specversion: "1.0" + type: org.camaraproject.qod-provision.vwip.status-changed + time: 2021-12-12T00:00:00Z + data: + provisionId: 123e4567-e89b-12d3-a456-426614174000 + status: UNAVAILABLE + statusInfo: NETWORK_TERMINATED + + RETRIEVE_PROVISIONS: + summary: Provisions for a given device + description: Several provisions may exist for a given device + value: + - device: + phoneNumber: "+123456789" + qosProfile: QOS_L + webhook: + notificationUrl: https://application-server.com + provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + startedAt: 2024-05-12T17:32:01Z + status: AVAILABLE + From 3e3d593b51c1d46b776c06fe74407161ef6d75cf Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 5 Jun 2024 19:57:04 +0200 Subject: [PATCH 02/16] Update qod-provision.yaml Linting complaints --- code/API_definitions/qod-provision.yaml | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 40081e4c7f..4120047634 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -5,14 +5,14 @@ info: The Quality-On-Demand (QoD) Provision API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device or application flows, indefinitely. This API sets up the configuration in the network so the requested QoS profile is applied to the specified device or application flows, at any time while the provision is available. The device or application traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provision is revoked. - + # Relevant terms and definitions - + * **QoS profiles and QoS profile labels**: Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). * **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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provision request is accepted, the device may get different IP addresses, but the provision will still apply to the device that was identified during the request process. + 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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provision request is accepted, the device may get different IP addresses, but the provision will still apply to the device that was identified during the request process. * **Identifier for the application server**: IPv4 and/or IPv6 address of the application server (application backend). If not specified, the default value is all possible IP addresses, that is `0.0.0.0/0` in IPv4 notation, or `::/0` in IPv6 notation. @@ -39,7 +39,7 @@ info: CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. - + termsOfService: http://swagger.io/terms/ contact: email: project-email@sample.com @@ -68,15 +68,15 @@ paths: description: | Triggers a new provision in the operator to assign certain QoS Profile to certain device or application flows. - - If the provision is completed synchronously, the response will be 201 with `status` = `AVAILABLE`. - - If the provision request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. + - If the provision is completed synchronously, the response will be 201 with `status` = `AVAILABLE`. + - If the provision request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. - If the operator determines synchronously that the provision request cannot be fulfilled, the response will be 201 with `status` = `UNAVAILABLE`. - + - If the request includes a webhook, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. NOTE: When the provision status becomes `UNAVAILABLE`, the QoD provision resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. This behavior allows clients which are not receiving notification events but are polling, to get the provision status information. Before a client can attempt to create a new QoD provision for the same device and flow, they must release the provision resources with an explicit `delete` operation if not yet automatically deleted. - + operationId: createProvision parameters: - $ref: "#/components/parameters/x-correlator" @@ -158,7 +158,7 @@ paths: - "qod-provision:provisions:create" /provisions/{provisionId}: - get: + get: tags: - QoD Provision summary: Get QoD provision information @@ -815,7 +815,7 @@ components: value: status: 422 code: UNPROCESSABLE_ENTITY - message: "Value not acceptable: ..." + message: "Value not acceptable: ..." GENERIC_422_DEVICE_NOT_APPLICABLE: summary: Service not applicable to the device description: The provided device is not compatible with the requested operation, according to the service provider rules. @@ -909,7 +909,7 @@ components: status: 409 code: CONFLICT message: "There is another active provision for the same device and/or flow" - + examples: PROVISION_AVAILABLE: summary: QoD provision status is available @@ -943,7 +943,7 @@ components: PROVISION_STATUS_CHANGED_EXAMPLE: description: Provision status changed - summary: Cloud event example for QoD provision status change to UNAVAILABLE due to + summary: Cloud event example for QoD provision status change to UNAVAILABLE due to NETWORK_TERMINATED value: id: 83a0d986-0866-4f38-b8c0-fc65bfcda452 source: https://api.example.com/qod-provision/vwip/provisions/123e4567-e89b-12d3-a456-426614174000 @@ -967,4 +967,3 @@ components: provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 startedAt: 2024-05-12T17:32:01Z status: AVAILABLE - From 807e7a7230a7f042896699bcef72cc496eb507bb Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 5 Jun 2024 19:59:17 +0200 Subject: [PATCH 03/16] Update qod-provision.yaml More linting fixes --- code/API_definitions/qod-provision.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 4120047634..160eeb12cc 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -155,7 +155,7 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:create" + - "qod-provision:provisions:create" /provisions/{provisionId}: get: @@ -196,7 +196,7 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:read" + - "qod-provision:provisions:read" delete: tags: @@ -233,7 +233,7 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:delete" + - "qod-provision:provisions:delete" /provisions/retrieve: post: @@ -284,7 +284,7 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:read" + - "qod-provision:provisions:read" components: securitySchemes: From 0052d6a1aa9401753e62ec252e9c7563b225b4bf Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Wed, 5 Jun 2024 20:02:11 +0200 Subject: [PATCH 04/16] Update qod-provision.yaml More trailing spaces --- code/API_definitions/qod-provision.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 160eeb12cc..6232653a6c 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -5,9 +5,9 @@ info: The Quality-On-Demand (QoD) Provision API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device or application flows, indefinitely. This API sets up the configuration in the network so the requested QoS profile is applied to the specified device or application flows, at any time while the provision is available. The device or application traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provision is revoked. - + # Relevant terms and definitions - + * **QoS profiles and QoS profile labels**: Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). @@ -39,7 +39,7 @@ info: CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. - + termsOfService: http://swagger.io/terms/ contact: email: project-email@sample.com @@ -158,7 +158,7 @@ paths: - "qod-provision:provisions:create" /provisions/{provisionId}: - get: + get: tags: - QoD Provision summary: Get QoD provision information From d7ebffb97244aa9d33eeb261727a63959bdd1500 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Tue, 18 Jun 2024 17:47:31 +0200 Subject: [PATCH 05/16] Changes after early feedback * Removed support for serveral appliocation flows per device. In this version provision is per device and affects all its traffic. Proiperties `applicationServer`, `devicePorts` and `applicationPorts` are deleted. * Also `messages` in the response is deleted as it had not a requirement * Added support for async deletion process (202 response) in addition to the sync 204 --- code/API_definitions/qod-provision.yaml | 140 ++++-------------------- 1 file changed, 19 insertions(+), 121 deletions(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 6232653a6c..812c54f99d 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -2,9 +2,9 @@ openapi: 3.0.3 info: title: QoD Provision API description: | - The Quality-On-Demand (QoD) Provision API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device or application flows, indefinitely. + The Quality-On-Demand (QoD) Provision API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device, indefinitely. - This API sets up the configuration in the network so the requested QoS profile is applied to the specified device or application flows, at any time while the provision is available. The device or application traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provision is revoked. + This API sets up the configuration in the network so the requested QoS profile is applied to an specified device, at any time while the provision is available. The device traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provision is revoked. # Relevant terms and definitions @@ -12,15 +12,7 @@ info: Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). * **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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provision request is accepted, the device may get different IP addresses, but the provision will still apply to the device that was identified during the request process. - - * **Identifier for the application server**: - IPv4 and/or IPv6 address of the application server (application backend). If not specified, the default value is all possible IP addresses, that is `0.0.0.0/0` in IPv4 notation, or `::/0` in IPv6 notation. - - * **App-Flow (between the application client and application server)**: - The precise application data flow the developer wants to prioritize and/or have stable latency or throughput for. This flow is in the current API version determined by the identifiers used for the device and the application server. And it can be further elaborated with details such as ports or port-ranges. Future version of the API might allow more detailed flow identification features. - - - If the application server is not specified, the QoS profile will apply to all flows between the device and the network. + 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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provision request is accepted, the device may get different IP addresses, but the provision will still apply to the device that was identified during the request process.between the device and the network. * **Notification URL and token**: Developers may provide a callback URL on which notifications about all status change events (eg. provision termination) can be received from the service provider. This is an optional parameter. @@ -66,7 +58,7 @@ paths: - QoD Provision summary: Sets a new QoD provision description: | - Triggers a new provision in the operator to assign certain QoS Profile to certain device or application flows. + Triggers a new provision in the operator to assign certain QoS Profile to certain device. - If the provision is completed synchronously, the response will be 201 with `status` = `AVAILABLE`. - If the provision request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. @@ -75,7 +67,7 @@ paths: - If the request includes a webhook, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. NOTE: When the provision status becomes `UNAVAILABLE`, the QoD provision resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. - This behavior allows clients which are not receiving notification events but are polling, to get the provision status information. Before a client can attempt to create a new QoD provision for the same device and flow, they must release the provision resources with an explicit `delete` operation if not yet automatically deleted. + This behavior allows clients which are not receiving notification events but are polling, to get the provision status information. Before a client can attempt to create a new QoD provision for the same device, they must release the provision resources with an explicit `delete` operation if not yet automatically deleted. operationId: createProvision parameters: @@ -205,7 +197,7 @@ paths: description: | Release resources related to QoS provision. - If the notification callback is provided and the provision status was `AVAILABLE`, the client will receive in addition to the response a `PROVISION_STATUS_CHANGED` event with + If the notification callback is provided and the provision status was `AVAILABLE`, when the deletion is completed, the client will receive in addition to the response a `PROVISION_STATUS_CHANGED` event with - `status` as `UNAVAILABLE` and - `statusInfo` as `DELETE_REQUESTED` There will be no notification event if the `status` was already `UNAVAILABLE`. @@ -219,6 +211,15 @@ paths: headers: x-correlator: $ref: "#/components/headers/x-correlator" + "202": + description: Deletion request accepted to be processed. It applies for an async deletion process. `status` in the response will be `AVAILABLE` with `statusInfo` set to `DELETE_REQUESTED`. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ProvisionInfo" "400": $ref: "#/components/responses/Generic400" "401": @@ -332,16 +333,6 @@ components: properties: device: $ref: "#/components/schemas/Device" - applicationServer: - $ref: "#/components/schemas/ApplicationServer" - devicePorts: - description: The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports - allOf: - - $ref: "#/components/schemas/PortsSpec" - applicationServerPorts: - description: A list of single ports or port ranges on the application server. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address. If `applicationServer` is not specified, then `applicationServerPorts` must not be included. - allOf: - - $ref: "#/components/schemas/PortsSpec" qosProfile: $ref: "#/components/schemas/QosProfileName" webhook: @@ -382,10 +373,6 @@ components: $ref: "#/components/schemas/Status" statusInfo: $ref: "#/components/schemas/StatusInfo" - messages: - type: array - items: - $ref: "#/components/schemas/Message" required: - provisionId - status @@ -410,39 +397,6 @@ components: minimum: 0 maximum: 65535 - PortsSpec: - description: Specification of several TCP or UDP ports - type: object - minProperties: 1 - properties: - ranges: - description: Range of TCP or UDP ports - type: array - minItems: 1 - items: - type: object - required: - - from - - to - properties: - from: - $ref: "#/components/schemas/Port" - to: - $ref: "#/components/schemas/Port" - ports: - description: Array of TCP or UDP ports - type: array - minItems: 1 - items: - $ref: "#/components/schemas/Port" - example: - ranges: - - from: 5010 - to: 5020 - ports: - - 5060 - - 5070 - QosProfileName: description: | A unique name for identifying a specific QoS profile. @@ -527,7 +481,7 @@ components: StatusInfo: description: | - Reason for the new `status`. Currently `statusInfo` is only applicable when `status` is `UNAVAILABLE`. + Reason for the new `status`: * `NETWORK_TERMINATED` - Network terminated the QoD provision * `DELETE_REQUESTED`- User requested the deletion of the QoD provision @@ -560,24 +514,6 @@ components: $ref: "#/components/schemas/DeviceIpv6Address" minProperties: 1 - ApplicationServer: - description: | - A server hosting backend applications to deliver some business logic to clients. - - The developer can choose to provide the below specified device identifiers: - - * `ipv4Address` - * `ipv6Address` - - If omitted the default value is all possible IP addresses, that is `0.0.0.0/0` in IPv4 notation, or `::/0` in IPv6 notation. - type: object - properties: - ipv4Address: - $ref: "#/components/schemas/ApplicationServerIpv4Address" - ipv6Address: - $ref: "#/components/schemas/ApplicationServerIpv6Address" - minProperties: 1 - NetworkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string @@ -624,53 +560,15 @@ components: DeviceIpv6Address: description: | The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). - - The provision shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts. type: string format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - ApplicationServerIpv4Address: - type: string - example: "198.51.100.0/24" - description: | - IPv4 address may be specified in form
as: - - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. - In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. - - ApplicationServerIpv6Address: - type: string - example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" - description: | - IPv6 address may be specified in form
as: - - address - The /128 subnet is optional for single addresses: - - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - - address/mask - an IP v6 number with a mask: - - 2001:db8:85a3:8d3::0/64 - - 2001:db8:85a3:8d3::/64 - - Message: - description: Message with additional information - type: object - properties: - severity: - description: Message severity - type: string - enum: ["INFO", "WARNING"] - description: - description: Detailed message text - type: string - required: - - severity - - description - Status: description: | The current status of the requested QoD provision. The status can be one of the following: * `REQUESTED` - QoD provision has been requested but is still being processed. - * `AVAILABLE` - The requested QoS profile has been provisioned to the device or application flows, and is active. + * `AVAILABLE` - The requested QoS profile has been provisioned to the device, and is active. * `UNAVAILABLE` - The QoD provision request has been processed but is not active. `statusInfo` may provide additional information about the reason for the unavailability. enum: - REQUESTED @@ -680,7 +578,7 @@ components: StatusChanged: description: | The current status of a requested or previously available QoD provision. Applicable values in the event are: - * `AVAILABLE` - The requested QoS profile has been provisioned to the device or application flows, and is active. + * `AVAILABLE` - The requested QoS profile has been provisioned to the device, and is active. * `UNAVAILABLE` - A requested or previously available QoD provision is now unavailable. `statusInfo` may provide additional information about the reason for the unavailability. type: string enum: @@ -908,7 +806,7 @@ components: value: status: 409 code: CONFLICT - message: "There is another active provision for the same device and/or flow" + message: "There is another active provision for the same device" examples: PROVISION_AVAILABLE: From 01fa7cbcaa13575af0225ba93cb3b9eba4b29bdb Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Tue, 18 Jun 2024 18:12:16 +0200 Subject: [PATCH 06/16] RetrieveProvision only returns one provision per device Operation adapted to last changes --- code/API_definitions/qod-provision.yaml | 75 ++++++++++++++----------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 812c54f99d..4023fd5251 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -22,7 +22,7 @@ info: - An operation to setup a new QoD provision for a given device. - An operation to get the information about a specific QoD provision, identified by its `provisionId`. - - An operation to get all the QoD provisions for a given device. + - An operation to get the QoD provisions for a given device. - An operation to terminate a QoD provision, identified by its `provisionId`. @@ -161,7 +161,7 @@ paths: - $ref: "#/components/parameters/x-correlator" responses: "200": - description: Contains information about active provision + description: Returns information about an active provision headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -240,35 +240,32 @@ paths: post: tags: - QoD Provision - summary: Gets QoD provisions for a given device + summary: Gets the QoD provision for a given device description: | - Retrieves all the QoD provisions for a given device. An implementation may allow multiple provisions for the same device. - operationId: retrieveProvisions + Retrieves the QoD provision for a given device. + operationId: retrieveProvision parameters: - $ref: "#/components/parameters/x-correlator" requestBody: - description: Parameters to retrieve provisions + description: Parameters to retrieve a provision by device content: application/json: schema: - $ref: "#/components/schemas/RetrieveProvisions" + $ref: "#/components/schemas/RetrieveProvision" required: true responses: "200": - description: Provision created. An empty array is returned if no provisions are found. + description: Returns information about an active provision for the device. If no provision is found for the device, an error response 404 is returned with code "PROVISION_NOT_FOUND". headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: - type: array - minItems: 0 - items: - $ref: "#/components/schemas/ProvisionInfo" + $ref: "#/components/schemas/ProvisionInfo" examples: - RETRIEVE_PROVISIONS: - $ref: "#/components/examples/RETRIEVE_PROVISIONS" + PROVISION_AVAILABLE: + $ref: "#/components/examples/PROVISION_AVAILABLE" "400": $ref: "#/components/responses/Generic400" "401": @@ -276,7 +273,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/DeviceNotFound404" + $ref: "#/components/responses/RetrieveProvision404" "422": $ref: "#/components/responses/Generic422" "500": @@ -382,7 +379,7 @@ components: allOf: - $ref: "#/components/schemas/BaseProvisionInfo" - RetrieveProvisions: + RetrieveProvision: description: Attributes to look for QoD provisions type: object properties: @@ -790,6 +787,31 @@ components: code: DEVICE_NOT_FOUND message: "No device found for a provided identifier" + RetrieveProvision404: + description: Device or provision not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + ERROR_404_DEVICE_NOT_FOUND: + summary: Some identifier cannot be matched to a device + description: One or more of the provided device identifiers do not match any device + value: + status: 404 + code: DEVICE_NOT_FOUND + message: "No device found for a provided identifier" + ERROR_404_PROVISION_NOT_FOUND: + summary: No provision found for the device + description: The provided device is valid but does not have any provision + value: + status: 404 + code: PROVISION_NOT_FOUND + message: "No provision found for the provided device" + ProvisionConflict409: description: Provision conflict headers: @@ -814,9 +836,7 @@ components: description: The provision has become available value: device: - ipv4Address: - publicAddress: 203.0.113.0 - publicPort: 59765 + phoneNumber: "+123456789" qosProfile: QOS_L webhook: notificationUrl: https://application-server.com @@ -830,7 +850,9 @@ components: value: duration: 86400 device: - phoneNumber: "+123456789" + ipv4Address: + publicAddress: 203.0.113.0 + publicPort: 59765 qosProfile: QOS_L webhook: notificationUrl: https://application-server.com @@ -852,16 +874,3 @@ components: provisionId: 123e4567-e89b-12d3-a456-426614174000 status: UNAVAILABLE statusInfo: NETWORK_TERMINATED - - RETRIEVE_PROVISIONS: - summary: Provisions for a given device - description: Several provisions may exist for a given device - value: - - device: - phoneNumber: "+123456789" - qosProfile: QOS_L - webhook: - notificationUrl: https://application-server.com - provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - startedAt: 2024-05-12T17:32:01Z - status: AVAILABLE From 1f939f193d495a1e9529ad336d5694cd59f8aee2 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Tue, 18 Jun 2024 18:14:49 +0200 Subject: [PATCH 07/16] Trailing spaces fix --- code/API_definitions/qod-provision.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 4023fd5251..092eda35a4 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -788,7 +788,7 @@ components: message: "No device found for a provided identifier" RetrieveProvision404: - description: Device or provision not found + description: Device or provision not found headers: x-correlator: $ref: "#/components/headers/x-correlator" From b79329db2e9839a54664cd51b96a16a561667dd8 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Fri, 12 Jul 2024 13:49:44 +0200 Subject: [PATCH 08/16] Update qod-provision.yaml - Replaced "provision" for "provisioning" - Path for /provisions changed to /device-qos - Fix that get operations do not only return active provision --- code/API_definitions/qod-provision.yaml | 262 ++++++++++++------------ 1 file changed, 131 insertions(+), 131 deletions(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 092eda35a4..0595f476f5 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -1,10 +1,10 @@ openapi: 3.0.3 info: - title: QoD Provision API + title: QoD Provisioning API description: | - The Quality-On-Demand (QoD) Provision API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device, indefinitely. + The Quality-On-Demand (QoD) Provisioning API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device, indefinitely. - This API sets up the configuration in the network so the requested QoS profile is applied to an specified device, at any time while the provision is available. The device traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provision is revoked. + This API sets up the configuration in the network so the requested QoS profile is applied to an specified device, at any time while the provisioning is available. The device traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provisioning is revoked. # Relevant terms and definitions @@ -12,18 +12,18 @@ info: Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). * **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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provision request is accepted, the device may get different IP addresses, but the provision will still apply to the device that was identified during the request process.between the device and the network. + 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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provisioning request is accepted, the device may get different IP addresses, but the provisioning will still apply to the device that was identified during the request process.between the device and the network. * **Notification URL and token**: - Developers may provide a callback URL on which notifications about all status change events (eg. provision termination) can be received from the service provider. This is an optional parameter. + Developers may provide a callback URL on which notifications about all status change events (eg. provisioning termination) can be received from the service provider. This is an optional parameter. # Resources and Operations overview The API defines four operations: - - An operation to setup a new QoD provision for a given device. - - An operation to get the information about a specific QoD provision, identified by its `provisionId`. - - An operation to get the QoD provisions for a given device. - - An operation to terminate a QoD provision, identified by its `provisionId`. + - An operation to setup a new QoD provisioning for a given device. + - An operation to get the information about a specific QoD provisioning, identified by its `provisioningId`. + - An operation to get the QoD provisioning for a given device. + - An operation to terminate a QoD provisioning, identified by its `provisioningId`. ### Authorization and authentication @@ -43,52 +43,52 @@ externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/qod-provision/vwip" + - url: "{apiRoot}/qod-provisioning/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: QoD Provision - description: Manage the provision of QoD + - name: QoD Provisioning + description: Manage the provisioning of QoD paths: - /provisions: + /device-qos: post: tags: - - QoD Provision - summary: Sets a new QoD provision + - QoD Provisioning + summary: Sets a new provisioning of QoS for a device description: | - Triggers a new provision in the operator to assign certain QoS Profile to certain device. + Triggers a new provisioning in the operator to assign certain QoS Profile to certain device. - - If the provision is completed synchronously, the response will be 201 with `status` = `AVAILABLE`. - - If the provision request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. - - If the operator determines synchronously that the provision request cannot be fulfilled, the response will be 201 with `status` = `UNAVAILABLE`. + - If the provisioning is completed synchronously, the response will be 201 with `status` = `AVAILABLE`. + - If the provisioning request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. + - If the operator determines synchronously that the provisioning request cannot be fulfilled, the response will be 201 with `status` = `UNAVAILABLE`. - If the request includes a webhook, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. - NOTE: When the provision status becomes `UNAVAILABLE`, the QoD provision resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. - This behavior allows clients which are not receiving notification events but are polling, to get the provision status information. Before a client can attempt to create a new QoD provision for the same device, they must release the provision resources with an explicit `delete` operation if not yet automatically deleted. + NOTE: When the provisioning status becomes `UNAVAILABLE`, the QoD provisioning resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. + This behavior allows clients which are not receiving notification events but are polling, to get the provisioning status information. Before a client can attempt to create a new QoD provisioning for the same device, they must release the provisioning resources with an explicit `delete` operation if not yet automatically deleted. - operationId: createProvision + operationId: createProvisioning parameters: - $ref: "#/components/parameters/x-correlator" requestBody: - description: Parameters to create a new provision + description: Parameters to create a new provisioning content: application/json: schema: - $ref: "#/components/schemas/CreateProvision" + $ref: "#/components/schemas/CreateProvisioning" required: true callbacks: notifications: "{$request.body#/webhook/notificationUrl}": post: - summary: Provision notifications callback + summary: Provisioning notifications callback description: | Important: this endpoint is to be implemented by the API consumer. - The QoD server will call this endpoint whenever any QoD provision change related event occurs. - Currently only `PROVISION_STATUS_CHANGED` event is defined. - operationId: postProvisionNotification + The QoD server will call this endpoint whenever any QoD provisioning change related event occurs. + Currently only `PROVISIONING_STATUS_CHANGED` event is defined. + operationId: postProvisioningNotification parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -98,8 +98,8 @@ paths: schema: $ref: "#/components/schemas/CloudEvent" examples: - PROVISION_STATUS_CHANGED_EXAMPLE: - $ref: "#/components/examples/PROVISION_STATUS_CHANGED_EXAMPLE" + PROVISIONING_STATUS_CHANGED_EXAMPLE: + $ref: "#/components/examples/PROVISIONING_STATUS_CHANGED_EXAMPLE" responses: "204": description: Successful notification @@ -121,14 +121,14 @@ paths: - notificationsBearerAuth: [] responses: "201": - description: Provision created + description: Provisioning created headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/ProvisionInfo" + $ref: "#/components/schemas/ProvisioningInfo" "400": $ref: "#/components/responses/Generic400" "401": @@ -138,7 +138,7 @@ paths: "404": $ref: "#/components/responses/DeviceNotFound404" "409": - $ref: "#/components/responses/ProvisionConflict409" + $ref: "#/components/responses/ProvisioningConflict409" "422": $ref: "#/components/responses/Generic422" "500": @@ -147,33 +147,33 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:create" + - "qod-provisioning:device-qos:create" - /provisions/{provisionId}: + /device-qos/{provisioningId}: get: tags: - - QoD Provision - summary: Get QoD provision information - description: Querying for QoD provisions resource information details - operationId: getProvision + - QoD Provisioning + summary: Get QoD provisioning information + description: Querying for QoD provisioning resource information details + operationId: getProvisioningById parameters: - - $ref: "#/components/parameters/provisionId" + - $ref: "#/components/parameters/provisioningId" - $ref: "#/components/parameters/x-correlator" responses: "200": - description: Returns information about an active provision + description: Returns information about certain provisioning headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/ProvisionInfo" + $ref: "#/components/schemas/ProvisioningInfo" examples: - PROVISION_AVAILABLE: - $ref: "#/components/examples/PROVISION_AVAILABLE" - PROVISION_UNAVAILABLE: - $ref: "#/components/examples/PROVISION_UNAVAILABLE" + PROVISIONING_AVAILABLE: + $ref: "#/components/examples/PROVISIONING_AVAILABLE" + PROVISIONING_UNAVAILABLE: + $ref: "#/components/examples/PROVISIONING_UNAVAILABLE" "400": $ref: "#/components/responses/Generic400" "401": @@ -188,26 +188,26 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:read" + - "qod-provisioning:device-qos:read" delete: tags: - - QoD Provision - summary: Deletes a QoD provision + - QoD Provisioning + summary: Deletes a QoD provisioning description: | - Release resources related to QoS provision. + Release resources related to QoS provisioning. - If the notification callback is provided and the provision status was `AVAILABLE`, when the deletion is completed, the client will receive in addition to the response a `PROVISION_STATUS_CHANGED` event with + If the notification callback is provided and the provisioning status was `AVAILABLE`, when the deletion is completed, the client will receive in addition to the response a `PROVISIONING_STATUS_CHANGED` event with - `status` as `UNAVAILABLE` and - `statusInfo` as `DELETE_REQUESTED` There will be no notification event if the `status` was already `UNAVAILABLE`. - operationId: deleteProvision + operationId: deleteProvisioning parameters: - - $ref: "#/components/parameters/provisionId" + - $ref: "#/components/parameters/provisioningId" - $ref: "#/components/parameters/x-correlator" responses: "204": - description: Provision deleted + description: Provisioning deleted headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -219,7 +219,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ProvisionInfo" + $ref: "#/components/schemas/ProvisioningInfo" "400": $ref: "#/components/responses/Generic400" "401": @@ -234,38 +234,38 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:delete" + - "qod-provisioning:device-qos:delete" - /provisions/retrieve: + /device-qos/retrieve: post: tags: - - QoD Provision - summary: Gets the QoD provision for a given device + - QoD Provisioning + summary: Gets the QoD provisioning for a given device description: | - Retrieves the QoD provision for a given device. - operationId: retrieveProvision + Retrieves the QoD provisioning for a given device. + operationId: retrieveProvisioningByDevice parameters: - $ref: "#/components/parameters/x-correlator" requestBody: - description: Parameters to retrieve a provision by device + description: Parameters to retrieve a provisioning by device content: application/json: schema: - $ref: "#/components/schemas/RetrieveProvision" + $ref: "#/components/schemas/RetrieveProvisioning" required: true responses: "200": - description: Returns information about an active provision for the device. If no provision is found for the device, an error response 404 is returned with code "PROVISION_NOT_FOUND". + description: Returns information about QoS provisioning for the device. If no provisioning is found for the device, an error response 404 is returned with code "PROVISIONING_NOT_FOUND". headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/ProvisionInfo" + $ref: "#/components/schemas/ProvisioningInfo" examples: - PROVISION_AVAILABLE: - $ref: "#/components/examples/PROVISION_AVAILABLE" + PROVISIONING_AVAILABLE: + $ref: "#/components/examples/PROVISIONING_AVAILABLE" "400": $ref: "#/components/responses/Generic400" "401": @@ -273,7 +273,7 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/RetrieveProvision404" + $ref: "#/components/responses/RetrieveProvisioning404" "422": $ref: "#/components/responses/Generic422" "500": @@ -282,7 +282,7 @@ paths: $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provision:provisions:read" + - "qod-provisioning:device-qos:read" components: securitySchemes: @@ -297,13 +297,13 @@ components: bearerFormat: "{$request.body#/webhook/notificationAuthToken}" parameters: - provisionId: - name: provisionId + provisioningId: + name: provisioningId in: path - description: Provision ID that was obtained from the createProvision operation + description: Provisioning ID that was obtained from the createProvision operation required: true schema: - $ref: "#/components/schemas/ProvisionId" + $ref: "#/components/schemas/ProvisioningId" x-correlator: name: x-correlator @@ -319,13 +319,13 @@ components: type: string schemas: - ProvisionId: - description: Provision Identifier in UUID format + ProvisioningId: + description: Provisioning Identifier in UUID format type: string format: uuid - BaseProvisionInfo: - description: Common attributes of a QoD provision + BaseProvisioningInfo: + description: Common attributes of a QoD provisioning type: object properties: device: @@ -333,7 +333,7 @@ components: qosProfile: $ref: "#/components/schemas/QosProfileName" webhook: - description: Callback URL on which notifications about all status change events of the provision process (eg. provision termination) can be received + description: Callback URL on which notifications about all status change events of the provisioning process (eg. provisioning termination) can be received type: object required: - notificationUrl @@ -342,7 +342,7 @@ components: type: string format: uri example: "https://application-server.com" - description: Allows asynchronous delivery of provision related events + description: Allows asynchronous delivery of provisioning related events notificationAuthToken: type: string minLength: 20 @@ -353,16 +353,16 @@ components: - device - qosProfile - ProvisionInfo: - description: Provision related information. + ProvisioningInfo: + description: Provisioning related information. allOf: - - $ref: "#/components/schemas/BaseProvisionInfo" + - $ref: "#/components/schemas/BaseProvisioningInfo" - type: object properties: - provisionId: - $ref: "#/components/schemas/ProvisionId" + provisioningId: + $ref: "#/components/schemas/ProvisioningId" startedAt: - description: Date and time when the provision became "AVAILABLE". Not to be returned when `status` is "REQUESTED". Format must follow RFC 3339 and must indicate time zone (UTC or local). + description: Date and time when the provisioning became "AVAILABLE". Not to be returned when `status` is "REQUESTED". Format must follow RFC 3339 and must indicate time zone (UTC or local). type: string format: date-time example: "2024-06-01T12:00:00Z" @@ -371,16 +371,16 @@ components: statusInfo: $ref: "#/components/schemas/StatusInfo" required: - - provisionId + - provisioningId - status - CreateProvision: - description: Attributes to request a new QoD provision + CreateProvisioning: + description: Attributes to request a new QoD provisioning allOf: - - $ref: "#/components/schemas/BaseProvisionInfo" + - $ref: "#/components/schemas/BaseProvisioningInfo" - RetrieveProvision: - description: Attributes to look for QoD provisions + RetrieveProvisioning: + description: Attributes to look for QoD provisioning type: object properties: device: @@ -430,7 +430,7 @@ components: description: The type of the event. type: string enum: - - "org.camaraproject.qod-provision.vwip.status-changed" + - "org.camaraproject.qod-provisioning.vwip.status-changed" specversion: description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) type: string @@ -452,10 +452,10 @@ components: discriminator: propertyName: "type" mapping: - org.camaraproject.qod-provision.vwip.status-changed: "#/components/schemas/EventStatusChanged" + org.camaraproject.qod-provisioning.vwip.status-changed: "#/components/schemas/EventStatusChanged" EventStatusChanged: - description: Event to notify a QoD provision status change + description: Event to notify a QoD provisioning status change allOf: - $ref: "#/components/schemas/CloudEvent" - type: object @@ -464,11 +464,11 @@ components: type: object description: Event details depending on the event type required: - - provisionId + - provisioningId - qosStatus properties: - provisionId: - $ref: "#/components/schemas/ProvisionId" + provisioningId: + $ref: "#/components/schemas/ProvisioningId" status: $ref: "#/components/schemas/StatusChanged" statusInfo: @@ -479,8 +479,8 @@ components: StatusInfo: description: | Reason for the new `status`: - * `NETWORK_TERMINATED` - Network terminated the QoD provision - * `DELETE_REQUESTED`- User requested the deletion of the QoD provision + * `NETWORK_TERMINATED` - Network terminated the QoD provisioning + * `DELETE_REQUESTED`- User requested the deletion of the QoD provisioning type: string enum: @@ -563,10 +563,10 @@ components: Status: description: | - The current status of the requested QoD provision. The status can be one of the following: - * `REQUESTED` - QoD provision has been requested but is still being processed. + The current status of the requested QoD provisioning. The status can be one of the following: + * `REQUESTED` - QoD provisioning has been requested but is still being processed. * `AVAILABLE` - The requested QoS profile has been provisioned to the device, and is active. - * `UNAVAILABLE` - The QoD provision request has been processed but is not active. `statusInfo` may provide additional information about the reason for the unavailability. + * `UNAVAILABLE` - The QoD provisioning request has been processed but is not active. `statusInfo` may provide additional information about the reason for the unavailability. enum: - REQUESTED - AVAILABLE @@ -574,9 +574,9 @@ components: StatusChanged: description: | - The current status of a requested or previously available QoD provision. Applicable values in the event are: + The current status of a requested or previously available QoD provisioning. Applicable values in the event are: * `AVAILABLE` - The requested QoS profile has been provisioned to the device, and is active. - * `UNAVAILABLE` - A requested or previously available QoD provision is now unavailable. `statusInfo` may provide additional information about the reason for the unavailability. + * `UNAVAILABLE` - A requested or previously available QoD provisioning is now unavailable. `statusInfo` may provide additional information about the reason for the unavailability. type: string enum: - AVAILABLE @@ -787,8 +787,8 @@ components: code: DEVICE_NOT_FOUND message: "No device found for a provided identifier" - RetrieveProvision404: - description: Device or provision not found + RetrieveProvisioning404: + description: Device or provisioning not found headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -804,16 +804,16 @@ components: status: 404 code: DEVICE_NOT_FOUND message: "No device found for a provided identifier" - ERROR_404_PROVISION_NOT_FOUND: - summary: No provision found for the device - description: The provided device is valid but does not have any provision + ERROR_404_PROVISIONING_NOT_FOUND: + summary: No provisioning found for the device + description: The provided device is valid but does not have any provisioning value: status: 404 - code: PROVISION_NOT_FOUND - message: "No provision found for the provided device" + code: PROVISIONING_NOT_FOUND + message: "No provisioning found for the provided device" - ProvisionConflict409: - description: Provision conflict + ProvisioningConflict409: + description: Provisioning conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -822,31 +822,31 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - PROVISION_409_CONFLICT: - summary: Provision Conflict - description: The requested provision conflicts with an existing one + PROVISIONING_409_CONFLICT: + summary: Provisioning Conflict + description: The requested provisioning conflicts with an existing one value: status: 409 code: CONFLICT - message: "There is another active provision for the same device" + message: "There is another existing provisioning for the same device" examples: - PROVISION_AVAILABLE: - summary: QoD provision status is available - description: The provision has become available + PROVISIONING_AVAILABLE: + summary: QoD provisioning status is available + description: The provisioning has become available value: device: phoneNumber: "+123456789" qosProfile: QOS_L webhook: notificationUrl: https://application-server.com - provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + provisioningId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 startedAt: 2024-05-12T17:32:01Z status: AVAILABLE - PROVISION_UNAVAILABLE: - summary: QoD provision status is unavailable - description: The provision could not be created or is not active anymore + PROVISIONING_UNAVAILABLE: + summary: QoD provisioning status is unavailable + description: The provisioning could not be created or is not active anymore value: duration: 86400 device: @@ -856,21 +856,21 @@ components: qosProfile: QOS_L webhook: notificationUrl: https://application-server.com - provisionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + provisioningId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 startedAt: 2024-05-12T17:32:01Z status: UNAVAILABLE statusInfo: NETWORK_TERMINATED - PROVISION_STATUS_CHANGED_EXAMPLE: - description: Provision status changed - summary: Cloud event example for QoD provision status change to UNAVAILABLE due to NETWORK_TERMINATED + PROVISIONING_STATUS_CHANGED_EXAMPLE: + description: Provisioning status changed + summary: Cloud event example for QoD provisioning status change to UNAVAILABLE due to NETWORK_TERMINATED value: id: 83a0d986-0866-4f38-b8c0-fc65bfcda452 - source: https://api.example.com/qod-provision/vwip/provisions/123e4567-e89b-12d3-a456-426614174000 + source: https://api.example.com/qod-provisioning/vwip/device-qos/123e4567-e89b-12d3-a456-426614174000 specversion: "1.0" - type: org.camaraproject.qod-provision.vwip.status-changed + type: org.camaraproject.qod-provisioning.vwip.status-changed time: 2021-12-12T00:00:00Z data: - provisionId: 123e4567-e89b-12d3-a456-426614174000 + provisioningId: 123e4567-e89b-12d3-a456-426614174000 status: UNAVAILABLE statusInfo: NETWORK_TERMINATED From ce1e3c78f0b4cfe30700d394df5be6fe9bad830d Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Fri, 12 Jul 2024 13:59:42 +0200 Subject: [PATCH 09/16] Update qod-provision.yaml - Trailing space --- code/API_definitions/qod-provision.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index 0595f476f5..cd4cad22bd 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -56,7 +56,7 @@ paths: post: tags: - QoD Provisioning - summary: Sets a new provisioning of QoS for a device + summary: Sets a new provisioning of QoS for a device description: | Triggers a new provisioning in the operator to assign certain QoS Profile to certain device. From 7051178abd5c9e132f9d195730b660bc8b6701f5 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Fri, 19 Jul 2024 11:12:06 +0200 Subject: [PATCH 10/16] Update code/API_definitions/qod-provision.yaml Co-authored-by: Randy Levensalor --- code/API_definitions/qod-provision.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provision.yaml index cd4cad22bd..98aaa5c303 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provision.yaml @@ -4,7 +4,8 @@ info: description: | The Quality-On-Demand (QoD) Provisioning API offers a programmable interface for developers to request the assignment of a certain QoS Profile to a certain device, indefinitely. - This API sets up the configuration in the network so the requested QoS profile is applied to an specified device, at any time while the provisioning is available. The device traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provisioning is revoked. + This API sets up the configuration in the network so the requested QoS profile is applied to an specified device, at any time while the provisioning is available. The device traffic will be treated with a certain QoS profile by the network whenever the device is connected to the network, until the provisioning is deleted. + # Relevant terms and definitions From 7c014837b7d2504fbb04d426173ef61660618ab8 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Fri, 2 Aug 2024 12:41:45 +0200 Subject: [PATCH 11/16] Aligned with #326 --- ...d-provision.yaml => qod-provisioning.yaml} | 255 ++++++++++++------ 1 file changed, 168 insertions(+), 87 deletions(-) rename code/API_definitions/{qod-provision.yaml => qod-provisioning.yaml} (76%) diff --git a/code/API_definitions/qod-provision.yaml b/code/API_definitions/qod-provisioning.yaml similarity index 76% rename from code/API_definitions/qod-provision.yaml rename to code/API_definitions/qod-provisioning.yaml index 98aaa5c303..fb81cfa5d2 100644 --- a/code/API_definitions/qod-provision.yaml +++ b/code/API_definitions/qod-provisioning.yaml @@ -13,7 +13,7 @@ info: Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that an operator is offering can be retrieved by means of the [QoS Profile API](link TBC). * **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 network operator for the device, at the request time. When multiple identifiers are provided, they must identify the same device. After the provisioning request is accepted, the device may get different IP addresses, but the provisioning will still apply to the device that was identified during the request process.between the device and the network. + 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 network operator for the device, at the request time. After the provisioning request is accepted, the device may get different IP addresses, but the provisioning will still apply to the device that was identified during the request process. Note: Network Access Identifier is defined for future use and will not be supported with v0.1 of the API. * **Notification URL and token**: Developers may provide a callback URL on which notifications about all status change events (eg. provisioning termination) can be received from the service provider. This is an optional parameter. @@ -26,23 +26,47 @@ info: - An operation to get the QoD provisioning for a given device. - An operation to terminate a QoD provisioning, identified by its `provisioningId`. + # Authorization and Authentication - ### 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. - CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. + Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. - termsOfService: http://swagger.io/terms/ - contact: - email: project-email@sample.com + # Identifying a device from the access token + + This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the device can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. + + ## Handling of device information: + + ### Optional device object for 3-legged tokens: + + - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. + + ### Validation mechanism: + + - The server will extract the device identification from the access token, if available. + - If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token. + - If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the device information in the request does not match the token. + + ### Error handling for unidentifiable devices: + + - If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error. + + ### Restrictions for tokens without an associated authenticated identifier: + + - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip + x-camara-commonalities: 0.4.0 + externalDocs: - description: Product documentation at Camara - url: https://github.com/camaraproject/ + description: Project documentation at CAMARA + url: https://github.com/camaraproject/QualityOnDemand + servers: - url: "{apiRoot}/qod-provisioning/vwip" variables: @@ -51,7 +75,8 @@ servers: description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` tags: - name: QoD Provisioning - description: Manage the provisioning of QoD + description: Manage the permanent provisioning of QoD + paths: /device-qos: post: @@ -67,8 +92,13 @@ paths: - If the request includes a webhook, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. - NOTE: When the provisioning status becomes `UNAVAILABLE`, the QoD provisioning resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. + **NOTES:** + - When the provisioning status becomes `UNAVAILABLE`, the QoD provisioning resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. + This behavior allows clients which are not receiving notification events but are polling, to get the provisioning status information. Before a client can attempt to create a new QoD provisioning for the same device, they must release the provisioning resources with an explicit `delete` operation if not yet automatically deleted. + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token which is associated with a device is used, it is recommended NOT to include the `device` parameter in the request (see "Handling of device information" within the API description for details). + - If a 2-legged access token is used, the device parameter must be provided and identify a device. operationId: createProvisioning parameters: @@ -137,11 +167,13 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/DeviceNotFound404" + $ref: "#/components/responses/GenericDevice404" "409": $ref: "#/components/responses/ProvisioningConflict409" "422": $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -155,7 +187,13 @@ paths: tags: - QoD Provisioning summary: Get QoD provisioning information - description: Querying for QoD provisioning resource information details + description: | + Querying for QoD provisioning resource information details + + **NOTES:** + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token is used, the end user (and device) associated with the QoD provisioning must also be associated with the access token. + - The QoD provisioning must have been created by the same API client given in the access token. operationId: getProvisioningById parameters: - $ref: "#/components/parameters/provisioningId" @@ -175,6 +213,8 @@ paths: $ref: "#/components/examples/PROVISIONING_AVAILABLE" PROVISIONING_UNAVAILABLE: $ref: "#/components/examples/PROVISIONING_UNAVAILABLE" + PROVISIONING_AVAILABLE_WITHOUT_DEVICE: + $ref: "#/components/examples/PROVISIONING_AVAILABLE_WITHOUT_DEVICE" "400": $ref: "#/components/responses/Generic400" "401": @@ -183,6 +223,8 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -202,6 +244,11 @@ paths: - `status` as `UNAVAILABLE` and - `statusInfo` as `DELETE_REQUESTED` There will be no notification event if the `status` was already `UNAVAILABLE`. + + **NOTES:** + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token is used, the end user (and device) associated with the QoD provisioning must also be associated with the access token. + - The QoD provisioning must have been created by the same API client given in the access token. operationId: deleteProvisioning parameters: - $ref: "#/components/parameters/provisioningId" @@ -229,6 +276,8 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -237,13 +286,20 @@ paths: - openId: - "qod-provisioning:device-qos:delete" - /device-qos/retrieve: + /retrieve-device-qos: post: tags: - QoD Provisioning - summary: Gets the QoD provisioning for a given device + summary: Gets the QoD provisioning for a device description: | - Retrieves the QoD provisioning for a given device. + Retrieves the QoD provisioning for a device. + + **NOTES:** + - The access token may be either 2-legged or 3-legged. + - If a 3-legged access token is used, the end user (and device) associated with the QoD provisioning must also be associated with the access token. In this case it is recommended NOT to include the `device` parameter in the request (see "Handling of device information" within the API description for details). + - If a 2-legged access token is used, the device parameter must be provided and identify a device. + - The QoD provisioning must have been created by the same API client given in the access token. + - If no provisioning is found for the device, an error response 404 is returned with code "NOT_FOUND". operationId: retrieveProvisioningByDevice parameters: - $ref: "#/components/parameters/x-correlator" @@ -252,11 +308,10 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RetrieveProvisioning" - required: true + $ref: "#/components/schemas/RetrieveProvisioningByDevice" responses: "200": - description: Returns information about QoS provisioning for the device. If no provisioning is found for the device, an error response 404 is returned with code "PROVISIONING_NOT_FOUND". + description: Returns information about QoS provisioning for the device. headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -267,6 +322,8 @@ paths: examples: PROVISIONING_AVAILABLE: $ref: "#/components/examples/PROVISIONING_AVAILABLE" + PROVISIONING_AVAILABLE_WITHOUT_DEVICE: + $ref: "#/components/examples/PROVISIONING_AVAILABLE_WITHOUT_DEVICE" "400": $ref: "#/components/responses/Generic400" "401": @@ -274,16 +331,18 @@ paths: "403": $ref: "#/components/responses/Generic403" "404": - $ref: "#/components/responses/RetrieveProvisioning404" + $ref: "#/components/responses/GenericDevice404" "422": $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" security: - openId: - - "qod-provisioning:device-qos:read" + - "qod-provisioning:device-qos:read-by-device" components: securitySchemes: @@ -351,11 +410,13 @@ components: example: "c8974e592c2fa383d4a3960714" description: Authentication token for callback API required: - - device - qosProfile ProvisioningInfo: - description: Provisioning related information. + description: | + Provisioning related information returned in responses. + Optional device object only to be returned if provided in createProvisioning. If more than one type of device identifier was provided, only one identifier will be returned (at implementation choice and with the original value provided in createProvisioning). + Please note that IP addresses of devices can change and get reused, so the original values may no longer identify the same device. They identified the device at the time of QoD provisioning creation. allOf: - $ref: "#/components/schemas/BaseProvisioningInfo" - type: object @@ -380,14 +441,12 @@ components: allOf: - $ref: "#/components/schemas/BaseProvisioningInfo" - RetrieveProvisioning: + RetrieveProvisioningByDevice: description: Attributes to look for QoD provisioning type: object properties: device: $ref: "#/components/schemas/Device" - required: - - device Port: description: TCP or UDP port number @@ -499,7 +558,8 @@ components: * `phoneNumber` * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: @@ -695,6 +755,48 @@ components: code: NOT_FOUND message: "{{resource}} is not found" + GenericDevice404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_404_NOT_FOUND: + summary: Generic Not Found + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: "{{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. + + ProvisioningConflict409: + description: Provisioning conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PROVISIONING_409_CONFLICT: + summary: Provisioning Conflict + description: The requested provisioning conflicts with an existing one + value: + status: 409 + code: CONFLICT + message: "There is another existing provisioning for the same device" + Generic422: description: Unprocessable entity headers: @@ -733,6 +835,35 @@ components: status: 422 code: UNSUPPORTED_DEVICE_IDENTIFIERS message: "Supported device supported are: ..." + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: Service is not available for the provided device + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: The device cannot be identified. + + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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: Internal server error @@ -770,67 +901,6 @@ components: code: UNAVAILABLE message: "Service unavailable" - DeviceNotFound404: - description: Device not found - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - ERROR_404_DEVICE_NOT_FOUND: - summary: Some identifier cannot be matched to a device - description: One or more of the provided device identifiers do not match any device - value: - status: 404 - code: DEVICE_NOT_FOUND - message: "No device found for a provided identifier" - - RetrieveProvisioning404: - description: Device or provisioning not found - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - ERROR_404_DEVICE_NOT_FOUND: - summary: Some identifier cannot be matched to a device - description: One or more of the provided device identifiers do not match any device - value: - status: 404 - code: DEVICE_NOT_FOUND - message: "No device found for a provided identifier" - ERROR_404_PROVISIONING_NOT_FOUND: - summary: No provisioning found for the device - description: The provided device is valid but does not have any provisioning - value: - status: 404 - code: PROVISIONING_NOT_FOUND - message: "No provisioning found for the provided device" - - ProvisioningConflict409: - description: Provisioning conflict - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - PROVISIONING_409_CONFLICT: - summary: Provisioning Conflict - description: The requested provisioning conflicts with an existing one - value: - status: 409 - code: CONFLICT - message: "There is another existing provisioning for the same device" - examples: PROVISIONING_AVAILABLE: summary: QoD provisioning status is available @@ -862,6 +932,17 @@ components: status: UNAVAILABLE statusInfo: NETWORK_TERMINATED + PROVISIONING_AVAILABLE_WITHOUT_DEVICE: + summary: QoD provisioning status is available but no device information is provided + description: Device is optional in responses and must not be provided if it was not provided in the request + value: + qosProfile: QOS_M + webhook: + notificationUrl: https://application-server.com + provisioningId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + startedAt: 2024-05-12T17:32:01Z + status: AVAILABLE + PROVISIONING_STATUS_CHANGED_EXAMPLE: description: Provisioning status changed summary: Cloud event example for QoD provisioning status change to UNAVAILABLE due to NETWORK_TERMINATED From 7d47c12b28c5a390609ea64b2341f34961977125 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Fri, 2 Aug 2024 14:41:20 +0200 Subject: [PATCH 12/16] Update qod-provisioning.yaml Revert required: true for request Body --- code/API_definitions/qod-provisioning.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/code/API_definitions/qod-provisioning.yaml b/code/API_definitions/qod-provisioning.yaml index fb81cfa5d2..32c2ed1e4f 100644 --- a/code/API_definitions/qod-provisioning.yaml +++ b/code/API_definitions/qod-provisioning.yaml @@ -309,6 +309,7 @@ paths: application/json: schema: $ref: "#/components/schemas/RetrieveProvisioningByDevice" + required: true responses: "200": description: Returns information about QoS provisioning for the device. From 360bcaae784a7605f61f6d9a3d5c040e6dcfbd8d Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Mon, 5 Aug 2024 14:20:24 +0200 Subject: [PATCH 13/16] Update qod-provisioning.yaml - Updated implicit subscriptions model with Commonalities, issue https://github.com/camaraproject/QualityOnDemand/issues/332 - Error examples aligned with Commonalities (removed summary and some messages updated) --- code/API_definitions/qod-provisioning.yaml | 212 +++++++++++++++------ 1 file changed, 157 insertions(+), 55 deletions(-) diff --git a/code/API_definitions/qod-provisioning.yaml b/code/API_definitions/qod-provisioning.yaml index 32c2ed1e4f..a37c3719b3 100644 --- a/code/API_definitions/qod-provisioning.yaml +++ b/code/API_definitions/qod-provisioning.yaml @@ -16,7 +16,7 @@ info: 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 network operator for the device, at the request time. After the provisioning request is accepted, the device may get different IP addresses, but the provisioning will still apply to the device that was identified during the request process. Note: Network Access Identifier is defined for future use and will not be supported with v0.1 of the API. * **Notification URL and token**: - Developers may provide a callback URL on which notifications about all status change events (eg. provisioning termination) can be received from the service provider. This is an optional parameter. + Developers may provide a callback URL (`sink`) on which notifications about all status change events (eg. provisioning termination) can be received from the service provider. This is an optional parameter. The notification will be sent as a CloudEvent compliant message. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` property to protect the notification enpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` if provided. # Resources and Operations overview The API defines four operations: @@ -90,7 +90,7 @@ paths: - If the provisioning request is accepted but not yet completed, the response will be 201 with `status` = `REQUESTED`. - If the operator determines synchronously that the provisioning request cannot be fulfilled, the response will be 201 with `status` = `UNAVAILABLE`. - - If the request includes a webhook, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. + - If the request includes the `sink` and `sinkCredential` properties, the client will receive a `status-changed` event with the outcome of the process. The event will be sent also for synchronous operations. **NOTES:** - When the provisioning status becomes `UNAVAILABLE`, the QoD provisioning resource is not immediately released, but will get deleted automatically, at earliest 360 seconds after. @@ -112,7 +112,7 @@ paths: required: true callbacks: notifications: - "{$request.body#/webhook/notificationUrl}": + "{$request.body#/sink}": post: summary: Provisioning notifications callback description: | @@ -143,6 +143,10 @@ paths: $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": @@ -355,7 +359,7 @@ components: description: Bearer authentication for notifications type: http scheme: bearer - bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + bearerFormat: "{$request.body#/sinkCredential.credentialType}" parameters: provisioningId: @@ -393,23 +397,13 @@ components: $ref: "#/components/schemas/Device" qosProfile: $ref: "#/components/schemas/QosProfileName" - webhook: - description: Callback URL on which notifications about all status change events of the provisioning process (eg. provisioning termination) can be received - type: object - required: - - notificationUrl - properties: - notificationUrl: - type: string - format: uri - example: "https://application-server.com" - description: Allows asynchronous delivery of provisioning related events - notificationAuthToken: - type: string - minLength: 20 - maxLength: 256 - example: "c8974e592c2fa383d4a3960714" - description: Authentication token for callback API + 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" required: - qosProfile @@ -449,6 +443,100 @@ components: device: $ref: "#/components/schemas/Device" + SinkCredential: + description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + type: object + 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 + + PlainCredential: + type: object + description: A plain credential as a combination of an identifier and a secret. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - type: object + required: + - identifier + - secret + properties: + identifier: + description: The identifier might be an account or username. + type: string + secret: + description: The secret might be a password or passphrase. + type: string + + AccessTokenCredential: + type: object + description: An access token credential. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - type: object + properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). + type: string + enum: + - bearer + required: + - accessToken + - accessTokenExpiresUtc + - accessTokenType + + RefreshTokenCredential: + type: object + description: An access token credential with a refresh token. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - type: object + properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). + type: string + enum: + - bearer + refreshToken: + description: REQUIRED. An refresh token credential used to acquire access tokens. + type: string + refreshTokenEndpoint: + type: string + format: uri + description: REQUIRED. A URL at which the refresh token can be traded for an access token. + required: + - accessToken + - accessTokenExpiresUtc + - accessTokenType + - refreshToken + - refreshTokenEndpoint + Port: description: TCP or UDP port number type: integer @@ -674,14 +762,12 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_400_INVALID_ARGUMENT: - summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_OUT_OF_RANGE: - summary: Generic 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 @@ -699,14 +785,12 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_401_UNAUTHENTICATED: - summary: Generic 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: - summary: Generic Authentication Required description: New authentication is needed, authentication is no longer valid value: status: 401 @@ -724,15 +808,13 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_403_PERMISSION_DENIED: - summary: Generic Permission Denied description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. GENERIC_403_INVALID_TOKEN_CONTEXT: - summary: Invalid access token context - description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token value: status: 403 code: INVALID_TOKEN_CONTEXT @@ -749,12 +831,11 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_404_NOT_FOUND: - summary: Generic Not Found description: Resource is not found value: status: 404 code: NOT_FOUND - message: "{{resource}} is not found" + message: The specified resource is not found. GenericDevice404: description: Not found @@ -767,12 +848,11 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_404_NOT_FOUND: - summary: Generic Not Found description: Resource is not found value: status: 404 code: NOT_FOUND - message: "{{resource}} is not found" + message: The specified resource is not found. GENERIC_404_DEVICE_NOT_FOUND: description: Device identifier not found value: @@ -791,13 +871,29 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: PROVISIONING_409_CONFLICT: - summary: Provisioning Conflict description: The requested provisioning conflicts with an existing one value: status: 409 code: CONFLICT message: "There is another existing provisioning for the same device" + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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. + Generic422: description: Unprocessable entity headers: @@ -809,28 +905,24 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_422_UNPROCESSABLE_ENTITY: - summary: Unprocessable entity description: The request was well-formed but was unable to be processed due to semantic errors or not applicable values. This is the generic error code for 422 responses. value: status: 422 code: UNPROCESSABLE_ENTITY message: "Value not acceptable: ..." - GENERIC_422_DEVICE_NOT_APPLICABLE: - summary: Service not applicable to the device - description: The provided device is not compatible with the requested operation, according to the service provider rules. - value: - status: 422 - code: DEVICE_NOT_APPLICABLE - message: "The device is not applicable for the requested operation" GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: - summary: Device identifiers mismatch - description: Several device identifiers are provided but do not match the same device + description: Inconsistency between device identifiers not pointing to the same device value: status: 422 code: DEVICE_IDENTIFIERS_MISMATCH - message: "The provided device identifiers do not match the same device" + 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: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: - summary: None of the provided device identifiers is supported by the implementation description: Message may list the supported device identifiers value: status: 422 @@ -877,12 +969,11 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_500_INTERNAL: - summary: Generic Internal description: Problem in Server side. Regular Server Exception value: status: 500 code: INTERNAL - message: "Internal server error" + message: Unknown server error. Typically a server bug. Generic503: description: Service unavailable @@ -895,12 +986,11 @@ components: $ref: "#/components/schemas/ErrorInfo" examples: GENERIC_503_UNAVAILABLE: - summary: Generic Unavailable description: Service is not available. Temporary situation usually related to maintenance process in the server side value: status: 503 code: UNAVAILABLE - message: "Service unavailable" + message: Service Unavailable. examples: PROVISIONING_AVAILABLE: @@ -910,8 +1000,12 @@ components: device: phoneNumber: "+123456789" qosProfile: QOS_L - webhook: - notificationUrl: https://application-server.com + sink: https://application-server.com/callback + sinkCredential: + credentialType: ACCESSTOKEN + accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + accessTokenExpiresUtc: "2024-12-01T12:00:00Z" + accessTokenType: bearer provisioningId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 startedAt: 2024-05-12T17:32:01Z status: AVAILABLE @@ -926,8 +1020,12 @@ components: publicAddress: 203.0.113.0 publicPort: 59765 qosProfile: QOS_L - webhook: - notificationUrl: https://application-server.com + sink: https://application-server.com/callback + sinkCredential: + credentialType: ACCESSTOKEN + accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + accessTokenExpiresUtc: "2024-12-01T12:00:00Z" + accessTokenType: bearer provisioningId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 startedAt: 2024-05-12T17:32:01Z status: UNAVAILABLE @@ -938,8 +1036,12 @@ components: description: Device is optional in responses and must not be provided if it was not provided in the request value: qosProfile: QOS_M - webhook: - notificationUrl: https://application-server.com + sink: https://application-server.com/callback + sinkCredential: + credentialType: ACCESSTOKEN + accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" + accessTokenExpiresUtc: "2024-12-01T12:00:00Z" + accessTokenType: bearer provisioningId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 startedAt: 2024-05-12T17:32:01Z status: AVAILABLE From 18505f7116a3d5ec8b5eba1fcd547bac4b9ff7e6 Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Mon, 5 Aug 2024 14:26:27 +0200 Subject: [PATCH 14/16] Update qod-provisioning.yaml Trailing spaces --- code/API_definitions/qod-provisioning.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/qod-provisioning.yaml b/code/API_definitions/qod-provisioning.yaml index a37c3719b3..f9cdd76d1b 100644 --- a/code/API_definitions/qod-provisioning.yaml +++ b/code/API_definitions/qod-provisioning.yaml @@ -403,7 +403,7 @@ components: description: The address to which events shall be delivered using the selected protocol. example: "https://endpoint.example.com/sink" sinkCredential: - $ref: "#/components/schemas/SinkCredential" + $ref: "#/components/schemas/SinkCredential" required: - qosProfile @@ -893,7 +893,7 @@ components: status: 410 code: GONE message: Access to the target resource is no longer available. - + Generic422: description: Unprocessable entity headers: From 8b12298e30dae49468ac155348fffd908e51f11a Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Tue, 6 Aug 2024 12:19:55 +0200 Subject: [PATCH 15/16] Update qod-provisioning.yaml Fixing review comments --- code/API_definitions/qod-provisioning.yaml | 39 ++++++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/qod-provisioning.yaml b/code/API_definitions/qod-provisioning.yaml index f9cdd76d1b..3a12fa7510 100644 --- a/code/API_definitions/qod-provisioning.yaml +++ b/code/API_definitions/qod-provisioning.yaml @@ -16,7 +16,7 @@ info: 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 network operator for the device, at the request time. After the provisioning request is accepted, the device may get different IP addresses, but the provisioning will still apply to the device that was identified during the request process. Note: Network Access Identifier is defined for future use and will not be supported with v0.1 of the API. * **Notification URL and token**: - Developers may provide a callback URL (`sink`) on which notifications about all status change events (eg. provisioning termination) can be received from the service provider. This is an optional parameter. The notification will be sent as a CloudEvent compliant message. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` property to protect the notification enpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` if provided. + Developers may provide a callback URL (`sink`) on which notifications about all status change events (eg. provisioning termination) can be received from the service provider. This is an optional parameter. The notification will be sent as a CloudEvent compliant message. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` property to protect the notification endpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` if provided. # Resources and Operations overview The API defines four operations: @@ -138,7 +138,7 @@ paths: x-correlator: $ref: "#/components/headers/x-correlator" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/CreateProvisioning400" "401": $ref: "#/components/responses/Generic401" "403": @@ -647,7 +647,7 @@ components: * `phoneNumber` * `networkAccessIdentifier` - NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device + NOTE1: the network operator 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. type: object properties: @@ -774,6 +774,39 @@ components: code: OUT_OF_RANGE message: Client specified an invalid range. + CreateProvisioning400: + description: Bad Request with additional errors for implicit notifications + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + GENERIC_400_INVALID_CREDENTIAL: + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + GENERIC_400_INVALID_TOKEN: + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" + Generic401: description: Unauthorized headers: From 73937abcf8f3fdca6f0ba2568e4d8af5de848a8a Mon Sep 17 00:00:00 2001 From: Jose Luis Urien Date: Tue, 6 Aug 2024 14:40:54 +0200 Subject: [PATCH 16/16] Update qod-provisioning.yaml Dedicated 400 response was in wrong place --- code/API_definitions/qod-provisioning.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/qod-provisioning.yaml b/code/API_definitions/qod-provisioning.yaml index 3a12fa7510..c5e595d335 100644 --- a/code/API_definitions/qod-provisioning.yaml +++ b/code/API_definitions/qod-provisioning.yaml @@ -138,7 +138,7 @@ paths: x-correlator: $ref: "#/components/headers/x-correlator" "400": - $ref: "#/components/responses/CreateProvisioning400" + $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": @@ -165,7 +165,7 @@ paths: schema: $ref: "#/components/schemas/ProvisioningInfo" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/CreateProvisioning400" "401": $ref: "#/components/responses/Generic401" "403":