6 API Definitions

29.5773GPP5G SystemIP Short Message Gateway and SMS Router For Short Message ServicesRelease 18Stage 3TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

6.1 Nipsmgw_SMService Service API

6.1.1 Introduction

The Nipsmgw_SMService shall use the Nipsmgw_SMService API.

The API URI of the Nipsmgw_SMService 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 "nipsmgw-smservice".

– 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 Nipsmgw_SMService API is contained in Annex A.

6.1.2.2 HTTP standard headers

6.1.2.2.1 General

See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.

6.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].

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 binary body part 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.sms	Binary encoded payload, encoding SMS payload, as specified in 3GPP TS 23.040 [16] and 3GPP TS 24.011 [17].
NOTE: Using 3GPP vendor content subtypes allows to describe the nature of the opaque payload (e.g. SMS payload) without having to rely on metadata in the JSON payload.

See clause 6.1.2.4 for the binary payloads supported in the binary body part of multipart messages.

6.1.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 supported, and the optional HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [4] may be supported.

6.1.2.4 HTTP multipart messages

HTTP multipart messages shall be supported, to transfer opaque SMS payload (e.g. SMS message, CP Ack, etc.), in the following service operations (and HTTP messages):

– MtForwardSm service operation;

HTTP multipart messages shall include one JSON body part and one binary body part comprising content of SMS payload content (see clause 6.1.6.5).

The JSON body part shall be the "root" body part of the multipart message. It shall be encoded as the first body part of the multipart message. The "Start" parameter does not need to be included.

The multipart message shall include a "type" parameter (see IETF RFC 2387 [18]) specifying the media type of the root body part, i.e. "application/json".

NOTE: The "root" body part (or "root" object) is the first body part the application processes when receiving a multipart/related message, see IETF RFC 2387 [18]. The default root is the first body within the multipart/related message. The "Start" parameter indicates the root body part, e.g. when this is not the first body part in the message.

A binary body part shall include a Content-ID header (see IETF RFC 2045 [19]), and the JSON body part shall make a reference to the binary body part using the Content-ID header field.

Examples of multipart/related messages can be found in Annex B.

6.1.3 Resources

6.1.3.1 Overview

This clause describes the structure for the Resource URIs and the resources and methods used for the service.

Figure 6.1.3.1-1 depicts the resource URIs structure for the Nipsmgw_SMService API.

Figure 6.1.3.1-1: Resource URI structure of the Nipsmgw_SMService 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 purpose/name	Resource URI (relative path after API URI)	HTTP method or custom operation	Description (service operation)
MtSmInfos (Collection)	/mt-sm-infos
MtSmInfo (Document)	/mt-sm-infos/{gpsi}	PUT	Create Routing Information for MT SMS.
MtSmInfo (Document)	/mt-sm-infos/{gpsi}/sendsms	sendsms (POST)	It is used for the MtForwardSm service operation, to allow NF Service Consumer to send SMS payload in downlink direction.

6.1.3.2 Resource: MtSmInfos (Collection)

6.1.3.2.1 Description

This resource represents the collection of Mobile Terminated Short Message Information in IP-SM-GW.

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

No HTTP method has been defined for this resource.

6.1.3.2.2 Resource Definition

Resource URI: {apiRoot}/nipsmgw-smsevice/<apiVersion>/mt-sm-infos

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	Data type	Definition
apiRoot	string	See clause 6.1.1

6.1.3.2.3 Resource Standard Methods

No HTTP method has been defined for the Mobile Terminated Short Message Information collection resource.

6.1.3.3 Resource: MtSmInfo (Document)

6.1.3.3.1 Description

This resource represents an individual Mobile Terminated Short Message Information in IP-SM-GW.

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

6.1.3.3.2 Resource Definition

Resource URI: {apiRoot}/nipsmgw-smsevice/<apiVersion>/mt-sm-infos/{gpsi}

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

Table 6.1.3.3.2-1: Resource URI variables for this resource

Name

Data type

Definition

apiRoot

string

See clause 6.1.1

gpsi

Represents the Generic Public Subscription Identifier with MSISDN (see 3GPP TS 23.501 [2] clause 5.9.8)

pattern: See pattern of type Gpsi in 3GPP TS 29.571 [15]

6.1.3.3.3 Resource Standard Methods

6.1.3.3.3.1 PUT

This method creates an individual resource of Mobile Terminated Short Message Information in the IP-SM-GW, or updates the indicated resource of Mobile Terminated Short Message Information in the IP-SM-GW.

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

