6 General aspects of APIs for 5G Media Streaming

26.5123GPP5G Media Streaming (5GMS)ProtocolsRelease 17TS

6.1 HTTP resource URIs and paths

The resource URI used in each HTTP request to the API provider shall have the structure defined in subclause 4.4.1 of TS 29.501 [22], i.e.:

{apiRoot}/{apiName}/{apiVersion}/{apiSpecificResourceUriPart}

with the following components:

– {apiRoot} shall be set as described in TS 29.501 [22].

– {apiName} shall be set as defined by the following clauses.

– {apiVersion} shall be set to "v2" in this release of the specification.

– {apiSpecificResourceUriPart} shall be set as described in the following clauses.

6.2 Usage of HTTP

6.2.1 HTTP protocol version

6.2.1.1 5GMS AF

Implementations of the 5GMS AF shall expose both HTTP/1.1 [24] and HTTP/2 [31] endpoints at interfaces M1 and M5, including support for the HTTP/2 starting mechanisms specified in section 3 of RFC 7540 [31]. In both protocol versions, TLS [29] shall be supported and HTTPS interactions should be used on these interfaces in preference to cleartext HTTP.

The 5GMS Application Provider may use any supported HTTP protocol version at interface M1.

The Media Session Handler may use any supported HTTP protocol version at interface M5.

All responses from the 5GMS AF that carry a message body shall include a strong entity tag in the form of an ETag response header and a modification timestamp in the form of a Last-Modified response header.

All endpoints shall support the conditional HTTP requests If-none-Match and If-Modified-Since.

6.2.1.2 5GMS AS

Implementations of the 5GMS AS shall expose HTTP/1.1 [24] endpoints at interfaces M2 and M4 and may additionally expose HTTP/2 [31] endpoints at these interfaces. In both protocol versions, TLS [30] shall be supported and HTTPS interactions should be used on these interfaces in preference to cleartext HTTP.

For pull-based content ingest, the 5GMS Application Provider shall expose an HTTP/1.1-based origin endpoint to the 5GMSd AS at interface M2 and may additionally expose an HTTP/2-based origin endpoint.

For push-based content ingest, the 5GMS Application Provider may use any supported HTTP protocol version at interface M2.

The Media Stream Handler may use any supported HTTP protocol version at interface M4.

6.2.2 HTTP message bodies for API resources

The OpenAPI [23] specification of HTTP messages and their content bodies is contained in Annex C.

6.2.3 Usage of HTTP headers

6.2.3.1 General

Standard HTTP headers shall be used in accordance with clause 5.2.2 of TS 29.500 [21] for both HTTP/1.1 and HTTP/2 messages.

6.2.3.2 User Agent identification

6.2.3.2.1 Media Stream Handler identification

The Media Stream Handler in the 5GMSd Client shall identify itself to the 5GMS AS at interface M4 using a User-Agent request header (see section 5.3.3 of RFC 7231 [25]) that should include the product token 5GMSdMediaPlayer optionally suffixed with a product-version.

The Media Stream Handler may additionally supply a comment element in the User-Agent request header containing a vendor-specific identification string.

6.2.3.2.2 Media Session Handler identification

The Media Session Handler in the 5GMS Client shall identify itself to the 5GMSd AF at interface M5d using a User-Agent request header (see section 5.3.3 of RFC 7231 [25]) in which the first element shall be a product identified by the token 5GMSdMediaSessionHandler (or 5GMSuMediaSessionHandler) and optionally suffixed with a product-version.

The Media Session Handler may additionally supply a comment element in the User-Agent request header containing a vendor-specific identification string.

6.2.3.3 Server identification

6.2.3.3.1 5GMSd AF identification

The 5GMSd AF shall identify itself using a Server response header (see section 7.4.2 of RFC 7231 [25]) of the following form:

5GMSdAF-{FQDN}/{implementationSpecificSuffix}

where {FQDN} shall be the Fully-Qualified Domain Name of the 5GMSd AF exposed to the requesting client, and {implementationSpecificSuffix} shall be determined by the implementation.

6.2.3.4 Support for conditional HTTP GET requests

All responses from the 5GMS AF that carry a resource message body shall include:

– a strong entity tag for the resource, conveyed in an ETag response header,

