5.28 MSEventExposure API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

5.28.1 Introduction

The Nnef_MSEventExposure service shall use the MSEventExposure API.

The API URI of MSEventExposure API shall be:

{apiRoot}/3gpp-ms-event-exposure/v1

with the following components:

– "apiRoot" is set as defined in clause 5.2.4 of 3GPP TS 29.122 [4].

– "apiName" shall be set to "3gpp-ms-event-exposure".

– "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.

5.28.2 Resources

5.28.2.1 Overview

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

Figure 5.28.2.1-1: Resource URI structure of the MSEventExposure API

Table 5.28.2.1-1 provides an overview of the resources and applicable HTTP methods.

Table 5.28.2.1-1: Resources and methods overview

Resource name	Resource URI (relative path under API URI)	HTTP method or custom operation	Description (service operation)
Media Streaming Event Exposure Subscriptions	/subscriptions	GET	Reads all the existing Media Streaming Event Exposure Subscriptions.
		POST	Request the creation of a Media Streaming Event Subscription.
Individual Media Sreaming Event Exposure Subscription	/subscriptions/{subscriptionId}	GET	Read an existing Individual Media Streaming Event Exposure Subscription resource.
		PUT	Update an existing Individual Media Streaming Event Exposure Subscription.
		DELETE	Delete an existing Individual Media Streaming Event Exposure Subscription.

5.28.2.2 Resource: Media Streaming Event Exposure Subscriptions

5.28.2.2.1 Introduction

This resource represents the collection of Media Streaming Event Exposure Subscription resources managed by the NEF.

This resource is modelled with the Collection resource archetype (see clause C.2 of 3GPP TS 29.501 [3]).

5.28.2.2.2 Resource Definition

Resource URI: {apiRoot}/3gpp-ms-event-exposure/v1/subscriptions

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

Table 5.28.2.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 5.28.1.

5.28.2.2.3 Resource Standard Methods

5.28.2.2.3.1 GET

This method allows an AF to retrieve all the active Media Streaming Event Exposure Subscription resource at the NEF.

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

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

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

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

Data type	P	Cardinality	Description
n/a

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

Data type	P	Cardinality	Response codes	Description
array(AfEventExposureSubsc)	M	0..N	200 OK	Successful case. All the active Media Streaming Event Exposure Subscriptions managed by the NEF are returned.
n/a			307 Temporary Redirect	Temporary redirection. 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. 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 code for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.28.2.2.3.1-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.28.2.2.3.1-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.28.2.2.3.2 POST

This method enables an AF to request the creation of a new Media Streaming Event Exposure Subscription at the NEF.

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

Table 5.28.2.2.3.2-1: URI query parameters supported by the POST method on this resource

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

Table 5.28.2.2.3.2-2: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
AfEventExposureSubsc	M	1	Contains the parameters to request the creation of a new Media Streaming Event Exposure Subscription at the NEF.

Table 5.28.2.2.3.2-3: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response Codes	Description
AfEventExposureSubsc	M	1	201 Created	Successful case. A new Media Streaming Event Exposure Subscription is successfully created and a representation of the created Individual Media Streaming Event Exposure Subscription resource is returned. An HTTP "Location" header that contains the resource URI of the created Individual Media Streaming Event Exposure Subscription resource shall also be included.
NOTE: The mandatory HTTP error status code for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.28.2.2.3.2-4: 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-ms-event-exposure/v1/subscriptions/{subscriptionId}

5.28.2.2.4 Resource Custom Operations

There are no resource custom operations defined for this resource in this release of the specification.

5.28.2.3 Resource: Individual Media Streaming Event Exposure Subscription

5.28.2.3.1 Introduction

This resource represents an Individual Media Streaming Event Exposure Subscription managed by the NEF.

This resource is modelled with the Document resource archetype (see clause C.1 of 3GPP TS 29.501 [3]).

5.28.2.3.2 Resource Definition

Resource URI: {apiRoot}/3gpp-ms-event-exposure/v1/subscriptions/{subscriptionId}

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

Table 5.28.2.3.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 5.28.1.
subscriptionId	string	Contains the unique identifier of the Individual Media Streaming Event Exposure Subscription resource assigned by the NEF.

5.28.2.3.3 Resource Standard Methods

5.28.2.3.3.1 GET

This method allows an AF to retrieve an existing Individual Media Streaming Event Exposure Subscription resource at the NEF.

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

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

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

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

Data type	P	Cardinality	Description
n/a

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

Data type	P	Cardinality	Response codes	Description
AfEventExposureSubsc	M	1	200 OK	Successful case. The requested Individual Media Streaming Event Exposure Subscription resource is successfully returned.
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI 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. The response shall include a Location header field containing an alternative target URI 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 code for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.28.2.3.3.1-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.28.2.3.3.1-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.28.2.3.3.2 PUT

This method enables an AF to request the update of an existing Individual Media Streaming Event Exposure Subscription resource at the NEF.

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

Table 5.28.2.3.3.2-1: URI query parameters supported by the PUT method on this resource

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