Table 6.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 6.1.3.3.3.1-2 and the response data structures and response codes specified in table 6.1.3.3.3.1-3.

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

Data type	P	Cardinality	Description
CreateRoutingData	M	1	Representation of the UE’s Mobile Terminated Short Message Information to be created in the IP-SM-GW, or to be updated in the IP-SM-GW.

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

Data type	P	Cardinality	Response codes	Description
CreatedRoutingData	M	1	201 Created	This case represents the successful creation of an UE’s Mobile Terminated Short Message Information. The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created resource.
CreatedRoutingData	M	1	200 OK	Upon success, a response body containing a representation of the updated UE’s Mobile Terminated Short Message Information shall be returned.
n/a			204 No Content	Upon success, an empty response body shall be returned
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (service) set. (NOTE 2)
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (service) set. (NOTE 2)
NOTE 1: 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. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.1.3.3.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}/nipsmgw-smsevice/<apiVersion>/mt-sm-infos/{gpsi}

Table 6.1.3.3.3.1-5: Headers supported by the 307 Response Code on this resource

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.1.3.3.3.1-6: Headers supported by the 308 Response Code on this resource

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.1.3.3.4 Resource Custom Operations

6.1.3.3.4.1 Overview

Table 6.1.3.3.4.1-1: Custom operations

Operation name	Custom operaration URI	Mapped HTTP method	Description
sendsms	/mt-sm-infos/{gpsii}/sendsms	POST	Send MT SMS message or the related Delivery Report.

6.1.3.3.4.2 Operation: sendsms

6.1.3.3.4.2.1 Description

This custom operation is used for NF Service Consumers to send SMS message in downlink direction.

6.1.3.3.4.2.2 Operation Definition

This custom operation is used to send a SMS payload to an UE’s Mobile Terminated Short Message Information resource in the IP-SM-GW.

This operation shall support the request data structures specified in table 6.1.3.3.4.2.2-1 and the response data structure and response codes specified in table 6.1.3.3.4.2.2-2.

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

Data type	P	Cardinality	Description
SmsData	M	1	Representation of the MT SMS message to be sent.

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

