openapi: 3.0.3
info:
title: Global System for Mobile Communications GSMA Camara Project Quality on Demand API
description: >-
Quality on Demand API offers the application developer the capability to
request stable latency (reduced jitter) or minimum throughput for specified
application data flows between application clients (within a user device)
and Application Servers (backend services). The developer has a pre-defined
set of Quality of Service (QoS) profiles which they could choose from
depending on their latency or throughput requirements.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 0.11.0
x-camara-commonalities: 0.4.0
externalDocs:
description: Project documentation at Camara
url: https://github.com/camaraproject/QualityOnDemand
servers:
- url: '{apiRoot}/quality-on-demand/v0.11'
variables:
apiRoot:
default: http://localhost:9091
description: >-
API root, defined by the service provider, e.g. `api.example.com` or
`api.example.com/somepath`
tags:
- name: QoS Sessions
description: Manage QoS sessions
paths:
/sessions:
post:
tags:
- QoS Sessions
summary: Global System for Mobile Communications Creates a new session
description: >
Create QoS Session to manage latency/throughput priorities
If the qosStatus in the API response is "AVAILABLE" and a notification
callback is provided the client will receive in addition to the response
a
`QOS_STATUS_CHANGED` event notification with `qosStatus` as `AVAILABLE`.
If the `qosStatus` in the API response is `REQUESTED`, the client will
receive either
- a `QOS_STATUS_CHANGED` event notification with `qosStatus` as
`AVAILABLE` after the network notifies that it has created the requested
session, or
- a `QOS_STATUS_CHANGED` event notification with `qosStatus` as
`UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` after the network
notifies that it has failed to provide the requested session.
A `QOS_STATUS_CHANGED` event notification with `qosStatus` as
`UNAVAILABLE` will also be send if the network terminates the session
before the requested duration expired
**NOTES:**
- In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as
`UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of
the QoS session are not directly released, but will get deleted
automatically at earliest 360 seconds after the event.
This behavior allows clients which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session 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: createSession
security:
- openId:
- quality-on-demand:sessions:create
parameters:
- $ref: '#/components/parameters/x-correlator'
requestBody:
description: Parameters to create a new session
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSession'
required: true
callbacks:
notifications:
'{$request.body#/sink}':
post:
tags:
- Session notifications callback
summary: Session notifications callback
description: >
Important: this endpoint is to be implemented by the API
consumer.
The QoD server will call this endpoint whenever any QoS session
change (e.g. network termination) related event occurs.
Currently only QOS_STATUS_CHANGED event is defined.
operationId: postNotification
parameters:
- $ref: '#/components/parameters/x-correlator'
requestBody:
required: true
content:
application/cloudevents+json:
schema:
$ref: '#/components/schemas/CloudEvent'
examples:
QOS_STATUS_CHANGED_EXAMPLE:
$ref: '#/components/examples/QOS_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'
'410':
$ref: '#/components/responses/Generic410'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
security:
- {}
- notificationsBearerAuth: []
responses:
'201':
description: Session created
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/SessionInfo'
'400':
$ref: '#/components/responses/CreateSessionBadRequest400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$ref: '#/components/responses/GenericDevice404'
'409':
$ref: '#/components/responses/SessionInConflict409'
'422':
$ref: '#/components/responses/Generic422'
'429':
$ref: '#/components/responses/Generic429'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
/sessions/{sessionId}:
get:
tags:
- QoS Sessions
summary: Global System for Mobile Communications Get QoS session information
description: >
Querying for QoS session 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 session must also be associated with the access
token.
- The session must have been created by the same API client given in the
access token
operationId: getSession
security:
- openId:
- quality-on-demand:sessions:read
parameters:
- name: sessionId
in: path
description: Session ID that was obtained from the createSession operation
required: true
schema:
$ref: '#/components/schemas/SessionId'
- $ref: '#/components/parameters/x-correlator'
responses:
'200':
description: Contains information about active session
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/SessionInfo'
examples:
SESSION_AVAILABLE:
$ref: '#/components/examples/SESSION_AVAILABLE_EXAMPLE'
SESSION_UNAVAILABLE:
$ref: '#/components/examples/SESSION_UNAVAILABLE_EXAMPLE'
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$ref: '#/components/responses/Generic404'
'429':
$ref: '#/components/responses/Generic429'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
delete:
tags:
- QoS Sessions
summary: Global System for Mobile Communications Delete a QoS session
description: >
Release resources related to QoS session
If the notification callback is provided and the `qosStatus` of the
session was `AVAILABLE` the client will receive in addition to the
response a `QOS_STATUS_CHANGED` event with
- `qosStatus` as `UNAVAILABLE` and
- `statusInfo` as `DELETE_REQUESTED`
There will be no notification event if the `qosStatus` 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 session must also be associated with the access
token.
- The session must must have been created by the same API client given
in the access token
operationId: deleteSession
security:
- openId:
- quality-on-demand:sessions:delete
parameters:
- name: sessionId
in: path
description: Session ID that was obtained from the createSession operation
required: true
schema:
$ref: '#/components/schemas/SessionId'
- $ref: '#/components/parameters/x-correlator'
responses:
'204':
description: Session 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'
'429':
$ref: '#/components/responses/Generic429'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
/sessions/{sessionId}/extend:
post:
tags:
- QoS Sessions
summary: Global System for Mobile Communications Extend the duration of an active session
description: >
Extend the overall session duration of an active QoS session (with
qosStatus = AVAILABLE).
The overall duration of the QoS session, including the additional
extended duration, shall not exceed the maximum duration limit fixed for
the QoS Profile. If the current duration plus the value of
`requestedAdditionalDuration` exceeds the maximum limit, the new overall
duration shall be capped to the maximum value allowed.
An example: For a QoS profile limited to a `maxDuration` of 50,000
seconds, a QoD session was originally created with duration 30,000
seconds. Before the session expires, the developer requests to extend
the session by another 30,000 seconds:
- Previous duration: 30,000 seconds
- Requested additional duration: 30,000 seconds
- New overall session duration: 50,000 seconds (the maximum allowed)
**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 session must also be associated with the access
token.
- The session must must have been created by the same API client given
in the access token
operationId: extendQosSessionDuration
security:
- openId:
- quality-on-demand:sessions:update
parameters:
- name: sessionId
in: path
description: Session ID that was obtained from the createSession operation
required: true
schema:
$ref: '#/components/schemas/SessionId'
- $ref: '#/components/parameters/x-correlator'
requestBody:
description: Parameters to extend the duration of an active session
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendSessionDuration'
required: true
responses:
'200':
description: Contains information about active session
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/SessionInfo'
'400':
$ref: '#/components/responses/GenericExtendSessionDuration400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$ref: '#/components/responses/Generic404'
'409':
$ref: '#/components/responses/SessionStatusConflict409'
'429':
$ref: '#/components/responses/Generic429'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
/retrieve-sessions:
post:
tags:
- QoS Sessions
summary: Global System for Mobile Communications Get QoS session information for a device
description: >
Querying for QoS session resource information details 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 session 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 session must have been created by the same API client given in the
access token
- If no QoS session is found for the requested device, an empty array is
returned.
operationId: retrieveSessionsByDevice
parameters:
- $ref: '#/components/parameters/x-correlator'
requestBody:
description: Parameters to get QoS session information by device
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSessionsInput'
required: true
responses:
'200':
description: >-
Returns the QoS sessions information for a given device. A device
may have multiple sessions, thus the response is an array. An empty
array is returned if no sessions are found.
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveSessionsOutput'
examples:
RETRIEVE_SESSIONS_ONE_ITEM:
$ref: '#/components/examples/RETRIEVE_SESSIONS_EXAMPLE'
RETRIEVE_SESSIONS_NO_ITEMS:
$ref: '#/components/examples/RETRIEVE_SESSIONS_EMPTY_EXAMPLE'
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$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:
- quality-on-demand:sessions:retrieve-by-device
components:
securitySchemes:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
notificationsBearerAuth:
description: Bearer authentication for notifications
type: http
scheme: bearer
bearerFormat: '{$request.body#sinkCredential.credentialType}'
parameters:
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:
SessionId:
description: Session ID in UUID format
type: string
format: uuid
BaseSessionInfo:
description: Common attributes of a QoD session
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
allOf:
- $ref: '#/components/schemas/PortsSpec'
qosProfile:
$ref: '#/components/schemas/QosProfileName'
sink:
type: string
format: url
description: >-
The address to which events about all status changes of the session
(e.g. session termination) shall be delivered, using the HTTP
protocol.
example: https://endpoint.example.com/sink
sinkCredential:
description: >-
A sink credential provides authentication or authorization
information necessary to enable delivery of events to a target.
allOf:
- $ref: '#/components/schemas/SinkCredential'
required:
- applicationServer
- qosProfile
SessionInfo:
description: >
Session related information returned in responses.
Note that the device object is defined as optional and will only to be
returned if provided in createSession. 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
createSession).
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 session creation.
allOf:
- $ref: '#/components/schemas/BaseSessionInfo'
- type: object
properties:
sessionId:
$ref: '#/components/schemas/SessionId'
duration:
description: >
Session duration in seconds. Implementations can grant the
requested session duration or set a different duration, based on
network policies or conditions.
- When `qosStatus` is "REQUESTED", the value is the duration to
be scheduled, granted by the implementation.
- When `qosStatus` is AVAILABLE", the value is the overall
duration since `startedAt. When the session is extended, the
value is the new overall duration of the session.
- When `qosStatus` is "UNAVAILABLE", the value is the overall
effective duration since `startedAt` until the session was
terminated.
type: integer
format: int32
minimum: 1
example: 3600
startedAt:
description: >-
Date and time when the QoS status became "AVAILABLE". Not to be
returned when `qosStatus` 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'
expiresAt:
description: >
Date and time of the QoS session expiration. Format must follow
RFC 3339 and must indicate time zone (UTC or local).
- When `qosStatus` is "AVAILABLE", it is the limit time when the
session is scheduled to finnish, if not terminated by other
means.
- When `qosStatus` is "UNAVAILABLE", it is the time when the
session was terminated.
- Not to be returned when `qosStatus` is "REQUESTED".
When the session is extended, the value is the new expiration
time of the session.
type: string
format: date-time
example: '2024-06-01T13:00:00Z'
qosStatus:
$ref: '#/components/schemas/QosStatus'
statusInfo:
$ref: '#/components/schemas/StatusInfo'
required:
- sessionId
- duration
- qosStatus
CreateSession:
description: Attributes required to create a session
allOf:
- $ref: '#/components/schemas/BaseSessionInfo'
- type: object
properties:
duration:
description: >
Requested session duration in seconds. Value may be explicitly
limited for the QoS profile, as specified in the [Qos Profile
API](TBC). Implementations can grant the requested session
duration or set a different duration, based on network policies
or conditions.
type: integer
format: int32
minimum: 1
example: 3600
required:
- duration
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
SinkCredential:
type: object
properties:
credentialType:
type: string
enum:
- PLAIN
- ACCESSTOKEN
- REFRESHTOKEN
description: >-
The type of the credential. With the current API version the type
MUST be set to `ACCESSTOKEN`
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)). For the
current version of the API the type MUST be set to `Bearer`.
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
ExtendSessionDuration:
description: Attributes required to extend the duration of an active session
type: object
properties:
requestedAdditionalDuration:
description: >
Additional duration in seconds to be added to the current session
duration. The overall session duration, including extensions, shall
not exceed the maximum duration limit for the QoS Profile.
type: integer
format: int32
minimum: 1
example: 1800
required:
- requestedAdditionalDuration
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.quality-on-demand.v0.qos-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.quality-on-demand.v0.qos-status-changed: '#/components/schemas/EventQosStatusChanged'
EventQosStatusChanged:
description: Event to notify a QoS status change
allOf:
- $ref: '#/components/schemas/CloudEvent'
- type: object
properties:
data:
type: object
description: Event details depending on the event type
required:
- sessionId
- qosStatus
properties:
sessionId:
$ref: '#/components/schemas/SessionId'
qosStatus:
$ref: '#/components/schemas/EventQosStatus'
statusInfo:
$ref: '#/components/schemas/StatusInfo'
required:
- data
StatusInfo:
description: >
Reason for the new `qosStatus`. Currently `statusInfo` is only
applicable when `qosStatus` is 'UNAVAILABLE'.
* `DURATION_EXPIRED` - Session terminated due to requested duration
expired
* `NETWORK_TERMINATED` - Network terminated the session before the
requested duration expired
* `DELETE_REQUESTED`- User requested the deletion of the session before
the requested duration expired
type: string
enum:
- DURATION_EXPIRED
- NETWORK_TERMINATED
- DELETE_REQUESTED
Device:
description: >
End-user equipment able to connect to a mobile network. Examples of
devices include smartphones or IoT sensors/actuators.
The developer can choose to provide the below specified device
identifiers:
* `ipv4Address`
* `ipv6Address`
* `phoneNumber`
* `networkAccessIdentifier`
NOTE1: the 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:
phoneNu
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/global-system-for-mobile-communications/refs/heads/main/openapi/quality-on-demand-api-openapi.yml