6 API Definitions
29.5793GPP5G SystemInterworking MSC For Short Message ServicesRelease 18Stage 3TS
6.1 Niwmsc_SMService Service API
6.1.1 Introduction
The Niwmsc_SMService shall use the Niwmsc_SMService API.
The API URI of the Niwmsc_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 "niwmsc-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 Niwmsc_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):
– MoForwardSm 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 Niwmsc_SMService API.
Figure 6.1.3.1-1: Resource URI structure of the Niwmsc_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) |
|
SMService |
/mo-sm-info/{supi}/sendsms |
sendsms (POST) |
MO short message transfer |
6.1.3.2 Resource: MoSmInfo
6.1.3.2.1 Description
This resource represents the collection of Mobile Originated Short Message Information in SMS-IWMSC.
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}/<apiName>/<apiVersion>/mo-sm-info{supi}
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 |
|
supi |
Supi |
Represents the Subscription Permanent Identifier (see 3GPP TS 23.501 [2] clause 5.9.2) |
6.1.3.2.3 Resource Standard Methods
No HTTP method has been defined for the Mobile Originated Short Message Information collection resource.
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
|
Operation name |
Custom operaration URI |
Mapped HTTP method |
Description |
|
sendsms |
/mo-sm-infos/{supi}/sendsms |
POST |
Send MO SMS message or the related Delivery Report. |
6.1.3.2.4.2 Operation: sendsms
6.1.3.2.4.2.1 Description
This custom operation is used for NF Service Consumers to send SMS message in uplink direction.
6.1.3.2.4.2.2 Operation Definition
This custom operation is used to send a SMS payload to an UE’s Mobile Originated Short Message Information resource in the SMS-IWMSC.
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 |
|
SmsData |
M |
1 |
Representation of the MO SMS message to be sent. |
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 |
|
SmsDeliveryData |
M |
1 |
200 OK |
This case represents the successful of sending SMS message in uplink 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-IWMSC or SMS-IWMSC (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-IWMSC or SMS-IWMSC (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 |
403 Forbidden |
This case represents an unsuccessful delivery of SMS message. The "cause" attribute may be used to indicate one of the following application errors: – UNKNOWN_SERVICE_CENTRE_ADDRESS, if the SMS-SC was unknown; – SERVICE_CENTRE_CONGESTION, if the SMS-SC was in congestion; – USER_NOT_SERVICE_CENTER, if the user didn’t belongs to the SMS-SC; – FACILITY_NOT_SUPPORTED, if the facility not supported; – INVALID_SME_ADDRESS, if the SME address is invalid.. |
|
ProblemDetails |
O |
0..1 |
504 Gateway Timeout |
This case represents an unsuccessful delivery of SMS message. The "cause" attribute may be used to indicate one of the following application errors: – UNREACHABLE_SMS_SC, if the response is timeout. |
|
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 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 SMS-IWMSC or SMS-IWMSC (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 SMS-IWMSC or SMS-IWMSC (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
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 Niwmsc_SMService service based interface protocol.
Table 6.1.6.1-1: Niwmsc_SMService specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
N/A |
Table 6.1.6.1-2 specifies data types re-used by the Niwmsc_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 Niwmsc_SMService service based interface.
Table 6.1.6.1-2: Niwmsc_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 |
|
|
Supi |
3GPP TS 29.571 [15] |
Subscription Permanent Identifier |
|
|
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 |
|
|
SmsData |
3GPP TS 29.577 [17] |
Information within request message invoking MoForwardSm service operation, for delivering MO SMS. |
|
|
SmsDeliveryData |
3GPP TS 29.571 [17] |
Information within response message invoking MoForwardSm service operation, for delivering MO SMS Delivery Report. |
6.1.6.2 Structured data types
In this release of this specification, no structure to be used in resource representations is defined.
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 |
|
N/A |
6.1.6.4 Data types describing alternative data types or combinations of data types
None.
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.4.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 [18], 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 [18].
6.1.7 Error Handling
6.1.7.1 General
For the Niwmsc_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 Niwmsc_SMService API.
6.1.7.2 Protocol Errors
No specific procedures for the Niwmsc_SMService service are specified.
6.1.7.3 Application Errors
The application errors defined for the Niwmsc_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. |
|
SERVICE_CENTRE_CONGESTION |
403 Forbidden |
The delivery of the MO short message failed because SMS-SC was in congestion. |
|
USER_NOT_SERVICE_CENTER |
403 Forbidden |
The delivery of the short message failed because the user didn’t belongs to the SMS-SC. |
|
FACILITY_NOT_SUPPORTED |
403 Forbidden |
The delivery of the MO short message failed because of facility not supported. |
|
INVALID_SME_ADDRESS |
403 Forbidden |
The delivery of the MO short message failed because the SME address is invalid. |
|
UNREACHABLE_SMS_SC |
504 Gateway Timeout |
The delivery of the MO short message failed because the response is timeout. |
6.1.8 Feature negotiation
The optional features in table 6.1.8-1 are defined for the Niwmsc_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 |
|
N/A |
6.1.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Niwmsc_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 Niwmsc_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 Niwmsc_SMService service.
The Niwmsc_SMService API defines a single scope "niwmsc-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 SMS-IWMSC service instance, within the same SMS-IWMSC or a different SMS-IWMSC of an SMS-IWMSC set, e.g. when an SMS-IWMSC service instance is part of an SMS-IWMSC (service) set or when using indirect communications (see 3GPP TS 29.500 [4]).
An SCP that reselects a different SMS-IWMSC producer instance will return the NF Instance ID of the new SMS-IWMSC 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-IWMSC within an SMS-IWMSC set redirects a service request to a different SMS-IWMSC of the set using a 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new SMS-IWMSC 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