Data type	P	Cardinality	Response codes	Description
SmsDeliveryData	M	1	200 OK	This case represents the successful of sending SMS message in downlink direction, with necessary response data on the received delivery report.
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (service) set. (NOTE 2)
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (service) set. (NOTE 2)
ProblemDetails	O	0..1	400 Bad Request	This case represents an unsuccessful delivery of SMS message. The "cause" attribute may be used to indicate one of the following application errors: – SMS_PAYLOAD_MISSING, if the expected SMS payload content is missing; – SMS_PAYLOAD_ERROR, if error exists in the SMS payload content.
ProblemDetails	O	0..1	404 Not Found	This case represents an unsuccessful delivery of SMS payload. The "cause" attribute may be used to indicate one of the following application errors: – ROUTING_INFO_NOT_FOUND, if the routing information for SMS to be operated is invalid or not found in IP-SM-GW. – USER_NOT_FOUND, if the UE identified by the GPSI is not found in the IP-SM-GW.
NOTE 1: 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. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

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

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

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

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same IP-SM-GW or IP-SM-GW (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.1.4 Custom Operations without associated resources

In this release of this specification, no custom operations without associated resources are defined.

6.1.5 Notifications

In this release of this specification, no notification procedures are defined.

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 Nipsmgw_SMService service based interface protocol.

Table 6.1.6.1-1: Nipsmgw_SMService specific Data Types

Data type	Clause defined	Description	Applicability
CreateRoutingData	6.1.6.2.2	Information used for creating or updating the routing information of the user.
CreatedRoutingData	6.1.6.2.3	Information used for receiving the MT SMS.
SmsData	6.1.6.2.4	Information within request message for delivering SMS.
SmsDeliveryData	6.1.6.2.5	Information within response message invoking MtForwardSm service operation, for delivering MT SMS Delivery Report.

Table 6.1.6.1-2 specifies data types re-used by the Nipsmgw_SMService 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 Nipsmgw_SMService service based interface.

Table 6.1.6.1-2: Nipsmgw_SMService re-used Data Types

Data type	Reference	Comments	Applicability
ProblemDetails	3GPP TS 29.571 [15]	Common Data Type used in response bodies
RedirectResponse	3GPP TS 29.571 [15]	Redirect Response
Gpsi	3GPP TS 29.571 [15]	General Public Subscription Identifier
NfInstanceId	3GPP TS 29.571 [15]	NF Instance ID
RefToBinaryData	3GPP TS 29.571 [15]	Information for indicating the binary content of SMS payload.
Ipv4Addr	3GPP TS 29.571 [15]	IPv4 address
Ipv6Addr	3GPP TS 29.571 [15]	IPv6 address
SupportedFeatures	3GPP TS 29.571 [15]	Supported Features
Fqdn	3GPP TS 29.571 [15]	Fully Qualified Domain Name
Supi	3GPP TS 29.571 [15]	Subscription Permanent Identifier

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: CreateRoutingData

Table 6.1.6.2.2-1: Definition of type CreateRoutingData

Attribute name	Data type	P	Cardinality	Description	Applicability
smsfId	NfInstanceId	M	1	This IE shall be present, and it shall contain the NF instance ID of the SMSF to receive the downlink MT SM.
supi	Supi	O	0..1	SUPI
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.1.8 is supported.

6.1.6.2.3 Type: CreatedRoutingData

Table 6.1.6.2.3-1: Definition of type CreatedRoutingData

Attribute name	Data type	P	Cardinality	Description	Applicability
ipsmgwIpv4	Ipv4Addr	C	0..1	This IE shall be present if available. When present, this IE indicates the IPv4 address of the IP-SM-GW to receive the downlink short message. See NOTE
ipsmgwIpv6	Ipv6Addr	C	0..1	This IE shall be present if available. When present, this IE indicates the IPv6 address of the IP-SM-GW to receive the downlink short message. See NOTE
ipsmgwFqdn	Fqdn	C	0..1	This IE shall be present if available. When present, this IE indicates the FQDN of the IP-SM-GW to receive the downlink short message. See NOTE
correlationId	string	O	0..1	Correlation ID
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.1.8 is supported.
NOTE: At least, one of IP-SM-GW addresses shall be included.

6.1.6.2.4 Type: SmsData

Table 6.1.6.2.4-1: Definition of type SmsData

Attribute name	Data type	P	Cardinality	Description	Applicability
smsPayload	RefToBinaryData	M	1	This IE shall be present, and it shall contain the reference to the SMS Payload Information binary data (see clause 6.1.6.5)

6.1.6.2.5 Type: SmsDeliveryData

Table 6.1.6.2.5-1: Definition of type SmsDeliveryData

Attribute name	Data type	P	Cardinality	Description	Applicability
smsPayload	RefToBinaryData	M	1	This IE shall be present, and it shall contain the reference to the SMS Payload Information binary data (see clause 6.1.6.5)

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

In this release of this specification, no alternative data types or combinations of data types are defined.

6.1.6.5 Binary data

6.1.6.5.1 Binary Data Types

Table 6.1.6.5.1-1: Binary Data Types

Name	Clause defined	Content type
SMS Payload Information	6.1.6.5.2	vnd.3gpp.sms

6.1.6.5.2 SMS Payload Information

SMS Payload Information shall encode a SMS payload as specified in 3GPP TS 23.040 [16] and 3GPP TS 24.011 [17], using the vnd.3gpp.sms content-type.

SMS Payload Information may encode e.g. the following content:

– CP-DATA, CP-ACK, CP-ERROR as specified in 3GPP TS 23.040 [16] and 3GPP TS 24.011 [17].

6.1.7 Error Handling

6.1.7.1 General

For the Nipsmgw_SMService 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 Nipsmgw_SMService API.

6.1.7.2 Protocol Errors

No specific procedures for the Nipsmgw_SMService service are specified.

6.1.7.3 Application Errors

The application errors defined for the Nipsmgw_SMService service are listed in Table 6.1.7.3-1.

Table 6.1.7.3-1: Application errors

Application Error	HTTP status code	Description
SMS_PAYLOAD_MISSING	400 Bad Request	The expected SMS payload content is missing.
SMS_PAYLOAD_ERROR	400 Bad Request	Errors exist in the format of SMS payload.
USER_NOT_FOUND	404 Not Found	The provided subscriber identifier is not found.
ROUTING_INFO_NOT_FOUND	404 Not Found	The routing information for SMS to be operated is invalid or not found in IP-SM-GW

6.1.8 Feature negotiation

The optional features in table 6.1.8-1 are defined for the Nipsmgw_SMService 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 Nipsmgw_SMService 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 Nipsmgw_SMService 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 Nipsmgw_SMService service.

The Nipsmgw_SMService API defines a single scope "nipsmgw-smservice" for the entire service, 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 IP-SM-GW service instance, within the same IP-SM-GW or a different IP-SM-GW of an IP-SM-GW set, e.g. when an IP-SM-GW service instance is part of an IP-SM-GW (service) set or when using indirect communications (see 3GPP TS 29.500 [4]).

An SCP that reselects a different IP-SM-GW producer instance will return the NF Instance ID of the new IP-SM-GW 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 IP-SM-GW within an IP-SM-GW set redirects a service request to a different IP-SM-GW of the set using a 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new IP-SM-GW 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].