– a resource modification timestamp, conveyed in a Last-Modified response header, and

– a predicted time-to-live period for the resource, conveyed in a Cache-Control: max-age response header.

All API endpoints on the 5GMS AF that expose the HTTP GET method shall support conditional requests using the If-None-Match and If-Modified-Since request headers. API clients should not attempt to revalidate their cached copy of a resource using a conditional GET request before the indicated time-to-live period has elapsed.

6.2.3.5 Support for conditional HTTP POST, PUT, PATCH and DELETE requests

All API endpoints on the 5GMS AF that expose the HTTP POST, PUT, PATCH or DELETE methods shall support conditional requests using the If-Match request header. The API client should supply a strong entity tag in an ETag request header when invoking any of these HTTP methods.

6.3 HTTP response codes

Guidelines for error responses to the invocation of APIs of NF services are specified in clause 4.8 of TS 29.501 [22]. API-specific error responses are specified in the respective technical specifications.

6.4 Common API data types

6.4.1 General

The data types defined in this clause are intended to be used by more than one of the 5GMS APIs.

6.4.2 Simple data types

Table 6.4.2-1 below specifies common simple data types used within the 5GMS APIs, including a short description of each. In cases where types from other specifications are reused, a reference is provided.

Table 6.4.2-1: Simple data types

Type name	Type definition	Description	Reference
ResourceId	string	String chosen by the 5GMS AF to serve as an identifier in a resource URL.
Uri	string	Uniform Resource Identifier conforming with the URI Generic Syntax.	TS 29.571 [12] table 5.2.2‑1
Url	string	Uniform Resource Locator, conforming with the URI Generic Syntax.	IETF RFC 3986 [41]
Percentage	number	A percentage expressed as a floating point value between 0.0 and 100.0 (inclusive).
DurationSec	integer	An unsigned integer identifying a period of time expressed in units of seconds.	TS 29.571 [12] table 5.2.2‑1
DateTime	string	An absolute date and time expressed using the OpenAPI date-time string format.	TS 29.571 [12] table 5.2.2‑1
IPv4Addr	string	IPv4 address formatted in "dotted decimal" notation	TS 29.571 [12] table 5.2.2‑1.
IPv6Addr	string	IPv6 address formatted in colon-separated hexadecimal quartet notation.	TS 29.571 [12] table 5.2.2‑1.
Uinteger	Integer	Unsigned integer.	TS 29.571 [12] table 5.2.2‑1.

6.4.3 Structured data types

6.4.3.1 IpPacketFilterSet type

Table 6.4.3.1-1: Definition of type IpPacketFilterSet

Property name	Data type	Cardinality	Usage	Description
srcIp	String	0..1		Source IP address or IPv6 prefix.
dstIp	String	0..1		Destination IP address or IPv6 prefix.
protocol	Integer	0..1		Protocol.
srcPort	Integer	0..1		Source port.
dstPort	Integer	0..1		Destination Port.
toSTc	String	0..1		Type of Service (TOS) (IPv4) / Traffic class (IPv6) and Mask.
flowLabel	Integer	0..1		Flow Label (IPv6).
spi	Integer	0..1		Security Parameter Index.
direction	String	1..1		Packet Filter Set Direction.

6.4.3.2 ServiceDataFlowDescription type

Table 6.4.3.2-1: Definition of type ServiceDataFlowDescription

Property name	Data type	Cardinality	Usage	Description
flowDescription	IpPacketFilterSet	0..1		Service Data Flow Description.
domainName	String	0..1		FQDN of the 5GMS AS.

An object of type ServiceDataFlowDescription shall contain at least one property.

6.4.3.3 M5QoSSpecification type

Table 6.4.3.2-1: Definition of type M5QoSSpecification

Property name	Data type	Cardinality	Usage	Description
marBwDlBitRate	BitRate	1..1		Maximum requested bit rate for the Downlink.
marBwUlBitRate	BitRate	1..1		Maximum requested bit rate for the Uplink.
minDesBwDlBitRate	BitRate	0..1		Minimum desired bit rate for the Downlink.
minDesBwUlBitRate	BitRate	0..1		Minimum desired bit rate for the Uplink.
mirBwDlBitRate	BitRate	1..1		Minimum requested bit rate for the Downlink.
mirBwUlBitRate	BitRate	1..1		Minimum requested bandwidth for the Uplink.
desLatency	Integer	0..1		Desire Latency.
desLoss	Integer	0..1		Desired Loss Rate.

