6 API Definitions
29.5423GPP5G SystemRelease 18Session management services for Non-IP Data Delivery (NIDD)Stage 3TS
6.1 Nsmf_NIDD Service API
6.1.1 Introduction
The Nsmf_NIDD service shall use the Nsmf_NIDD API.
The API URI of the Nsmf_NIDD API shall be:
{apiRoot}/<apiName>/<apiVersion>/
The request URI used in HTTP request 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 "nsmf-nidd".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 6.1.3.
6.1.2 Usage of HTTP
6.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 Nsmf_NIDD API is contained in Annex A.
6.1.2.2 HTTP standard headers
6.1.2.2.1 General
The usage of HTTP standard headers shall be supported as specified in clause 5.2.2 of 3GPP TS 29.500 [4].
6.1.2.2.2 Content type
The following content types shall be supported:
– the JSON format (IETF RFC 8259 [12]). The use of the JSON format shall be signalled by the content type "application/json". See also clause 5.4 of 3GPP TS 29.500 [4].
– the Problem Details JSON Object (IETF RFC 7807 [13]). The use of the Problem Details JSON object in a HTTP response body shall be signalled by the content type "application/problem+json".
NOTE: "application/json" is used in a response that includes a payload body containing an application-specific data structure, see clause 4.8 of 3GPP TS 29.501 [5].
Multipart messages shall also be supported (see clause 6.1.2.4) using the content type "multipart/related", comprising:
– one JSON body part with the "application/json" content type; and
– one or two binary body parts with 3gpp vendor specific content subtypes.
The 3gpp vendor specific content subtypes defined in Table 6.1.2.2.2-1 shall be supported.
Table 6.1.2.2.2-1: 3GPP vendor specific content subtypes
|
content subtype |
Description |
|
vnd.3gpp.5gnas |
Binary encoded payload, encoding a 5GS NAS message or 5G NAS IEs, as specified in 3GPP TS 24.501 [7]. |
See clause 6.1.6.5 for the binary payloads supported in the binary body part of multipart messages.
6.1.2.3 HTTP custom headers
In this release of the specification, no specific custom headers are defined for the Nsmf_NIDD service.
For 3GPP specific HTTP custom headers used across all service based interfaces, see clause 5.2.3 of 3GPP TS 29.500 [4].
6.1.3 Resources
6.1.3.1 Overview
Figure 6.1.3.1-1 describes the resource URI structure of the Nsmf_NIDD API.
Figure 6.1.3.1-1: Resource URI structure of the Nsmf_NIDD API
Table 6.1.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 6.1.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
Individual PDU session |
/pdu-sessions/{pduSessionRef}/deliver |
deliver (POST) |
Delivery Service Operation |
6.1.3.2 Resource: Individual PDU session
6.1.3.2.1 Description
This resource represents an individual PDU session created in SMF for NIDD.
This resource is modelled with the Document resource archetype (see clause C.1 of 3GPP TS 29.501 [5]).
6.1.3.2.2 Resource Definition
Resource URI: {apiRoot}/nsmf-nidd/<apiVersion>/pdu-sessions/{pduSessionRef}
This resource shall support the resource URI variables defined in table 6.1.3.2.2-1.
Table 6.1.3.2.2-1: Resource URI variables for this resource
|
Name |
Definition |
|
apiRoot |
See clause 6.1.1 |
|
apiVersion |
See clause 6.1.1 |
|
pduSessionRef |
PDU session reference assigned by the SMF during SMF-NEF Connection creation. |
6.1.3.2.3 Resource Standard Methods
None.
6.1.3.2.4 Resource Custom Operations
6.1.3.2.4.1 Overview
Table 6.1.3.2.4.1-1: Custom operations
|
Custom operaration URI |
Mapped HTTP method |
Description |
|
{resourceUri}/deliver |
POST |
Delivery service operation. |
6.1.3.2.4.2 Operation: deliver
6.1.3.2.4.2.1 Description
This custom operation enables to deliver NEF anchored MT data for a given PDU session towards the SMF.
6.1.3.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 6.1.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.1.3.2.4.2.2-2.
Table 6.1.3.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
DeliverReqData |
M |
1 |
Representation of the payload of a Deliver Request |
Table 6.1.3.2.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Successful delivery of MT data. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same SMF or SMF (service) set. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same SMF or SMF (service) set. |
|
DeliverError |
O |
0..1 |
504 Gateway Timeout |
The "cause" attribute may be used to indicate the following application errors: – UE_NOT_REACHABLE, if the UE is not reachable to deliver the mobile terminated data; if Estimated Maximum Waiting Time shall be included if available; See table 6.1.7.3-1 for the description of these errors. |
|
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] other than those specified in the table above also apply, with a ProblemDetails data type when needed (see clause 5.2.7 of 3GPP TS 29.500 [4]). |
||||
Table 6.1.3.2.4.2.2-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 on an alternative service instance within the same SMF or SMF (service) set. Or the same URI, if a request is redirected to the same target resource via a different SCP. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance ID towards which the request is redirected |
Table 6.1.3.2.4.2.2-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 on an alternative service instance within the same SMF or SMF (service) set. Or the same URI, if a request is redirected to the same target resource via a different SCP. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance ID towards which the request is redirected |
6.1.4 Custom Operations without associated resources
None
6.1.5 Notifications
None.
6.1.6 Data Model
6.1.6.1 General
This clause specifies the application data model supported by the API.
Table 6.1.6.1-1 specifies the data types defined for the Nsmf_NIDD service based interface protocol.
Table 6.1.6.1-1: Nsmf_NIDD specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
DeliverReqData |
6.1.6.2.2 |
Information within Deliver Request |
|
|
DeliverAddInfo |
6.1.6.2.3 |
Deliver Error Response Additional Information |
|
|
DeliverError |
6.1.6.4.1 |
Deliver Error Response |
Table 6.1.6.1-2 specifies data types re-used by the N<NF> 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 N<NF> service based interface.
Table 6.1.6.1-2: Nsmf_NIDD re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
RefToBinaryData |
3GPP TS 29.571 [15] |
Cross-Reference to binary data encoded within a binary body part in an HTTP multipart message. |
|
|
ProblemDetails |
3GPP TS 29.571 [15] |
Error description |
|
|
DurationSec |
3GPP TS 29.571 [15] |
Duration in units of seconds |
|
|
RedirectResponse |
3GPP TS 29.571 [15] |
Redirect Response |
6.1.6.2 Structured data types
6.1.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.1.6.2.2 Type: DeliverReqData
Table 6.1.6.2.2-1: Definition of type DeliverReqData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
mtData |
RefToBinaryData |
M |
1 |
This IE shall reference the Mobile Terminated Data (see clause 6.1.6.5.1). |
6.1.6.2.3 Type: DeliverAddInfo
Table 6.1.6.2.3-1: Definition of type DeliverAddInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
maxWaitingTime |
DurationSec |
C |
0..1 |
This IE shall contain the estimated maximum wait time (see clause 4.25.5 of 3GPP 23.502 [3]). |
6.1.6.3 Simple data types and enumerations
6.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.
6.1.6.3.2 Simple data types
The simple data types defined in table 6.1.6.3.2-1 shall be supported.
Table 6.1.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
6.1.6.4 Data types describing alternative data types or combinations of data types
6.1.6.4.1 Type: DeliverError
Table 6.1.6.4.1-1: Definition of type DeliverError as a list of "to be combined data types"
|
Data type |
Cardinality |
Description |
Applicability |
|
ProblemDetails |
1 |
Detail information of the problem |
|
|
DeliverAddInfo |
1 |
Additional information to be returned in error response. |
6.1.6.5 Binary data
6.1.6.5.1 Mobile Terminated Data
Mobile Terminated Data shall encode the Data Contents of the Payload Container specified in 3GPP TS 24.501 [7], using the vnd.3gpp.5gnas content-type, as summarized in Table 6.1.6.5.1-1.
Table 6.1.6.5.1-1: Mobile Terminated Data
|
Mobile Terminated Data |
Reference (3GPP TS 24.501 [7]) |
Related NAS SM message |
|
Payload container contents in octets 4 to n |
9.11.3.39 |
DL NAS Transport |
6.1.7 Error Handling
6.1.7.1 General
For the Nsmf_NIDD 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 Nsmf_NIDD API.
6.1.7.2 Protocol Errors
No specific procedures for the Nsmf_NIDD service are specified.
6.1.7.3 Application Errors
The common application errors defined in Table 5.2.7.2-1 of 3GPP TS 29.500 [4] may be used for the Nsmf_NIDD service.
The application errors defined for the Nsmf_NIDD service are listed in Table 6.1.7.3-1.
Table 6.1.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
UE_NOT_REACHABLE |
504 Gateway Timeout |
The UE is not reachable for the service. |
6.1.8 Feature negotiation
The optional features in table 6.1.8-1 are defined for the Nsmf_NIDD API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 6.1.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
6.1.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nsmf_NIDD 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 Nsmf_NIDD 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 Nsmf_NIDD service.
The Nsmf_NIDD API defines scopes for OAuth2 authorization as specified in 3GPP TS 33.501 [15]; it defines a single scope consisting on the name of the service (i.e., "nsmf-nidd"), and it does not define any additional scopes at resource or operation level.
6.1.10 HTTP redirection
An HTTP request may be redirected to a different SMF service instance, within the same SMF or a different SMF of an SMF set, e.g. when an SMF service instance is part of an SMF (service) set or when using indirect communications (see 3GPP TS 29.500 [4]).
An SCP that reselects a different SMF producer instance will return the NF Instance ID of the new SMF producer instance in the 3gpp-Sbi-Producer-Id header, as specified in clause 6.10.3.4 of 3GPP TS 29.500 [4].
If an SMF within an SMF set redirects a service request to a different SMF of the set using an 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new SMF towards which the service request is redirected shall be indicated in the 3gpp-Sbi-Target-Nf-Id header of the 307 Temporary Redirect or 308 Permanent Redirect response as specified in clause 6.10.9.1 of 3GPP TS 29.500 [4].
Annex A (normative):
OpenAPI specification