6.2 Nrouter_SMService Service API

6.2.1 Introduction

The Nrouter_SMService shall use the Nrouter_SMService API.

The API URI of the Nrouter_SMService 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 "nrouter-smservice".

– The <apiVersion> shall be "v1".

– The <apiSpecificResourceUriPart> shall be set as described in clause 6.2.3.

6.2.2 Usage of HTTP

6.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 Nrouter_SMService API is contained in Annex A.

6.2.2.2 HTTP standard headers

6.2.2.2.1 General

See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.

6.2.2.2.2 Content type

Multipart messages shall also be supported (see clause 6.2.2.4) using the content type "multipart/related", comprising:

– one JSON body part with the "application/json" content type; and

– one binary body part with 3gpp vendor specific content subtypes.

The 3gpp vendor specific content subtypes defined in Table 6.2.2.2.2-1 shall be supported.

Table 6.2.2.2.2-1: 3GPP vendor specific content subtypes

content subtype	Description
vnd.3gpp.sms	Binary encoded payload, encoding SMS payload, as specified in 3GPP TS 23.040 [16] and 3GPP TS 24.011 [17].
NOTE: Using 3GPP vendor content subtypes allows to describe the nature of the opaque payload (e.g. SMS payload) without having to rely on metadata in the JSON payload.

See clause 6.2.2.4 for the binary payloads supported in the binary body part of multipart messages.

6.2.2.3 HTTP custom headers

6.2.2.4 HTTP multipart messages

HTTP multipart messages shall be supported, to transfer opaque SMS payload (e.g. SMS message, CP Ack, etc.), in the following service operations (and HTTP messages):

– MtForwardSm service operation;

HTTP multipart messages shall include one JSON body part and one binary body part comprising content of SMS payload content (see clause 6.2.6.4).

The JSON body part shall be the "root" body part of the multipart message. It shall be encoded as the first body part of the multipart message. The "Start" parameter does not need to be included.

The multipart message shall include a "type" parameter (see IETF RFC 2387 [18]) specifying the media type of the root body part, i.e. "application/json".

A binary body part shall include a Content-ID header (see IETF RFC 2045 [19]), and the JSON body part shall make a reference to the binary body part using the Content-ID header field.

Examples of multipart/related messages can be found in Annex B.

6.2.3 Resources

6.2.3.1 Overview

This clause describes the structure for the Resource URIs and the resources and methods used for the service.

Figure 6.2.3.1-1 depicts the resource URIs structure for the Nrouter_SMService API.

Figure 6.2.3.1-1: Resource URI structure of the Nrouter_SMService API

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

Table 6.2.3.1-1: Resources and methods overview

Resource purpose/name

Resource URI (relative path after API URI)

HTTP method or custom operation

Description (service operation)

MtSmInfo

(Document)

/mt-sm-infos/{gpsi}

PUT

Create Routing Information for MT SMS.

/mt-sm-infos/{gpsi}/sendsms

sendsms

(POST)

It is used for the MtForwardSm service operation, to allow NF Service Consumer to send SMS payload in downlink direction.

6.2.3.2 Resource: MtSmInfos (Store)

6.2.3.2.1 Description

This resource represents the collection of Mobile Terminated Short Message Information in SMS Router.

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

No HTTP method has been defined for this resource.

6.2.3.2.2 Resource Definition

Resource URI: {apiRoot}/nrouter-smsevice/<apiVersion>/mt-sm-infos

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

Table 6.2.3.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.2.1

6.2.3.2.3 Resource Standard Methods

No HTTP method has been defined for the Mobile Terminated Short Message Information collection resource.

6.2.3.3 Resource: MtSmInfo (Document)

6.2.3.3.1 Description

This resource represents an individual Mobile Terminated Short Message Information in SMS Router.

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

6.2.3.3.2 Resource Definition

Resource URI: {apiRoot}/nrouter-smsevice/<apiVersion>/mt-sm-infos/{gpsi}

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

Table 6.2.3.3.2-1: Resource URI variables for this resource

Name

Data type

Definition

apiRoot

string

See clause 6.2.1

gpsi

Represents the Generic Public Subscription Identifier with MSISDN (see 3GPP TS 23.501 [2] clause 5.9.8)

pattern: See pattern of type Gpsi in 3GPP TS 29.571 [15]

6.2.3.3.3 Resource Standard Methods

6.2.3.3.3.1 PUT

This method creates an individual resource of Mobile Terminated Short Message Information in the SMS Router, or updates the indicated resource of Mobile Terminated Short Message Information in the SMS Router.

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

Table 6.2.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 6.2.3.3.3.1-2 and the response data structures and response codes specified in table 6.2.3.3.3.1-3.

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

Data type	P	Cardinality	Description
CreateRoutingData	M	1	Representation of the UE’s Mobile Terminated Short Message Information to be created in the SMS Router, or to be updated in the SMS Router.

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

Data type	P	Cardinality	Response codes	Description
CreatedRoutingData	M	1	201 Created	This case represents the successful creation of an UE’s Mobile Terminated Short Message Information. The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created resource.
CreatedRoutingData	M	1	200 OK	Upon success, a response body containing a representation of the updated UE’s Mobile Terminated Short Message Information shall be returned.
n/a			204 No Content	Upon success, an empty response body shall be returned
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (service) set. (NOTE 2)
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (service) set. (NOTE 2)
NOTE 1: 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. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.2.3.3.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}/nrouter-smsevice/<apiVersion>/mt-sm-infos/{gpsi}

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

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.2.3.3.3.1-6: Headers supported by the 308 Response Code on this resource

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.2.3.3.4 Resource Custom Operations

6.2.3.3.4.1 Overview

Table 6.2.3.3.4.1-1: Custom operations

Operation name	Custom operaration URI	Mapped HTTP method	Description
sendsms	/mt-sm-infos/{gpsii}/sendsms	POST	Send MT SMS message or the related Delivery Report.

6.2.3.3.4.2 Operation: sendsms

6.2.3.3.4.2.1 Description

This custom operation is used for NF Service Consumers to send SMS message in downlink direction.

6.2.3.3.4.2.2 Operation Definition

This custom operation is used to send a SMS payload to an UE’s Mobile Terminated Short Message Information resource in the SMS Router.

This operation shall support the request data structures specified in table 6.2.3.3.4.2.2-1 and the response data structure and response codes specified in table 6.2.3.3.4.2.2-2.

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

Data type	P	Cardinality	Description
SmsData	M	1	Representation of the MT SMS message to be sent.

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

