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. 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-tmus.n externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ security: - oAuth2ClientCredentials: [] servers: - url: https://api-teststg.t-mobile.com/qod/v0 description: Staging - url: https://naas.t-mobile.com/qod/v0 description: Production 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" means the QoS Session created successfully. Webhook notification support: 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`. A `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` will send for below scenairos. * if the delete request is triggered and successfully processed * if the network terminates the session before the requested duration expired operationId: createSession parameters: - name: Authorization in: header description: The Bearer Token used for authorization of the request. example: Bearer required: true schema: type: string - name: X-Authorization in: header description: PoP token generated for every request required: true schema: type: string - name: x-correlator in: header description: The transaction ID is GUID. Represents the API transaction, for use in debugging. example: 233b55ed-4a48-4f33-9efe-6fc277f66e8d required: false schema: type: string 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: DeviceMissing: summary: Device PhoneNumber is missing/invalid value: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: device.phoneNumber" QosProfileMissing: summary: Qos profile is missing/invalid value: status: 400 code: INVALID_ARGUMENT message: "Expected property is missing: qosProfile" DurationOutOfRangeForQoSProfile: summary: The requested duration is out of the allowed range for the specific QoS profile value: status: 400 code: INVALID_INPUT message: "The requested duration is out of the allowed range 60-86400 seconds" "401": $ref: "#/components/responses/Generic401" "403": description: Forbidden for createSession operation content: application/json: schema: $ref: "#/components/responses/Generic403" examples: CScallFailedWithQuotaLimitError: summary: In case of Charging failure with QUOTA_LIMIT_REACHED error value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: The requested duration exceeds Quota Limit for this ." CScallFailedWithEndUserServiceDeniedError: summary: In case of application doesnt have necessary authorization for this phoneNumber value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: The application does not have necessary authorization for this phoneNumber." QoSProfileMissinginAuthZDb: summary: The requested QoS profile is not present in AuthZ DB value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: The application is not authorized to update with this Profile." MsisdnNotAssociatedWithApp: summary: Create a session with MSSISDN that isn’t associated with appclient id value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: The application is not authorized to update ." QosProfileNotSubscribed: summary: Create a session with QOS profile that developer app isn’t subscribed in devedge value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: The application is not subscribed with this Profile." "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: SessionExistsForSameMsisdn: summary: Session exists for same msisdn value: status: 409 code: CONFLICT message: "A session is already active for this MSISDN" DuplicateRequestforSession: summary: Duplicate request for same msisdn when previous request is in progress value: status: 409 code: CONFLICT message: "Previous Create session request for is already being processed." "500": description: Internal content: application/json: schema: $ref: "#/components/responses/Generic500" examples: ChargingFails: summary: Failed due to Onboarding account setup in the internal systems. value: status: 500 code: INTERNAL message: "Internal server error: Please contact T-Mobile account manager." SouthBoundCallFailure: summary: If any Southbound api call fails/returns an exception for any reason value: status: 500 code: INTERNAL message: "Internal server error: Please try again after 1 minute." "502": description: Bad Gateway content: application/json: schema: $ref: "#/components/responses/Generic502" examples: RequiredContextNotPassed: summary: From Gateway to Backend, required context not passed value: status: 502 code: BAD_GATEWAY message: "Unexpected Server Error – please retry after an hour" 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" - name: Authorization in: header description: The Bearer Token used for authorization of the request. example: Bearer required: true schema: type: string - name: X-Authorization in: header description: PoP token generated for every request required: true schema: type: string - name: x-correlator in: header description: The transaction ID is GUID. Represents the API transaction, for use in debugging. example: 233b55ed-4a48-4f33-9efe-6fc277f66e8d required: false schema: type: string responses: "200": description: Contains information about active session content: application/json: schema: $ref: "#/components/schemas/SessionInfo" "401": $ref: "#/components/responses/Generic401" "404": $ref: "#/components/responses/SessionNotFound404" "500": $ref: "#/components/responses/Generic500" security: - oAuth2ClientCredentials: [] - threeLegged: - "qod-sessions-read" delete: tags: - QoS Sessions summary: Delete a QoS session description: | Release resources related to QoS session operationId: deleteSession parameters: - name: sessionId in: path description: Session ID that was obtained from the createSession operation required: true schema: $ref: "#/components/schemas/SessionId" - name: Authorization in: header description: The Bearer Token used for authorization of the request. example: Bearer required: true schema: type: string - name: X-Authorization in: header description: PoP token generated for every request required: true schema: type: string - name: x-correlator in: header description: The transaction ID is GUID. Represents the API transaction, for use in debugging. example: 233b55ed-4a48-4f33-9efe-6fc277f66e8d required: false schema: type: string responses: "204": description: Session deleted "401": $ref: "#/components/responses/Generic401" "404": $ref: "#/components/responses/SessionNotFound404" "500": $ref: "#/components/responses/Generic500" security: - oAuth2ClientCredentials: [] - threeLegged: - "qod-sessions-delete" 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 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 - 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: 60 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 - startedAt - duration - expiresAt - qosStatus CreateSession: description: Attributes required to create a session allOf: - $ref: "#/components/schemas/BaseSessionInfo" - type: object properties: duration: description: | Session duration in seconds. Minimum value is 60 seconds and Maximal value of 24 hours is used if not set. type: integer format: int32 minimum: 60 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 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_VC, QOS_XR, QOS_RVM, QOS_POSALE and QOS_BROADCAST - A searchable descriptive name type: string example: QOS_VC minLength: 3 maxLength: 256 format: string pattern: "^[a-zA-Z0-9_.-]+$" 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 required: - phoneNumber 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). 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": "84.125.93.10", "publicPort": 59765 } SingleIpv4Addr: description: A single IPv4 address with no subnet mask type: string format: ipv4 example: "84.125.93.10" 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 session 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: "192.168.0.1/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: type: object properties: severity: description: Message severity type: string enum: ["INFO", "WARNING"] description: description: Detailed message text type: string required: - severity - description QosStatus: description: | The current status of the requested QoS session. The status can be one of the following: * `AVAILABLE` - The requested QoS has been provided by the network type: string enum: - AVAILABLE ErrorInfo: 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 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' responses: Generic400: description: Invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 400 code: INVALID_ARGUMENT message: "Schema validation failed at ..." Generic401: description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 401 code: UNAUTHENTICATED message: "Request not authenticated due to missing, invalid, or expired credentials." Generic502: description: Bad Gateway content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 502 code: BAD_GATEWAY message: "Unexpected Server Error – please retry after an hour" Generic403: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" SessionNotFound404: description: Session not found content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 404 code: NOT_FOUND message: "Session Id does not exist" Generic500: description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 500 code: INTERNAL message: "Internal server error: ..." Generic501: description: Not Implemented content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 501 code: NOT_IMPLEMENTED message: "Service not implemented for the specified user device" Generic503: description: Service unavailable content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 503 code: UNAVAILABLE message: "Service unavailable" examples: QOS_STATUS_CHANGED_EXAMPLE: summary: QoS status changed value: id: 83a0d986-0866-4f38-b8c0-fc65bfcda452 source: 'https://api.example.com/qod/v0/sessions/123e4567-e89b-12d3-a456-426614174000' specversion: '1.0' type: 'org.camaraproject.qod.v0.qos-status-changed' time: '2021-12-12T00:00:00Z' data: sessionId: '123e4567-e89b-12d3-a456-426614174000' qosStatus: 'UNAVAILABLE' statusInfo: 'DURATION_EXPIRED'

API Reference for QoD Sessions