6.4.3.4 M1QoSSpecification type

Table 6.4.3.2-1: Definition of type M1QoSSpecification

Property name	Data type	Cardinality	Usage	Description
qosReference	String	0..1		As defined in clause 5.6.2.7 of TS 29.514 [34].
maxBtrUl	BitRate	0..1	RO	Maximum Bitrate Uplink.
maxBtrDl	BitRate	0..1	RO	Maximum Bitrate Downlink.
maxAuthBtrUl	BitRate	0..1	RW	Maximum Authorized Bitrate Uplink by 5GMS Application Provider.
maxAuthBtrDl	BitRate	0..1	RW	Maximum Authorized Bitrate Downlink by 5GMS Application Provider.
defPacketLossRateDl	Integer	0..1		Default packet loss rate for Downlink.
defPacketLossRateUl	Integer	0..1		Default packet loss rate for Uplink.

6.4.3.5 ChargingSpecification type

Table 6.5.3.2-1: Definition of type ChargingSpecification

Property name	Data type	Cardinality	Usage	Description
sponId	SponId	0..1		As defined in clause 5.6.2.3 of TS 29.514 [34].
sponStatus	SponsoringStatus	0..1
gpsi	Array(Gpsi)	0..1		List of UEs permitted to instantiate this Policy Template.

6.4.3.6 TypedLocation type

Table 6.4.3.6-1: Definition of TypedLocation type

Property name	Data type	Cardinality	Description
locationIdentifierType	CellIdentifierType	1..1	The type of cell location present in the location property.
location	string	1..1	Identifies the cell location.

6.4.3.7 OperationSuccessResponse type

The data model for the OperationSuccessResponse type is specified in table 6.4.3.7-1 below:

Table 6.4.3.7-1: Definition of OperationSuccessResponse type

Property name	Type	Cardinality	Description
success	Boolean	1..1	Indicates whether an operation was successful (TRUE) or not (FALSE).
reason	String	0..1	Optional explanation of the success or otherwise of the operation.

6.4.3.8 EdgeProcessingEligibilityCriteria type

The EdgeProcessingEligibilityCriteria type is specified in table 6.4.3.8-1 below:

Table 6.4.3.8-1: Definition of EdgeProcessingEligibilityCriteria type

Property name	Type	Cardinality	Description
service‌DataFlow‌Descriptions	array(Service‌DataFlow‌Description)	1..1	A set of service data flow descriptions that are to be used as triggers for invoking edge media processing (see NOTE 1). If the set is empty, edge media processing may be invoked for an otherwise eligible media stream session on any service data flow. Valid ServiceDataFlowDescription elements: – domainName – flowDescription.dstIp and flowDescription.dstPort – flowDescription.toSTc – flowDescription.flowLabel Other ServiceDataFlowDescription settings shall be rejected by the 5GMS AF.
ueLocations	array(Location‌Area5G)	1..1	A set of geographical areas in which edge media processing is to be triggered when a UE is present. If the set is empty, edge media processing may be invoked for an otherwise eligible media stream session in any location.
timeWindows	array(TimeWindow)	1..1	Edge media processing is triggered when the media streaming session is taking place during one of the indicated time windows. If the set is empty, edge media processing may be invoked for an otherwise eligible media stream session at any time.
appRequest	boolean	1..1	When set TRUE, edge media processing is to be triggered based on application request only.
NOTE 1: The usage of these fields to influence route selection and EAS re-selection are for future study. NOTE 2: Data types LocationArea5G and TimeWindow are defined in TS 24.558 [42].

6.4.3.9 EndpointAddress type

Table 6.4.3.9-1: Definition of EndpointAddress type

Property name	Type	Cardinality	Description
ipv4Addr	Ipv4Addr	0..1	IPv4 address of the endpoint.
ipv6Addr	Ipv6Addr	0..1	IPv6 address of the endpoint.
portNumber	Uinteger	1	Port number of the endpoint.
NOTE: At least one of ipv4Addr or ipv6Addr shall be present.

