5.9 IPTVConfiguration API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

5.9.1 Resources

5.9.1.1 Overview

All resource URIs of this API should have the following root:

{apiRoot}/3gpp-iptvconfiguration/v1

"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-iptvconfiguration" and "apiVersion" shall be set to "v1" for the current version defined in the present document. All resource URIs in the clauses below are defined relative to the above root URI.

This clause describes the structure for the Resource URIs as shown in figure 5.9.1.1-1 and the resources and HTTP methods used for the IPTVConfiguration API.

Figure 5.9.1.1-1: Resource URI structure of the IPTVConfiguration API

Table 5.9.1.1-1 provides an overview of the resources and HTTP methods applicable for the IPTVConfiguration API.

Table 5.9.1.1-1: Resources and methods overview

Resource name	Resource URI	HTTP method	Description
IPTV Configurations	/{afId}/configurations	GET	Read all configurations for a given AF
		POST	Create a new IPTV configuration
Individual IPTV Configuration	/{afId}/configurations/{configurationId}	GET	Read an existing configuration identified by {configurationId}
		PUT	Modify all of the properties of an existing configuration identified by {configurationId}
		PATCH	Modify some of the properties of an existing configuration identified by {configurationId}
		DELETE	Delete a configuration identified by {configurationId}

5.9.1.2 Resource: IPTV Configurations

5.9.1.2.1 Introduction

This resource allows a AF to read all active IPTV configurations for the given AF, or create an new individual IPTV configuration in the NEF.

5.9.1.2.2 Resource Definition

Resource URI: {apiRoot}/3gpp-iptvconfiguration/v1/{afId}/configurations

This resource shall support the resource URI variables defined in table 5.9.1.2.2-1.

Table 5.9.1.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	Clause 5.2.4 of 3GPP TS 29.122 [4].
afId	string	Identifier of the AF.

5.9.1.2.3 Resource Methods

5.9.1.2.3.1 General

The following clauses specify the resource methods supported by the resource as described in clause 5.9.1.2.2.

5.9.1.2.3.2 GET

The GET method allows to read all active configurations for a given AF. The AF shall initiate the HTTP GET request message and the NEF shall respond to the message.

This method shall support the URI query parameters specified in table 5.9.1.2.3.2-1.

Table 5.9.1.2.3.2-1: URI query parameters supported by the GET method on this resource

Name	Data type	P	Cardinality	Description
N/A

This method shall support the request data structures specified in table 5.9.1.2.3.2-2 and the response data structures and response codes specified in table 5.9.1.2.3.2-3.

Table 5.9.1.2.3.2-2: Data structures supported by the GET Request Body on this resource

Data type	P	Cardinality	Description
N/A

Table 5.9.1.2.3.2-3: Data structures supported by the GET Response Body on this resource

Data type	P	Cardinality	Response codes	Description
array(IptvConfigData)	M	0..N	200 OK	All the configuration information for the AF in the request URI are returned.
N/A			307 Temporary Redirect	Temporary redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
N/A			308 Permanent Redirect	Permanent redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.9.1.2.3.2-4: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.9.1.2.3.2-5: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.9.1.2.3.3 POST

The POST method creates a new resource to individual IPTV configuration for a given AF. The AF shall initiate the HTTP POST request message and the NEF shall respond to the message. The NEF shall construct the URI of the created resource.

This method shall support the request data structures specified in table 5.9.1.2.3.3-1 and the response data structures and response codes specified in table 5.9.1.2.3.3-2.

Table 5.9.1.2.3.3-1: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
IptvConfigData	M	1	Parameters to create an IPTV Configuration resource.

Table 5.9.1.2.3.3-2: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
IptvConfigData	M	1	201 Created	The configuration resource was created successfully. The URI of the created resource shall be returned in the "Location" HTTP header.
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.9.1.2.3.3-3: Headers supported by the 201 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	Contains the URI of the newly created resource, according to the structure: {apiRoot}/3gpp-iptvconfiguration/v1/{afId}/configurations/{configurationId}

5.9.1.3 Resource: Individual IPTV Configuration

5.9.1.3.1 Introduction

This resource allows a AF to read, update or delete an existing IPTV Configuration.

5.9.1.3.2 Resource Definition

Resource URI: {apiRoot}/3gpp-iptvconfiguration/v1/{afId}/configurations/{configurationId}

This resource shall support the resource URI variables defined in table 5.9.1.3.2-1.

Table 5.9.1.3.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	Clause 5.2.4 of 3GPP TS 29.122 [4].
afId	string	Identifier of the AF.
configurationId	string	Identifier of the configuration resource.

5.9.1.3.3 Resource Methods

5.9.1.3.3.1 General

The following clauses specify the resource methods supported by the resource as described in clause 5.9.1.3.2.

5.9.1.3.3.2 GET

The GET method allows to read the active configuration for a given AF and subscription Id. The AF shall initiate the HTTP GET request message and theNEF shall respond to the message.