Table 5.28.2.3.3.2-2: Data structures supported by the PUT Request Body on this resource

Data type	P	Cardinality	Description
AfEventExposureSubsc	M	1	Contains the updated representation of the Individual Media Streaming Event Exposure Subscription resource that is to be updated.

Table 5.28.2.3.3.2-3: Data structures supported by the PUT Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AfEventExposureSubsc	M	1	200 OK	Successful case. The concerned Individual Media Streaming Event Exposure Subscription resource is successfully updated and a representation of the updated resource is returned in the response body.
n/a			204 No Content	Successful case. The concerned Individual Media Streaming Event Exposure Subscription resource is successfully updated and no content is returned in the response body.
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI 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. The response shall include a Location header field containing an alternative target URI 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 code for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.28.2.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.28.2.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.28.2.3.3.3 DELETE

This method enables an AF to request the deletion of an existing Individual Media Streaming Event Exposure resource at the NEF.

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

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

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

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

Data type	P	Cardinality	Description
n/a

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

Data type	P	Cardinality	Response Codes	Description
n/a			204 No Content	Successful response. The Individual Media Streaming Event Exposure resource is successfully deleted.
			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing an alternative target URI 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 code for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.28.2.3.3.3-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.28.2.3.3.3-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.28.2.3.4 Resource Custom Operations

There are no resource custom operations defined for this resource in this release of the specification.

5.28.3 Custom Operations without associated resources

There are no custom operations without associated resources defined for this API in this release of the specification.

5.28.4 Notifications

5.28.4.1 General

Notifications shall comply to clause 5.2.5 of 3GPP TS 29.122 [4].

Table 5.28.4.1-1: Notifications overview

Notification	Callback URI	HTTP method or custom operation	Description (service operation)
Media Streaming Event Exposure Notification	{notifUri}	POST	This operation enables the NEF to notify a previously subscribed AF on the Media Streaming Exposure Event(s).

5.28.4.2 Media Streaming Event Exposure Notification

5.28.4.2.1 Description

The Media Streaming Event Exposure notification is used by the NEF to report one or several observed Media Streaming event(s) to a previously subscribed AF.

5.28.4.2.2 Target URI

The Callback URI "{notifUri}" shall be used with the callback URI variables defined in table 5.28.4.2.2-1.

Table 5.28.4.2.2-1: Callback URI variables

Name	Definition
notifUri	Callback reference provided by the AF during the creation/update of the corresponding Media Streaming Event Exposure Subscription.

5.28.4.2.3 Operation Definition

5.28.4.2.3.1 Notification via HTTP POST

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

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

Data type	P	Cardinality	Description
AfEventExposureNotif	M	1	Contains the Media Streaming Event Exposure Notification.

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

Data type	P	Cardinality	Response codes	Description
N/A			204 No Content	The Media Streaming Event Notification is successfully received.
N/A			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative AF where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
N/A			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative AF where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
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.28.4.2.3.1-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF towards which the notification should be redirected.

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

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF towards which the notification should be redirected.

5.28.4.2.3.2 Notification via Websocket

If supported by both AF and NEF and successfully negotiated, the Media Streaming event notification may alternatively be delivered through the Websocket mechanism as defined in clause 5.2.5.4 of 3GPP TS 29.122 [4].

5.28.5 Data Model

5.28.5.1 General

This clause specifies the application data model supported by the MSEventExposure API. Table 5.28.5.1-1 specifies the data types defined for the MSEventExposure API.

Table 5.28.5.1-1: MSEventExposure specific Data Types

Data type	Clause defined	Description	Applicability

Table 5.28.5.1-2 specifies data types re-used by the MSEventExposure API from other specifications, including a reference to their respective specifications, and when needed, a short description of their use within the MSEventExposure API.

Table 5.28.5.1-2: Re-used Data Types

Data type	Reference	Comments	Applicability
AfEventExposureNotif	3GPP TS 29.517 [58]	Represents a Media Streaming event notification.
AfEventExposureSubsc	3GPP TS 29.517 [58]	Represents a Media Streaming event exposure subscription. Only applicable to the UE application events exposed via Data Collection AF as defined in clause 4.1.1 of 3GPP TS 29.517 [58].

5.28.5.2 Structured data types

5.28.5.2.1 Introduction

This clause defines the structures to be used in resource representations.

There are no structured data types defined for this API in this release of the specification.

5.28.5.3 Simple data types and enumerations

5.28.5.3.1 Introduction

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

5.28.5.3.2 Simple data types

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

Table 5.28.5.3.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.28.6 Used Features

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

Table 5.28.6-1: Features used by MSEventExposure API

Feature number	Feature Name	Description

5.28.7 Error handling

5.28.7.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.28.7.2 Protocol Errors

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

5.28.7.3 Application Errors

The application errors defined for the MSEventExposure API are listed in table 5.28.7.3-1.

Table 5.28.7.3-1: Application errors

Application Error	HTTP status code	Description