6.4.4 Enumerated data types

6.4.4.1 CellIdentifierType enumeration

The data model for the CellIdentifierType enumeration which indicates the type of cell identifier as defined in TS 23.003 [7], is specified in Table 6.4.4.1-1 below:

Table 6.4.4.1‑1: Definition of CellIdentifierType enumeration

Enumeration value	Description
CGI	Cell Global Identification.
ECGI	E-UTRAN Cell Global Identification.
NCGI	NR Cell Global Identity.

6.4.4.2 SdfMethod enumeration

The data model for the SdfMethod enumeration is specified in table 6.4.4.2-1 below:

Table 6.4.4.2‑1: Definition of SdfMethod enumeration

Enumeration value	Description
5_TUPLE	The Media Session Handler shall use 5-Tuples for Service Data Flow descriptions. The 5‑Tuple shall not contain a wildcard.
2_TUPLE	The Media Session Handler shall use a 2-Tuple of UE IP and Server IP as Service Data Flow Description.
TYPE_OF_SERVICE_MARKING	The Media Session Handler shall apply Type of Service (ToS) marking to the Service Data Flow.
FLOW_LABEL	The Media Session Handler shall apply IPv6 flow label marking and provide the IPv6 flow label of the Service Data Flow.
DOMAIN_NAME	The Media Session Handler shall provide the domain name of the 5GMSd AS.

6.4.4.3 ProvisioningSessionType enumeration

The data model for the ProvisioningSessionType enumeration is specified in Table 6.4.4.3-1 below:

Table 6.4.4.3‑1: Definition of ProvisioningSessionType enumeration

Enumeration value	Description
DOWNLINK	Downlink media streaming
UPLINK	Uplink media streaming

6.4.4.4 EASRelocationTolerance enumeration

The EASERelocationTolerance enumeration is specified in table 6.4.4.4-1 below:

Table 6.4.4.4‑1: Definition of EASRelocationTolerance enumeration

Enumeration value	Description
RELOCATION_UNAWARE	The application is not aware of any EAS relocation that may happen. Relocation procedures may be executed without any restrictions.
RELOCATION_TOLERANT	The application may tolerate EAS relocation, but requirements for the relocation procedure must be met. An application context may need to be transferred.
RELOCATION_INTOLERANT	The application does not tolerate relocation.

6.4.4.4 CacheStatus enumeration

Table 6.4.4.4‑1: Definition of CacheStatus enumeration

Enumeration value	Description
HIT	The requested object is present in the 5GMS AS cache and is still valid.
MISS	The requested object is not present in the 5GMS AS cache.
EXPIRED	The requested object is present in the 5GMS AS cache but is stale.

6.5 Explanation of API data model notation

The data models in the following API clauses are specified using the following notational conventions:

1. Data models are expressed as an unordered list of JSON properties [38] with one property defined in each row of the data model table.

2. The Data type column defines the type of the property, according to JSON notation [38].

3. The keyword "Array" in the Data type column indicates that zero or more elements of the data type in brackets are included. The number of elements in the array may additionally be constrained by normative text in the Description column.

4. The Cardinality column defines whether a property is optional or mandatory. An array with cardinality 0 indicates that the array property is optional in the data structure. An array with cardinality 1 indicates that the property is mandatory in the data structure, even when the array is empty.

5. The keyword "Object" in the Data type column indicates a structured sub-object of an unnamed type whose properties are defined inline in the indented table rows immediately afterwards. The "Object" type may be combined with the "Array" type.

6. In the case of data types specifying RESTful resources, the additional Usage column defines the property behaviour for each CRUD Operation as follows:

– "C" (Create), "R" (Read) and "U" (Update) refers to the CRUD procedure during which the property is present in the resource type. (The Delete operation never takes any input data type.)

– "RO" signifies a read-only property. Only the API provider function is permitted to modify the property value. The API invoker can only read the value.

– "RW" signifies a read/write property. The API provider and API invoker may both modify the property value.

7. An additional read-only property is included at the start of all data models defining resources that are members of a RESTful collection. This property is populated with the unique identifier of the resource within its parent collection, and corresponds to the leaf path element in the RESTful URL of that resource.