This method shall support the URI query parameters specified in table 5.9.1.3.3.2-1.

Table 5.9.1.3.3.2-1: URI query parameters supported by the GET method on this resource

Name	Data type	P	Cardinality	Description
N/A

This method shall support the request data structures specified in table 5.9.1.3.3.2-2 and the response data structures and response codes specified in table 5.9.1.3.3.2-3.

Table 5.9.1.3.3.2-2: Data structures supported by the GET Request Body on this resource

Data type	P	Cardinality	Description
N/A

Table 5.9.1.3.3.2-3: Data structures supported by the GET Response Body on this resource

Data type	P	Cardinality	Response codes	Description
IptvConfigData	M	1	200 OK	The information for the configuration in the request URI are returned.
N/A			307 Temporary Redirect	Temporary redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
N/A			308 Permanent Redirect	Permanent redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.9.1.3.3.2-4: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.9.1.3.3.2-5: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.9.1.3.3.3 PUT

The PUT method modifies an existing resource to update a configuration. The AF shall initiate the HTTP PUT request message and the NEF shall respond to the message.

This method shall support the request data structures specified in table 5.9.1.3.3.3-1 and the response data structures and response codes specified in table 5.9.1.3.3.3-2.

Table 5.9.1.3.3.3-1: Data structures supported by the PUT Request Body on this resource

Data type	P	Cardinality	Description
IptvConfigData	M	1	Modify an existing configuration.

Table 5.9.1.3.3.3-2: Data structures supported by the PUT Response Body on this resource

Data type	P	Cardinality	Response codes	Description
IptvConfigData	M	1	200 OK	The configuration resource was updated successfully.
n/a			204 No Content	The configuration resource was updated successfully.
N/A			307 Temporary Redirect	Temporary redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
N/A			308 Permanent Redirect	Permanent redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.9.1.3.3.3-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.9.1.3.3.3-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.9.1.3.3.4 DELETE

The DELETE method deletes an existing individual configuration for a given AF. The AF shall initiate the HTTP DELETE request message and the NEF shall respond to the message.

This method shall support the URI query parameters specified in table 5.9.1.3.3.4-1.

Table 5.9.1.3.3.4-1: URI query parameters supported by the DELETE method on this resource

Name	Data type	P	Cardinality	Description
N/A

This method shall support the request data structures specified in table 5.9.1.3.3.4-2 and the response data structures and response codes specified in table 5.9.1.3.3.4-3.

Table 5.9.1.3.3.4-2: Data structures supported by the DELETE Request Body on this resource

Data type	P	Cardinality	Description
N/A

Table 5.9.1.3.3.4-3: Data structures supported by the DELETE Response Body on this resource

Data type	P	Cardinality	Response codes	Description
N/A			204 No Content	The configuration resource was terminated successfully.
N/A			307 Temporary Redirect	Temporary redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
N/A			308 Permanent Redirect	Permanent redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.9.1.3.3.4-4: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.9.1.3.3.4-5: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.9.1.3.3.5 PATCH

The PATCH method allows to change some properties of an existing resource to update a configuration. The AF shall initiate the HTTP PATCH request message and the NEF shall respond to the message.

This method shall support the request data structures specified in table 5.9.1.3.3.5-1 and the response data structures and response codes specified in table 5.9.1.3.3.5-2.

Table 5.9.1.3.3.5-1: Data structures supported by the PATCH Request Body on this resource

Data type	P	Cardinality	Description
IptvConfigDataPatch	M	1	Partial update an existing configuration.

Table 5.9.1.3.3.5-2: Data structures supported by the PATCH Response Body on this resource

Data type	P	Cardinality	Response codes	Description
IptvConfigData	M	1	200 OK	The configuration resource was updated successfully.
n/a			204 No Content	The configuration resource was updated successfully.
N/A			307 Temporary Redirect	Temporary redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
N/A			308 Permanent Redirect	Permanent redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE: The mandatory HTTP error status codes for the PATCH method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.9.1.3.3.5-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.9.1.3.3.5-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.9.1A Notifications

Notifications are not applicable to this API.

5.9.2 Data Model

5.9.2.1 General

This clause specifies the application data model supported by the IPTVConfiguration API.

Table 5.9.2.1-1 specifies the data types defined for the IPTVConfiguration API.

Table 5.9.2.1-1: IPTVConfiguration API specific Data Types

Data type	Clause defined	Description	Applicability
AccessRightStatus	5.9.2.4.3	Represents the access right status for parameter provision.
IptvConfigData	5.9.2.3.2	Represents an individual IPTV Configuration resource.
IptvConfigDataPatch	5.9.2.3.4	Represents the parameters to request the modification of an IPTV Configuration resource.
MulticastAccessControl	5.9.2.3.3	Represents multicast address access control information.

5.9.2.2 Reused data types

The data types reused by the IPTVConfiguration API from other specifications are listed in table 5.9.2.2-1.

Table 5.9.2.2-1: Re-used Data Types