Data type	P	Cardinality	Response codes	Description
SmsDeliveryData	M	1	200 OK	This case represents the successful of sending SMS message in downlink direction, with necessary response data on the received delivery report.
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (service) set. (NOTE 2)
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 this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (service) set. (NOTE 2)
ProblemDetails	O	0..1	400 Bad Request	This case represents an unsuccessful delivery of SMS message. The "cause" attribute may be used to indicate one of the following application errors: – SMS_PAYLOAD_MISSING, if the expected SMS payload content is missing; – SMS_PAYLOAD_ERROR, if error exists in the SMS payload content.
ProblemDetails	O	0..1	404 Not Found	This case represents an unsuccessful delivery of SMS payload. The "cause" attribute may be used to indicate one of the following application errors: – ROUTING_INFO_NOT_FOUND, if the routing information for SMS to be operated is invalid or not found in SMS Router. – USER_NOT_FOUND, if the UE identified by the GPSI is not found in the SMS Router.
NOTE 1: 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. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

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

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

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

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same SMS Router or SMS Router (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

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.2.4 Custom Operations without associated resources

In this release of this specification, no custom operations without associated resources are defined.

6.2.5 Notifications

In this release of this specification, no notification procedures are defined.

6.2.6 Data Model

6.2.6.1 General

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

Table 6.2.6.1-1 specifies the data types defined for the Nrouter_SMService service based interface protocol.

Table 6.2.6.1-1: Nrouter_SMService specific Data Types

Data type	Clause defined	Description	Applicability
CreatedRoutingData	6.2.6.2.2	Information used for receiving the MT SMS.

Table 6.2.6.1-2 specifies data types re-used by the Nrouter_SMService 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 Nrouter_SMService service based interface.

Table 6.2.6.1-2: Nrouter_SMService re-used Data Types

Data type	Reference	Comments	Applicability
CreateRoutingData	6.1.6.2.2	Information used for creating or updating the routing information of the user.
SmsData	6.1.6.2.4	Information within request message invoking MtForwardSm service operation, for delivering MT SMS.
SmsDeliveryData	6.1.6.2.5	Information within response message invoking MtForwardSm service operation, for delivering MT SMS Delivery Report.
ProblemDetails	3GPP TS 29.571 [15]	Common Data Type used in response bodies
RedirectResponse	3GPP TS 29.571 [15]	Redirect Response
Gpsi	3GPP TS 29.571 [15]	General Public Subscription Identifier
NfInstanceId	3GPP TS 29.571 [15]	NF Instance ID
RefToBinaryData	3GPP TS 29.571 [15]	Information for indicating the binary content of SMS payload.
Ipv4Addr	3GPP TS 29.571 [15]	IPv4 address
Ipv6Addr	3GPP TS 29.571 [15]	IPv6 address
SupportedFeatures	3GPP TS 29.571 [15]	Supported Features
Fqdn	3GPP TS 29.571 [15]	Fully Qualified Domain Name

6.2.6.2 Structured data types

6.2.6.2.1 Introduction

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

6.2.6.2.2 Type: CreatedRoutingData

Table 6.2.6.2.2-1: Definition of type CreatedRoutingData

Attribute name	Data type	P	Cardinality	Description	Applicability
routerIpv4	Ipv4Addr	C	0..1	This IE shall be present if available. When present, this IE indicates the IPv4 address of the SMS Router to receive the downlink short message. See NOTE
routerIpv6	Ipv6Addr	C	0..1	This IE shall be present if available. When present, this IE indicates the IPv6 address of the SMS Router to receive the downlink short message. See NOTE
routerFqdn	Fqdn	C	0..1	This IE shall be present if available. When present, this IE indicates the FQDN of the SMS Router to receive the downlink short message. See NOTE
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.1.8 is supported.
NOTE: At least, one of SMS Router addresses shall be included.

6.2.6.3 Simple data types and enumerations

6.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.

6.2.6.3.2 Simple data types

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

Table 6.2.6.3.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

6.2.6.3.3 Enumeration: <EnumType1>

The enumeration <EnumType1> represents <something>. It shall comply with the provisions defined in table 6.1.6.3.3-1.

Table 6.2.6.3.3-1: Enumeration < EnumType1>

Enumeration value	Description	Applicability

6.2.6.4 Data types describing alternative data types or combinations of data types

In this release of this specification, no alternative data types or combinations of data types are defined.

6.2.6.5 Binary data

See clause 6.1.6.5.

6.2.7 Error Handling

6.2.7.1 General

For the Nrouter_SMService 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 Nrouter_SMService API.

6.2.7.2 Protocol Errors

No specific procedures for the Nrouter_SMService service are specified.

6.2.7.3 Application Errors

The application errors defined for the Nrouter_SMService service are listed in Table 6.2.7.3-1.

Table 6.2.7.3-1: Application errors

Application Error	HTTP status code	Description
SMS_PAYLOAD_MISSING	400 Bad Request	The expected SMS payload content is missing.
SMS_PAYLOAD_ERROR	400 Bad Request	Errors exist in the format of SMS payload.
USER_NOT_FOUND	404 Not Found	The provided subscriber identifier is not found.
ROUTING_INFO_NOT_FOUND	404 Not Found	The routing information for SMS to be operated is invalid or not found in SMS Router

6.2.8 Feature negotiation

The optional features in table 6.2.8-1 are defined for the Nrouter_SMService API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].

Table 6.2.8-1: Supported Features

Feature number	Feature Name	Description

6.2.9 Security

As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nrouter_SMService 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 Nrouter_SMService 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 Nrouter_SMService service.

The Nrouter_SMService API defines a single scope "nrouter-smservice" for the entire service, and it does not define any additional scopes at resource or operation level.

6.2.10 HTTP redirection

An HTTP request may be redirected to a different SMS Router service instance, within the same SMS Router or a different SMS Router of an SMS Router set, e.g. when an SMS Router service instance is part of an SMS Router (service) set or when using indirect communications (see 3GPP TS 29.500 [4]).

An SCP that reselects a different SMS Router producer instance will return the NF Instance ID of the new SMS Router 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 SMS Router within an SMS Router set redirects a service request to a different SMS Router of the set using a 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new SMS Router 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