5 API Definitions
29.5763GPP5G SystemMessaging Framework Adaptor ServicesRelease 18Stage 3TS
5.1 Nmfaf_3daDataManagement Service API
5.1.1 Introduction
The Nmfaf_3daDataManagement Service shall use the Nmfaf_3daDataManagement API.
The API URI of the Nmfaf_3daDataManagement API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].
– The <apiName> shall be "nmfaf-3dadatamanagement".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 5.1.3.
5.1.2 Usage of HTTP
5.1.2.1 General
HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].
HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].
The OpenAPI [6] specification of HTTP messages and content bodies for the Nmfaf_3daDataManagement API is contained in Annex A.
5.1.2.2 HTTP standard headers
5.1.2.2.1 General
See clause 5.1.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.
5.1.2.2.2 Content type
JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in clause 5.4 of 3GPP TS 29.500 [4]. The use of the JSON format shall be signalled by the content type "application/json".
"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].
5.1.2.3 HTTP custom headers
The mandatory HTTP custom header fields specified in clause 5.1.3.2 of 3GPP TS 29.500 [4] shall be applicable.
5.1.3 Resources
5.1.3.1 Overview
This clause describes the structure for the Resource URIs, the resources and methods used for the service.
Figure 5.1.3.1-1 depicts the resource URIs structure for the Nmfaf_3daDataManagement API.
Figure 5.1.3.1-1: Resource URI structure of the Nmfaf_3daDataManagement API
Table 5.1.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 5.1.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
MFAF Configurations |
/configurations |
POST |
Creates a new individual MFAF Configuration resource. |
|
Individual MFAF Configuration |
/configurations/{transRefId} |
PUT |
Modifies an existing Individual MFAF Configuration subresource. |
|
DELETE |
Deletes an Individual MFAF Configuration identified by subresource {transRefId}. |
5.1.3.2 Resource: MFAF Configurations
5.1.3.2.1 Description
The MFAF Configurations resource represents all configuration to the Nmfaf_3daDataManagement Service at a given MFAF. The resource allows an NF service consumer to create a new Individual MFAF Configuration resource.
5.1.3.2.2 Resource Definition
Resource URI: {apiRoot}/nmfaf-3dadatamanagement/<apiVersion>/configurations
The <apiVersion> shall be set as described in clause 5.1.1.
This resource shall support the resource URI variables defined in table 5.1.3.2.2-1.
Table 5.1.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.1.1 |
5.1.3.2.3 Resource Standard Methods
5.1.3.2.3.1 POST
This method shall support the URI query parameters specified in table 5.1.3.2.3.1-1.
Table 5.1.3.2.3.1-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.1.3.2.3.1-2 and the response data structures and response codes specified in table 5.1.3.2.3.1-3.
Table 5.1.3.2.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
MfafConfiguration |
M |
1 |
Create a new Individual MFAF Configuration resource. |
Table 5.1.3.2.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
MfafConfiguration |
M |
1 |
201 Created |
The creation of an Individual MFAF Configuration resource is confirmed and a representation of that resource is returned. |
|
NOTE: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.1.3.2.3.1-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}/nmfaf-3dadatamanagement/<apiVersion>/configurations/{transRefId} |
5.1.3.2.4 Resource Custom Operations
None in this release of the specification.
5.1.3.3 Resource: Individual MFAF Configuration
5.1.3.2.1 Description
The Individual MFAF Configurations resource represents an individual configuration created in the MFAF and associated with transaction reference Id.
5.1.3.3.2 Resource Definition
Resource URI: {apiRoot}/nmfaf-3dadatamanagement/<apiVersion>/configurations/{transRefId}
The <apiVersion> shall be set as described in clause 5.1.1.
This resource shall support the resource URI variables defined in table 5.1.3.3.2-1.
Table 5.1.3.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.1.1 |
|
transRefId |
string |
Unique identifier of the individual MFAF Configurations resource. |
5.1.3.3.3 Resource Standard Methods
5.1.3.3.3.1 PUT
This method shall support the URI query parameters specified in table 5.1.3.3.3.1-1.
Table 5.1.3.3.3.1-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.1.3.3.3.1-2 and the response data structures and response codes specified in table 5.1.3.3.3.1-3.
Table 5.1.3.3.3.1-2: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
MfafConfiguration |
M |
1 |
The updated MFAF Configuration. |
Table 5.1.3.3.3.1-3: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
MfafConfiguration |
M |
1 |
200 OK |
The update of an Individual MFAF Configuration resource is confirmed and a representation of that resource is returned. |
|
n/a |
204 No Content |
Successful case: The Individual MFAF Configuration resource was modified. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during resource modification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF (service) instance where the request should be sent. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during resource modification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF (service) instance where the request should be sent. |
|
NOTE: The manadatory HTTP error status code for the PUT method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.1.3.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 NF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request should be redirected. |
Table 5.1.3.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 NF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request should be redirected. |
5.1.3.3.3.2 DELETE
This method shall support the URI query parameters specified in table 5.1.3.3.3.2-1.
Table 5.1.3.3.3.2-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.1.3.3.3.2-2 and the response data structures and response codes specified in table 5.1.3.3.3.2-3.
Table 5.1.3.3.3.2-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 5.1.3.3.3.2-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 case: The Individual MFAF Configuration resource matching the transRefId was deleted. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during resource deletion. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF (service) instance where the request should be sent. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during resource deletion. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF (service) instance where the request should be sent. |
|
NOTE: The manadatory HTTP error status code for the DELETE method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.1.3.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 NF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request should be redirected. |
Table 5.1.3.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 NF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request should be redirected. |
5.1.4 Custom Operations without associated resources
None in this release of the specification.
5.1.5 Notifications
None in this release of the specification.
5.1.6 Data Model
5.1.6.1 General
This clause specifies the application data model supported by the API.
Table 5.1.6.1-1 specifies the data types defined for the Nmfaf_3daDataManagement service based interface protocol.
Table 5.1.6.1-1: Nmfaf_3daDataManagement specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
MfafConfiguration |
5.1.6.2.2 |
The description of MFAF configuration |
|
|
MessageConfiguration |
5.1.6.2.3 |
The description of the configurations. |
|
|
MfafNotiInfo |
5.1.6.2.4 |
The MFAF notification information. |
Table 5.1.6.1-2 specifies data types re-used by the Nmfaf_3daDataManagement service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nmfaf_3daDataManagement service based interface.
Table 5.1.6.1-2: Nmfaf_3daDataManagement re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
FormattingInstruction |
3GPP TS 29.574 [15] |
Contains data or analytics formatting Instructions. |
|
|
ProcessingInstruction |
3GPP TS 29.574 [15] |
Contains instructions related to the processing |
|
|
SupportedFeatures |
3GPP TS 29.571 [22] |
Used to negotiate the applicability of the optional features defined in table 5.1.8-1. |
|
|
Uri |
3GPP TS 29.571 [22] |
URI. |
5.1.6.2 Structured data types
5.1.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
5.1.6.2.2 Type: MfafConfiguration
Table 5.1.6.2.2-1: Definition of type MfafConfiguration
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
messageConfigurations |
array(MessageConfiguration) |
M |
1..N |
The configuration of the MFAF for mapping data or analytics. |
5.1.6.2.3 Type: MessageConfiguration
Table 5.1.6.2.3-1: Definition of type MessageConfiguration
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
correId |
string |
M |
1 |
If the configuration is used for mapping analytics or data collection, representing the Analytics Consumer Notification Correlation ID or Data Consumer Notification Correlation ID. |
|
|
formatInstruct |
FormattingInstruction |
O |
0..1 |
Formatting instructions to be used for sending event notifications. |
|
|
mfafNotiInfo |
MfafNotiInfo |
C |
0..1 |
The MFAF notification information. It shall be provided in a response message if it had not been provided in the respective request message. |
|
|
notificationURI |
Uri |
M |
1 |
The notification URI of Data Consumer or Analytics Consumer or other endpoint where to receive the requested mapping data or analytics |
|
|
procInstruct |
ProcessingInstruction |
O |
0..1 |
Processing instructions to be used for sending event notifications. (NOTE 1) |
|
|
multiProcInstructs |
array(ProcessingInstruction) |
O |
1..N |
Processing instructions to be used for sending event notifications. (NOTE 1) |
MultiProcessingInstruction |
|
adrfId |
NfInstanceId |
O |
0..1 |
NF instance identifier of the ADRF in which data and analytics can be stored. |
|
|
suppFeat |
SupportedFeatures |
C |
0..1 |
This IE represents a list of Supported features as described in clause 5.1.8. (NOTE 2) |
|
|
NOTE 1: The "multiProcInstructs" attribute shall be used instead of the "procInstruct" attribute when the "MultiProcessingInstruction" feature is supported. NOTE 2 It shall be present in the POST request if at least one feature defined in clause 5.1.8 is supported, and it shall be present in the POST response if the NF service consumer includes the "suppFeat" attribute in the POST request. |
|||||
5.1.6.2.4 Type: MfafNotiInfo
Table 5.1.6.2.4-1: Definition of type MfafNotiInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
mfafNotifUri |
Uri |
M |
1 |
The notification URI of MFAF Notification Target Address. |
|
|
mfafCorreId |
string |
M |
1 |
The MFAF Notification Correlation ID |
5.1.6.3 Simple data types and enumerations
5.1.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
5.1.6.3.2 Simple data types
The simple data types defined in table 5.1.6.3.2-1 shall be supported.
Table 5.1.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
5.1.6.4 Data types describing alternative data types or combinations of data types
None in current specification.
5.1.6.5 Binary data
None in current specification.
5.1.7 Error Handling
5.1.7.1 General
For the Nmfaf_3daDataManagement API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.1.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.1.7.1-1 of 3GPP TS 29.500 [4].
In addition, the requirements in the following clauses are applicable for the Nmfaf_3daDataManagement API.
5.1.7.2 Protocol Errors
No specific procedures for the Nmfaf_3daDataManagement service are specified.
5.1.7.3 Application Errors
The application errors defined for the Nmfaf_3daDataManagement service are listed in Table 5.1.7.3-1.
Table 5.1.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
5.1.8 Feature negotiation
The optional features in table 5.1.8-1 are defined for the Nmfaf_3daDataManagement API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 5.1.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
|
1 |
MultiProcessingInstruction |
Indicates the support of multiple processing instructions. |
5.1.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nmfaf_3daDataManagement API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.
If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Nmfaf_3daDataManagement API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.
NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nmfaf_3daDataManagement service.
The Nmfaf_3daDataManagement API defines a single scope "nmfaf_3dadatamanagement" for the entire service, and it does not define any additional scopes at resource or operation level.
5.2 Nmfaf_3caDataManagement Service API
5.2.1 Introduction
The Nmfaf_3caDataManagement Service shall use the Nmfaf_3caDataManagement API.
The API URI of the Nmfaf_3caDataManagement API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].
– The <apiName> shall be "nmfaf-3cadatamanagement".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 5.2.3.
5.2.2 Usage of HTTP
5.2.2.1 General
HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].
HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].
The OpenAPI [6] specification of HTTP messages and content bodies for the Nmfaf_3caDataManagement API is contained in Annex A.
5.2.2.2 HTTP standard headers
5.2.2.2.1 General
See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.
5.2.2.2.2 Content type
JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in clause 5.4 of 3GPP TS 29.500 [4]. The use of the JSON format shall be signalled by the content type "application/json".
"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].
5.2.2.3 HTTP custom headers
The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be applicable.
5.2.3 Resources
5.2.3.1 Overview
This clause describes the structure for the Resource URIs, the resources and methods used for the service.
Figure 5.2.3.1-1 depicts the resource URIs structure for the Nmfaf_3caDataManagement API.
Figure 5.2.3.1-1: Resource URI structure of the Nmfaf_3caDataManagement API
Table 5.2.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 5.2.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
MFAF Data or Analytics(Collection) |
/mfaf-data-analytics |
POST |
This is a pseudo resource. |
5.2.3.2 Resource: MFAF Data or Analytics
5.2.3.2.1 Description
5.2.3.2.2 Resource Definition
Resource URI: {apiRoot}/nmfaf_3cadatamanagement/<apiVersion>/mfaf-data-analytics
The <apiVersion> shall be set as described in clause 5.2.1.
This resource shall support the resource URI variables defined in table 5.2.3.2.2-1.
Table 5.2.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.2.1 |
5.2.3.2.3 Resource Standard Methods
5.2.3.2.3.1 POST
This method shall support the URI query parameters specified in table 5.2.3.2.3.1-1.
Table 5.2.3.2.3.1-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.2.3.2.3.1-2 and the response data structures and response codes specified in table 5.2.3.2.3.1-3.
Table 5.2.3.2.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
Any |
Table 5.2.3.2.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
||||
|
NOTE: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
5.2.4 Custom Operations without associated resources
None in this release of the specification.
5.2.5 Notifications
5.2.5.1 General
Notifications shall comply to clause 6.2 of 3GPP TS 29.500 [4] and clause 4.6.2.3 of 3GPP TS 29.501 [5].
Table 5.2.5.1-1: Notifications overview
|
Notification |
Callback URI |
HTTP method or custom operation |
Description (service operation) |
|
MFAF Notification |
{notificationURI} (NOTE) |
POST |
Report one or several observed data or analytics. |
|
Fetch Notification |
{fetchUri} |
POST |
Fetch one or several notified data or analytics. |
|
NOTE: The notificationURI is not provided by NF service consumer via Nmfaf-3caDataManagement API, it is provided via Nmfaf-3daDataManagement API during the configuration for mapping data or analytics. |
|||
5.2.5.2 MFAF Notification
5.2.5.2.1 Description
The MFAF Notification is used by the MFAF to provide data or analytics or notification of availability of data or analytics to notification endpoints.
5.2.5.2.2 Target URI
The Callback URI "{notificationURI}" shall be used with the callback URI variables defined in table 5.2.5.2.2-1.
Table 5.2.5.2.2-1: Callback URI variables
|
Name |
Definition |
|
notificationURI |
The notification URI of Data Consumer or Analytics Consumer or other endpoint where to receive the requested data or analytics. The notificationURI is not provided by NF service consumer via Nmfaf-3caDataManagement API, it is provided via Nmfaf-3daDataManagement API during the configuration for mapping data or analytics. |
5.2.5.2.3 Standard Methods
5.2.5.2.3.1 POST
This method shall support the request data structures specified in table 5.2.5.2.3.1-1 and the response data structures and response codes specified in table 5.2.5.2.3.1-2.
Table 5.2.5.2.3.1-1: Data structures supported by the POST Request Body
|
Data type |
P |
Cardinality |
Description |
|
NmfafDataRetrievalNotification |
M |
1 |
The data or analytics or notification of availability of data or analytics to notification endpoints. |
Table 5.2.5.2.3.1-2: Data structures supported by the POST Response Body
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
The MFAF notification is treated successfully. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during the retrieval notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF consumer (service) instance where the notification should be sent. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during the retrieval notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF consumer (service) instance where the notification should be sent. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.2.5.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 NF consumer (service) instance towards which the notification should be redirected. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the notification request is redirected. |
Table 5.2.5.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 NF consumer (service) instance towards which the notification should be redirected. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the notification request is redirected. |
5.2.5.3 Fetch Notification
5.2.5.3.1 Description
The Fetch Notification is used by the NF service consumer to retrieve data or analytics from the MFAF.
5.2.5.3.2 Target URI
The Callback URI "{fetchUri}" shall be used with the callback URI variables defined in table 5.2.5.3.2-1.
Table 5.2.5.3.2-1: Callback URI variables
|
Name |
Data type |
Definition |
|
fetchUri |
Uri |
Fetch Uri as assigned during the procedure of notification about the subscribed data or analytics within the FetchInstruction data type (see table 5.2.6.2.3-1). |
5.2.5.3.3 Standard Methods
5.2.5.3.3.1 POST
This method shall support the URI query parameters specified in table 5.2.5.3.3.1-1.
Table 5.2.5.3.3.1-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.2.5.3.3.1-2 and the response data structures and response codes specified in table 5.2.5.3.3.1-3.
Table 5.2.5.3.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
array(string) |
M |
1..N |
Indicate the fetch correlation identifier(s). |
Table 5.2.5.3.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
NmfafDataAnaNotification |
M |
1 |
200 OK |
The stored data or analytics related to the fetch correlation identifier(s). |
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during subscription retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative MFAF. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during subscription retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative MFAF. |
|
NOTE: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.2.5.3.3.1-4: Headers supported by the 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 MFAF. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request is redirected. |
Table 5.2.3.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 MFAF. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request is redirected. |
5.2.6 Data Model
5.2.6.1 General
This clause specifies the application data model supported by the API.
Table 5.2.6.1-1 specifies the data types defined for the Nmfaf_3caDataManagement service based interface protocol.
Table 5.2.6.1-1: Nmfaf_3caDataManagement specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
FetchInstruction |
5.2.6.2.3 |
The fetch instruction indicates whether the data or analytics are to be fetched by the Consumer. |
|
|
NmfafDataAnaNotification |
5.2.6.2.4 |
MFAF data or analytics. |
|
|
NmfafDataRetrievalNotification |
5.2.6.2.2 |
The data or analytics or notification of availability of data or analytics to notification endpoints. |
Table 5.2.6.1-2 specifies data types re-used by the Nmfaf_3caDataManagement service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nmfaf_3caDataManagement service based interface.
Table 5.2.6.1-2: Nmfaf_3caDataManagement re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
DataNotification |
3GPP TS 29.575 [23] |
Represents a data subscription notification of one of various possible data sources |
|
|
DateTime |
3GPP TS 29.571 [22] |
Identifies a specific time. |
|
|
NnwdafEventsSubscriptionNotification |
3GPP TS 29.520 [20] |
Represents an NWDAF analytics subscription notification. |
|
|
Uri |
3GPP TS 29.571 [22] |
URI. |
5.2.6.2 Structured data types
5.2.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
5.2.6.2.2 Type: NmfafDataRetrievalNotification
Table 5.2.6.2.2-1: Definition of type NmfafDataRetrievalNotification
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
correId |
string |
M |
1 |
Represents the Analytics Consumer Notification Correlation ID or Data Consumer Notification Correlation ID. It shall be set to the same value as the "correId" attribute of MessageConfiguration data type. |
|
|
dataAnaNotif |
NmfafDataAnaNotification |
C |
0..1 |
Represents notifications of analytics and data. (NOTE) |
|
|
fetchInstruction |
FetchInstruction |
C |
0..1 |
The fetch instruction indicate whether the data or analytics are to be fetched by the Consumer. (NOTE) |
|
|
NOTE: Exactly one of the "dataAnaNotif" and "fetchInstruction" shall be included. |
|||||
5.2.6.2.3 Type: FetchInstruction
Table 5.2.6.2.3-1: Definition of type FetchInstruction
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
fetchUri |
Uri |
M |
1 |
The target address used by a data or analytics consumer to fetch the data or analytics. |
|
|
fetchCorrIds |
array(string) |
M |
1..N |
The fetch correlation identifier(s) of the MFAF Data or Analytics |
|
|
expiry |
DateTime |
O |
0..1 |
Indicates an expiration time, i.e. a deadline to fetch the data. |
5.2.6.2.4 Type: NmfafDataAnaNotification
Table 5.2.6.2.4-1: Definition of type NmfafDataAnaNotification
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
anaNotifications |
array(NnwdafEventsSubscriptionNotification) |
C |
1..N |
List of analytics subscription notifications. (NOTE 1) |
|
|
dataNotif |
DataNotification |
C |
0..1 |
Data subscription notification. (NOTE 1) |
|
|
NOTE 1: Exactly one of these attributes shall be provided. NOTE 2: If the MFAF has received the notifications from another source without a timestamp, then the MFAF adds itself a timestamp based on the time it received the notification in “timeStampGen” attribute contained in dataNotification attribute within the EventNotification data type in the NnwdafEventsSubscriptionNotification data type. |
|||||
5.2.6.3 Simple data types and enumerations
5.2.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
5.2.6.3.2 Simple data types
None in this release of the specification.
5.2.6.4 Data types describing alternative data types or combinations of data types
None in this release of the specification.
5.2.6.5 Binary data
None in this release of the specification.
5.2.7 Error Handling
5.2.7.1 General
For the Nmfaf_3caDataManagement API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].
In addition, the requirements in the following clauses are applicable for the Nmfaf_3caDataManagement API.
5.2.7.2 Protocol Errors
No specific procedures for the Nmfaf_3caDataManagement service are specified.
5.2.7.3 Application Errors
The application errors defined for the Nmfaf_3caDataManagement service are listed in Table 5.2.7.3-1.
Table 5.2.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
5.2.8 Feature negotiation
The optional features in table 5.2.8-1 are defined for the Nmfaf_3caDataManagement API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 5.2.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
5.2.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nmfaf_3caDataManagement API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.
If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Nmfaf_3caDataManagement API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.
NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nmfaf_3caDataManagement service.
The Nmfaf_3caDataManagement API defines a single scope "nmfaf_3cadatamanagement" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification