-
Notifications
You must be signed in to change notification settings - Fork 60
/
Copy pathqod-api.yaml
1234 lines (1146 loc) · 49.8 KB
/
qod-api.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.3
info:
title: QoD for enhanced communication
description: |
The Quality-On-Demand (QoD) API provides programmable interface for developers and other users (capabilities consumers) to request stable latency or throughput managed by Telco networks without the necessity to have an in-depth knowledge of the 4G/5G system or the overall complexity of the Telecom Systems.
# Introduction
Industrial (IoT), VR/Gaming, live video streaming, autonomous driving and many other scenarios demand network communication quality and are sensitive to any change in transmission conditions. Being able to request a stable latency (reduced jitter) or prioritized throughput from the network can improve user experience substantially.
The QoD API offers the application developers the capability to request for stable latency (reduced jitter) or throughput for some specified application data flows between application clients (within a user device) and Application Servers (backend services). The developer has a pre-defined set of Quality of Service (QoS) profiles which they could choose from depending on their latency or throughput requirements.
The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically. The automatic process is triggered either when the requested specified duration of a QoS session has reached its limit or the default session expiration time has been reached (within an example provider implementation it is set to 24hrs).
# Relevant terms and definitions
* **QOD service endpoint**:
The URL pointing to the RESTful resource of the QoD API.
* **Authentication**:
Security access keys such as OAuth 2.0 client credentials used by client applications to invoke the QoD API.
* **QoS profiles and QoS profile labels**:
Latency or throughput requirements of the application mapped to relevant QoS profile class.
* **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 [[5]](#5) assigned by the mobile network operator for the device.
* **Identifier for the application server**:
IPv4 and/or IPv6 address of the application server (application backend)
* **App-Flow (between the application client and application server)**:
The precise application data flow the developer wants to prioritize and 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.
* **Duration**:
Duration (in seconds) for which the QoS session (between application client and application server) should be created. This parameter is optional. When not specified, a default session duration (e.g. 24 hours) is applied. The user may request a termination before its expiration.
* **Notification URL and token**:
Developers may provide a callback URL on which notifications about all status change events of the session (eg. session termination) can be received from the service provider. This is an optional parameter.
# API functionality
The usage of the QoD API is based on QoS profile classes and parameters which define App-Flows.
Based on the API, QoS session resources can be created, queried, and deleted. Once an offered QoS profile class is requested, application users get a prioritized service with stable latency or throughput even in the case of congestion. The QoD API has the following characteristics:
* A specified App-Flow is prioritized to ensure stable latency or throughput for that flow.
* The prioritized App-Flow is described by providing information such as device IP address (or other device identifier) & application server IP addresses and port/port-ranges.
* The developer can optionally specify the duration for which they need the prioritized App-flow.
* Stable latency or throughput is requested by selecting from the list of QoS profiles made available by the service provider (e.g. QOS_E) to map latency and throughput requirements.
* The developer can optionally also specify callback URL on which notifications for the session can be sent. <br>
Following diagram shows the interaction between different components
How QoS profiles are mapped to connectivity characteristics are subject to agreements between the communication service provider and the API invoker. Within the CAMARA project, you can find a sample for such a mapping of QoS profiles. [CAMARA QoS Profiles Mapping Table (REFERENCE DRAFT)](https://github.com/camaraproject/QualityOnDemand/blob/main/documentation/API_documentation/QoSProfile_Mapping_Table.md)
# Further info and support
(FAQs will be added in a later version of the documentation)
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: 0.10.1
externalDocs:
description: Product documentation at Camara
url: https://github.com/camaraproject/
security:
- oAuth2ClientCredentials: []
servers:
- url: "{apiRoot}/qod/v0"
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
- name: QoS Profiles
description: Manage QoS Profiles
paths:
/sessions:
post:
tags:
- QoS Sessions
summary: 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
NOTE: 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` (the `statusInfo` parameter is not included in the current version but will be adding to `SessionInfo` in an upcoming release). 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.
operationId: createSession
requestBody:
description: Parameters to create a new session
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSession"
required: true
callbacks:
notifications:
"{$request.body#/webhook/notificationUrl}":
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
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
"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: Session created
content:
application/json:
schema:
$ref: "#/components/schemas/SessionInfo"
"400":
description: Invalid input for createSession operation
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
Generic400:
summary: Some parameter combinations or parameter values provided are not schema compliant
value:
status: 400
code: INVALID_ARGUMENT
message: "Schema validation failed at ..."
DeviceMissing:
summary: Device must be specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: device"
InsufficientDeviceProperties:
summary: Device must be identified by at least one parameter
value:
status: 400
code: INVALID_ARGUMENT
message: "Insufficient properties specified: device"
InconsistentDeviceProperties:
summary: Device parameters provided identify different devices
value:
status: 400
code: INVALID_ARGUMENT
message: "Multiple inconsistent parameters specified: device"
CannotIdentifyDevice:
summary: No device can be identified from provided parameters
value:
status: 400
code: INVALID_ARGUMENT
message: "Unable to identify device from specified parameters: device"
InvalidDevicePublicPortValue:
summary: Invalid port specified for device public port
value:
status: 400
code: OUT_OF_RANGE
message: "Invalid port value specified: device.ipv4Address.publicPort"
ApplicationServerMissing:
summary: Application server must be specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: applicationServer"
QoSProfileMissing:
summary: Required QoS profile must be specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: qosProfile"
InvalidDevicePortsRanges:
summary: Invalid port ranges specified for devicePorts
value:
status: 400
code: OUT_OF_RANGE
message: "Invalid port ranges specified: devicePorts"
DurationOutOfRangeForQoSProfile:
summary: The requested duration is out of the allowed range for the specific QoS profile
value:
status: 400
code: OUT_OF_RANGE
message: "The requested duration is out of the allowed range for the specific QoS profile"
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/Generic403"
"409":
description: Conflict
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
example:
status: 409
code: CONFLICT
message: "Another session is created for the same device"
"500":
$ref: "#/components/responses/Generic500"
"501":
$ref: "#/components/responses/Generic501"
"503":
$ref: "#/components/responses/Generic503"
security:
- oAuth2ClientCredentials: []
- threeLegged:
- "qod-sessions-write"
/sessions/{sessionId}:
get:
tags:
- QoS Sessions
summary: Get QoS session information
description: Querying for QoS session resource information details
operationId: getSession
parameters:
- name: sessionId
in: path
description: Session ID that was obtained from the createSession operation
required: true
schema:
$ref: "#/components/schemas/SessionId"
responses:
"200":
description: Contains information about active session
content:
application/json:
schema:
$ref: "#/components/schemas/SessionInfo"
"400":
$ref: "#/components/responses/Generic400"
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/Generic403"
"404":
$ref: "#/components/responses/SessionNotFound404"
"500":
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
security:
- oAuth2ClientCredentials: []
- threeLegged:
- "qod-sessions-read"
delete:
tags:
- QoS Sessions
summary: 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`.
operationId: deleteSession
parameters:
- name: sessionId
in: path
description: Session ID that was obtained from the createSession operation
required: true
schema:
$ref: "#/components/schemas/SessionId"
responses:
"204":
description: Session deleted
"400":
$ref: "#/components/responses/Generic400"
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/Generic403"
"404":
$ref: "#/components/responses/SessionNotFound404"
"500":
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
security:
- oAuth2ClientCredentials: []
- threeLegged:
- "qod-sessions-delete"
/sessions/{sessionId}/extend:
post:
tags:
- QoS Sessions
summary: "Extend the duration of an active session"
description: |
Extend the overall duration of an active QoS session. If this operation is executed successfully, the new duration of the target session will be the original duration plus the additionally requested duration.
The new remaining duration of the QoS session shall not exceed the maximum remaining duration limit (currently fixed at 86,400 seconds) where the remaining duration is calculated as the difference between the `expiresAt` and current time when the request to extend the session duration is received. If this maximum limit would be exceeded, the overall duration shall be set such that the remaining duration is equal to this limit.
An example: A QoD session was originally created with duration 80,000 seconds. 10,000 seconds later, the developer requested to extend the session by 20,000 seconds.
- Original duration: 80,000 seconds
- Elapsed time: 10,000 seconds
- Remaining duration: 70,000 seconds
- New remaining duration: 86,400 seconds (the maximum allowed)
- New overall session duration: 96,400 seconds
operationId: extendQosSessionDuration
parameters:
- name: sessionId
in: path
description: Session ID that was obtained from the createSession operation
required: true
schema:
$ref: "#/components/schemas/SessionId"
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
content:
application/json:
schema:
$ref: "#/components/schemas/SessionInfo"
"400":
description: Invalid input for extendQosSessionDuration operation
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
Generic400:
summary: Some parameter combinations or parameter values provided are not schema compliant
value:
status: 400
code: INVALID_ARGUMENT
message: "Schema validation failed at ..."
InactiveSession:
summary: The target session is inactive
value:
status: 400
code: INVALID_ARGUMENT
message: "The target session is inactive"
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/Generic403"
"404":
$ref: "#/components/responses/SessionNotFound404"
"500":
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
security:
- oAuth2ClientCredentials: []
- threeLegged:
- "qod-sessions-write"
/qos-profiles:
get:
tags:
- QoS Profiles
summary: "Get All QoS Profiles"
description: |
Returns all QoS Profiles that match the given criteria.
If no criteria is given, all QoS Profiles are returned.
operationId: getQosProfiles
parameters:
- name: name
in: query
description: QoS Profile name
schema:
type: string
required: false
- name: status
in: query
schema:
$ref: '#/components/schemas/QosProfileStatusEnum'
required: false
responses:
"200":
description: Contains information about QoS Profiles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/QosProfile"
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/Generic403"
"404":
$ref: "#/components/responses/QosProfilesNotFound404"
"500":
$ref: "#/components/responses/QoSProfile500"
"503":
$ref: "#/components/responses/Generic503"
/qos-profiles/{name}:
get:
tags:
- QoS Profiles
summary: "Get QoS Profile for a given name"
operationId: getQosProfile
description: |
Returns a QoS Profile that matches the given name.
parameters:
- name: name
in: path
required: true
schema:
$ref: "#/components/schemas/QosProfileName"
responses:
"200":
description: Contains information about QoS Profiles
content:
application/json:
schema:
$ref: "#/components/schemas/QosProfile"
"400":
$ref: "#/components/responses/Generic400"
"401":
$ref: "#/components/responses/Generic401"
"403":
$ref: "#/components/responses/Generic403"
"404":
$ref: "#/components/responses/QosProfileNotFound404"
"500":
$ref: "#/components/responses/QoSProfile500"
"503":
$ref: "#/components/responses/Generic503"
components:
securitySchemes:
oAuth2ClientCredentials:
description: |
The QoD API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.example.com/oauth/token
scopes: {}
notificationsBearerAuth:
type: http
scheme: bearer
bearerFormat: "{$request.body#/webhook/notificationAuthToken}"
threeLegged:
type: oauth2
description: This API uses OAuth 2 with the authorization code grant flow.
flows:
authorizationCode:
authorizationUrl: https://api.example.com/oauth2/authorize
tokenUrl: https://api.example.com/oauth/token
scopes:
qod-sessions-read: Retrieval of QoS sessions
qod-sessions-write: Creation and update of QoS sessions
qod-sessions-delete: Deletion of QoS sessions
qod-profiles-read: Retrieval of QoS profiles
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"
webhook:
type: object
required:
- notificationUrl
properties:
notificationUrl:
type: string
format: uri
example: "https://application-server.com"
description: Allows asynchronous delivery of session related events
notificationAuthToken:
type: string
minLength: 20
maxLength: 256
example: "c8974e592c2fa383d4a3960714"
description: Authentication token for callback API
required:
- device
- applicationServer
- qosProfile
SessionInfo:
description: Session related information.
allOf:
- $ref: "#/components/schemas/BaseSessionInfo"
- type: object
properties:
sessionId:
$ref: "#/components/schemas/SessionId"
duration:
type: integer
format: int32
minimum: 1
example: 86400
startedAt:
type: integer
example: 1639479600
description: Timestamp of session start in seconds since Unix epoch
format: int64
expiresAt:
type: integer
example: 1639566000
description: Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch
format: int64
qosStatus:
$ref: "#/components/schemas/QosStatus"
messages:
type: array
items:
$ref: "#/components/schemas/Message"
required:
- sessionId
- duration
- startedAt
- expiresAt
- qosStatus
CreateSession:
description: Attributes required to create a session
allOf:
- $ref: "#/components/schemas/BaseSessionInfo"
- type: object
properties:
duration:
description: |
Session duration in seconds. Maximal value of 24 hours is used if not set.
After session is expired the, client will receive a `QOS_STATUS_CHANGED` event with
- `qosStatus` as `UNAVAILABLE`, and,
- `statusInfo` as `DURATION_EXPIRED`.
See notification callback.
type: integer
format: int32
minimum: 1
maximum: 86400
default: 86400
example: 86400
Port:
description: TCP or UDP port number
type: integer
minimum: 0
maximum: 65535
PortsSpec:
type: object
minProperties: 1
properties:
ranges:
type: array
minItems: 1
items:
type: object
required:
- from
- to
properties:
from:
$ref: "#/components/schemas/Port"
to:
$ref: "#/components/schemas/Port"
ports:
type: array
minItems: 1
items:
$ref: "#/components/schemas/Port"
example:
ranges:
- from: 5010
to: 5020
ports:
- 5060
- 5070
ExtendSessionDuration:
description: Attributes required to extend the duration of an active session
type: object
properties:
requestedAdditionalDuration:
description: |
Additional duration in seconds to be extended.
type: integer
format: int32
minimum: 1
maximum: 86399
example: 60
required:
- requestedAdditionalDuration
QosProfile:
description: |
Data type with attributes of a QosProfile
type: object
properties:
name:
$ref: "#/components/schemas/QosProfileName"
description:
description: |
A description of the QoS profile.
type: string
example: "QoS profile for video streaming"
status:
$ref: "#/components/schemas/QosProfileStatusEnum"
targetMinUpstreamRate:
description: |
This is the target minimum upstream rate for the QoS profile.
For 5G networks 3GPP Guaranteed Bit Rate (GBR) refers to a dedicated, fixed data rate assigned to
specific services, ensuring a minimum performance level. As per 3GPP TS 23.203,
GBR is a QoS parameter used to manage traffic classes in mobile networks. It
provides a stable data rate for latency-sensitive applications, such as voice calls or
video streaming, helping maintain a consistent user experience. When this attribute is set
this could imply that a GBR QCI is used, though mechanisms on the network can be used to
ensure a minimum performance level without using a GBR QCI.
The committed data rate allocated to specific services, ensuring a consistent level of
performance. For DOCSIS networks, the "Minimum Reserved Traffic Rate" is defined in the
DOCSIS 3.1 - MAC and Upper Layer Protocols Interface Specification"
and it ensures a consistent level of performance for specific services within the network.
allOf:
- $ref: "#/components/schemas/Rate"
maxUpstreamRate:
description: |
The maximum best effort data
allOf:
- $ref: "#/components/schemas/Rate"
maxUpstreamBurstRate:
description: |
When defined, this is the maximum upstream burst rate for the QoS profile, that will enable
the network to burst data at a higher rate than the maxUpstreamRate for a period of time.
allOf:
- $ref: "#/components/schemas/Rate"
targetMinDownstreamRate:
description: |
This is the target minimum downstream rate for the QoS profile.
For 5G networks 3GPP Guaranteed Bit Rate (GBR) refers to a dedicated, fixed data rate assigned to
specific services, ensuring a minimum performance level. As per 3GPP TS 23.203,
GBR is a QoS parameter used to manage traffic classes in mobile networks. It
provides a stable data rate for latency-sensitive applications, such as voice calls or
video streaming, helping maintain a consistent user experience. When this attribute is set
this could imply that a GBR QCI is used, though mechanisms on the network can be used to
ensure a minimum performance level without using a GBR QCI.
The committed data rate allocated to specific services, ensuring a consistent level of
performance. DOCSIS networks, the "Minimum Reserved Traffic Rate" is defined in the
DOCSIS 3.1 - MAC and Upper Layer Protocols Interface Specification"
and it ensures a consistent level of performance for specific services within the network.
allOf:
- $ref: "#/components/schemas/Rate"
maxDownstreamRate:
description: |
The maximum best effort rate
allOf:
- $ref: "#/components/schemas/Rate"
maxDownstreamBurstRate:
description: |
When defined, this is the maximum downstream burst rate for the QoS profile, that will enable
the network to burst data at a higher rate than the maxDownstreamRate for a period of time.
This can result in improved user experience when there is additional network capacity.
For instance, when a user is streaming a video, the network can burst data at a higher rate
to fill the buffer, and then return to the maxUpstreamRate once the buffer is full.
allOf:
- $ref: "#/components/schemas/Rate"
minDuration:
description: |
The shortest time period that this profile can be deployed.
allOf:
- $ref: "#/components/schemas/Duration"
maxDuration:
description: |
The maximum time period that this profile can be deployed.
NOTE: currently the duration within `sessionInfo` is limited to 86400 seconds (1 day).
The value of `maxDuration` shouldn't therefore exceed this time period. The limitation might be removed in later versions.
allOf:
- $ref: "#/components/schemas/Duration"
priority:
type: integer
example: 20
description: |
Priority levels allow efficient resource allocation and ensure optimal performance
for various services in each technology, with the highest priority traffic receiving
preferential treatment.
The lower value the higher priority.
Not all access networks use the same priority range, so this priority will be
scaled to the access network's priority range.
format: int32
minimum: 1
maximum: 100
packetDelayBudget:
description: |
The packet delay budget is the maximum allowable one-way latency between the customer's device
and the gateway from the operator's network to other networks. By limiting the delay, the network
can provide an acceptable level of performance for various services, such as voice calls,
video streaming, and data.
The end-to-end or round trip latency will be about two times this value plus the latency not controlled
by the operator
allOf:
- $ref: "#/components/schemas/Duration"
jitter:
description: |
The jitter requirement aims to limit the maximum variation in round-trip
packet delay for the 99th percentile of traffic, following ITU Y.1540
standards. It considers only acknowledged packets in a session, which are
packets that receive a confirmation of receipt from the recipient (e.g.,
using TCP). This requirement helps maintain consistent latency, essential
for real-time applications such as VoIP, video calls, and gaming.
allOf:
- $ref: "#/components/schemas/Duration"
packetErrorLossRate:
type: integer
description: |
The exponential power of the allowable error loss rate 10^(-N).
For instance 3 would be an error loss rate of 10 to the power of -3 (0.001)
For 5G network the 3GPP specification TS 23.203 defines the packet error loss rate QCI attribute. It
describes the Quality of Service (QoS) Class Identifier (QCI) parameters used to
differentiate traffic classes in mobile networks, ensuring appropriate resource
allocation and performance for various services.
The packet error loss rate is one of the QCI attributes, providing information on the
acceptable packet loss rate for a specific traffic class. This attribute helps maintain
the desired performance level for services like voice calls, video streaming, or data
transfers within the 3GPP mobile network.
format: int32
minimum: 1
maximum: 10
example: 3
required:
- name
- status
QosProfileName:
description: |
A unique name for identifying a specific QoS profile.
This may follow different formats depending on the service providers implementation.
Some options addresses:
- A UUID style string
- Support for predefined profiles QOS_S, QOS_M, QOS_L, and QOS_E
- A searchable descriptive name
type: string
example: QCI_1_voice
minLength: 3
maxLength: 256
format: string
pattern: "^[a-zA-Z0-9_.-]+$"
Rate:
type: object
properties:
value:
type: integer
example: 10
format: int32
minimum: 0
maximum: 1024
unit:
$ref: "#/components/schemas/RateUnitEnum"
Duration:
type: object
properties:
value:
type: integer
example: 12
format: int32
minimum: 1
unit:
allOf:
- $ref: "#/components/schemas/TimeUnitEnum"
- example: Minutes
TimeUnitEnum:
type: string
enum:
- Days
- Hours
- Minutes
- Seconds
- Milliseconds
- Microseconds
- Nanoseconds
QosProfileStatusEnum:
description: |
The current status of the QoS Profile
- `ACTIVE`- QoS Profile is available to be used
- `INACTIVE`- QoS Profile is not currently available to be deployed
- `DEPRECATED`- QoS profile is actively being used in a QoD session, but can not be deployed in new QoD sessions
type: string
enum:
- ACTIVE
- INACTIVE
- DEPRECATED
RateUnitEnum:
type: string
enum:
- bps
- kbps
- Mbps
- Gbps
- Tbps
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.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.qod.v0.qos-status-changed: '#/components/schemas/EventQosStatusChanged'
EventQosStatusChanged:
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`
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`
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, optionally prefixed with '+'.
type: string
pattern: '^\+?[0-9]{5,15}$'
example: "123456789"
DeviceIpv4Addr:
type: object
description: |
The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).