Data type	Reference	Comments
Dnn	3GPP TS 29.571 [8]	Identifies a DNN.
ExternalGroupId	3GPP TS 29.122 [4]	External Group Identifier for a user group.
Gpsi	3GPP TS 29.571 [8]	Identifies a GPSI.
Ipv4Addr	3GPP TS 29.571 [8]	Identifies an IPv4 address.
Ipv6Addr	3GPP TS 29.571 [8]	Identifies an IPv6 address.
Link	3GPP TS 29.122 [4]
MtcProviderInformation	3GPP TS 29.571 [8]	Indicates MTC provider information.
Snssai	3GPP TS 29.571 [8]	Identifies the S-NSSAI.
SupportedFeatures	3GPP TS 29.571 [8]	Used to negotiate the applicability of the optional features defined in table 5.9.3-1.

5.9.2.3 Structured data types

5.9.2.3.1 Introduction

This clause defines the structured data types to be used in resource representations.

5.9.2.3.2 Type: IptvConfigData

Table 5.9.2.3.2-1: Definition of type IptvConfigData

Attribute name	Data type	P	Cardinality	Description	Applicability
self	Link	C	0..1	Identifies the individual IPTV configuration resource URI. Shall be present in the HTTP GET response when reading all the configurations for an AF.
gpsi	Gpsi	C	0..1	Identifies GPSI. (NOTE)
exterGroupId	ExternalGroupId	C	0..1	Represents a group of users. (NOTE)
afAppId	string	M	1	Identifies an application.
dnn	Dnn	O	0..1	Identifies a DNN, a full DNN with both the Network Identifier and Operator Identifier, or a DNN with the Network Identifier only.
snssai	Snssai	O	0..1	Identifies an S-NSSAI.
multiAccCtrls	map(MulticastAccessControl)	M	1..N	Identifies a list of multicast address access control information. Any string value can be used as a key of the map.
mtcProviderId	MtcProviderInformation	O	0..1	Indicates MTC provider information.
suppFeat	SupportedFeatures	M	1	Indicates the negotiated supported features.
NOTE: Only one of the "gpsi" or "exterGroupId" attribute shall be provided.

5.9.2.3.3 Type: MulticastAccessControl

Table 5.9.2.3.3-1: Definition of type MulticastAccessControl

Attribute name	Data type	P	Cardinality	Description	Applicability
srcIpv4Addr	Ipv4Addr	O	0..1	Identifies the source IPv4 address of IPTV multicast channel.
srcIpv6Addr	Ipv6Addr	O	0..1	Identifies the source IPv6 address of IPTV multicast channel.
multicastV4Addr	Ipv4Addr	O	0..1	Identifies the multicast IPv4 address of IPTV multicast channel. (NOTE)
multicastV6Addr	Ipv6Addr	O	0..1	Identifies the multicast IPv6 address of IPTV multicast channel. (NOTE)
accStatus	AccessRightStatus	M	1	Represents access right status of the multicast channel.
NOTE: At least one of the "multicastV4Addr" or "multicastV6Addr" attribute shall be provided.

5.9.2.3.4 Type: IptvConfigDataPatch

Table 5.9.2.3.4-1: Definition of type IptvConfigDataPatch

Attribute name	Data type	P	Cardinality	Description	Applicability
multiAccCtrls	map(MulticastAccessControl)	O	1..N	Identifies a list of multicast address access control information. Any string value can be used as a key of the map.

5.9.2.4 Simple data types and enumerations

5.9.2.4.1 Introduction

This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.

5.9.2.4.2 Simple data types

The simple data types defined in table 5.9.2.4.2-1 shall be supported.

Table 5.9.2.4.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.9.2.4.3 Enumeration: AccessRightStatus

The enumeration AccessRightStatus represents the parameters provision type of which the AF requests to provision. It shall comply with the provisions defined in table 5.9.2.4.3-1.

Table 5.9.2.4.3-1: Enumeration AccessRightStatus

Enumeration value	Description
FULLY_ALLOWED	The User is fully allowed to access to the channel.
PREVIEW_ALLOWED	The User is preview allowed to access to the channel.
NO_ALLOWED	The User is not allowed to access to the channel.

5.9.3 Used Features

The table below defines the features applicable to the IPTVConfiguration API. Those features are negotiated as described in clause 5.2.7 of 3GPP TS 29.122 [4].

Table 5.9.3-1: Features used by IPTVConfiguration API

Feature number	Feature Name	Description

5.9.4 Error handling

5.9.4.1 General

HTTP error handling shall be supported as specified in clause 5.2.6 of 3GPP TS 29.122 [4].

In addition, the requirements in the following clauses shall apply.

5.9.4.2 Protocol Errors

In this Release of the specification, there are no additional protocol errors applicable for the IPTVConfiguration API.

5.9.4.3 Application Errors

The application errors defined for IPTVConfiguration API are listed in table 5.9.4.3-1.

Table 5.9.4.3-1: Application errors

Application Error	HTTP status code	Description	Applicability