9 Message Gateway API definition
29.5383GPPApplication Programming Interfaces (API) specificationEnabling MSGin5G ServiceRelease 18Stage 3TS
9.1 MSGG_L3GDelivery API
9.1.1 API URI
The MSGG_L3GDelivery service shall use the MSGG_L3GDelivery API, The MSGG_L3GDelivery API corresponding to Ml3g APIs as defined in in 3GPP TS 23.554 [2].
The request URIs used in HTTP requests from the MSGin5G Server towards the Legacy 3GPP Message Gateway shall have the Resource URI structure as defined in clause 7.5 with the following clarifications:
– The <apiName> shall be "msgg-l3gdelivery".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 9.1.3.
9.1.2 Resources
None.
9.1.3 Custom Operations without associated resources
9.1.3.1 Overview
The structure of the custom operation URIs of the MSGG_L3GDelivery service is shown in Figure 9.1.3.1-1.
Figure 9.1.3.1-1: Custom operation URI structure of the MSGG_L3GDelivery API
Table 9.1.3.1-1 provides an overview of the custom operations and applicable HTTP methods.
Table 9.1.3.1-1: Custom operations without associated resources
|
Custom operation URI |
Mapped HTTP method |
Description |
|
{apiRoot}/msgg-l3gdelivery/<apiVersion>/deliver-message |
POST |
Request of MSGin5G Server to deliver message to a given Legacy 3GPP Message Gateway. |
|
{apiRoot}/msgg-l3gdelivery/<apiVersion>/deliver-report |
POST |
Request of MSGin5G Server to deliver status report to a given Legacy 3GPP Message Gateway. |
9.1.3.2 Operation: deliver-message
9.1.3.2.1 Description
This operation is used by the MSGin5G Server to deliver message to a given Legacy 3GPP Message Gateway.
9.1.3.2.2 Operation Definition
This operation shall support the response data structures and response codes specified in table 9.1.3.2.2-1 and table 9.1.3.2.2-2.
Table 9.1.3.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
L3gMessageDelivery |
M |
1 |
Represents the data to be used for MSGin5G Server to deliver message. |
Table 9.1.3.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 |
The Message is Delivered successfully. |
||
|
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
9.1.3.3 Operation: deliver-report
9.1.3.3.1 Description
This operation is used by the MSGin5G Server to deliver status report to a given Legacy 3GPP Message Gateway.
9.1.3.3.2 Operation Definition
This operation shall support the response data structures and response codes specified in Table 9.1.3.3.2-1 and Table 9.1.3.3.2-2.
Table 9.1.3.3.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
DeliveryStatusReport |
M |
1 |
Represents the data to be used for MSGin5G Server to deliver status report. |
Table 9.1.3.3.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 |
The status report is Delivered successfully. |
||
|
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
9.1.4 Notifications
None.
9.1.5 Data Model
9.1.5.1 General
This clause specifies the application data model supported by the API. Data types listed in clause 7.2 apply to this API. Table 9.1.5.1-1 specifies the data types defined specifically for the MSGG_L3GDelivery API service.
Table 9.1.5.1-1: MSGG_L3GDelivery API specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
L3gMessageDelivery |
9.1.5.2.2 |
Information within message delivery request. |
Table 9.1.5.1-2 specifies data types re-used by the MSGG_L3GDelivery API service.
Table 9.1.5.1-2: Re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
DeliveryStatusReport |
8.2.5.2.7 |
The message delivery status report request information. |
|
|
MessageSegmentPapameters |
8.2.5.2.5 |
Contains the message segment information of the message. |
9.1.5.2 Structured data types
9.1.5.2.1 Introduction
9.1.5.2.2 Type: L3gMessageDelivery
Table 9.1.5.2.2-1: Definition of type L3gMessageDelivery
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
oriAddr |
Address |
M |
1 |
The service identity of the originating MSGin5G Client or the originating Application Server. This IE is copied from the associated inbound message (NOTE). |
|
|
destAddr |
Address |
M |
1 |
The service identity of the receiving entity. The receiving entity can only be Legacy 3GPP UE Service ID in MSGG_L3GDelivery API. |
|
|
appId |
string |
O |
0..1 |
Identifies the application(s) for which the payload is intended. This list of Application IDs IE is required when the message is sent to one or multiple Application Clients served by same MSGin5G Client. |
|
|
msgId |
string |
M |
1 |
Unique identifier of this message. This IE is copied from the associated inbound message request |
|
|
delivStReqInd |
boolean |
O |
0..1 |
Indicates if delivery acknowledgement from the recipient is requested. This IE is copied from the associated inbound message. Set to "true" if delivery acknowledgement from the recipient is requested. otherwise set to "false". Default value is "false". |
|
|
payload |
string |
O |
0..1 |
Payload of the message. This IE is copied from the associated inbound message. |
|
|
segInd |
boolean |
O |
0..1 |
Indicates this message is part of a segmented message. Set to "true" if the message is part of a segmented message. otherwise set to "false". Default value is "false". |
|
|
segParams |
MessageSegmentParameters |
O |
0..1 |
The message segment parameters. This IE shall be included only if the value of segInd is true to indicate that message Segment services are requested. |
|
|
NOTE: The addrType in Address data type shall only include AS or UE to represent the originating of message request. |
|||||
9.1.5.2.3 Type: Address
Table 9.1.5.2.3-1: Definition of type Address
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
addrType |
AddressType |
M |
1 |
Represent the type of message request. |
|
|
addr |
string |
M |
1 |
Refer to UE Service ID or AS Service ID or Group Service ID or Broadcast Area ID or Messaging Topic. |
9.1.5.3 Simple data types and enumerations
9.1.5.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
9.1.5.3.2 Enumeration: AddressType
Table 9.1.5.3.2-1: Enumeration AddressType
|
Enumeration value |
Description |
Applicability |
|
UE |
The address type is UE. |
|
|
AS |
The address type is AS. |
|
|
GROUP |
The address type is GROUP. |
|
|
BC |
The address type is BC. |
|
|
TOPIC |
The address type is TOPIC. |
9.1.6 Error Handling
9.1.6.1 General
HTTP error handling shall be supported as specified in clause 7.7.
In addition, the requirements in the following clauses shall apply.
9.1.6.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the MSGG_L3GDelivery API.
9.1.6.3 Application Errors
The application errors defined for the MSGG_L3GDelivery API are listed in table 9.1.6.3-1.
Table 9.1.6.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
Applicability |
9.1.7 Feature negotiation
General feature negotiation procedures are defined in clause 7.8. Table 9.1.7-1 lists the supported features for MSGG_L3GDelivery API.
Table 9.1.7-1: Supported Features
|
Feature number |
Feature Name |
Description |
9.2 MSGG_N3GDelivery API
9.2.1 API URI
The MSGG_N3GDelivery service shall use the MSGG_N3GDelivery API, The MSGG_N3GDelivery API corresponding to Mn3g APIs as defined in in 3GPP TS 23.554 [2].
The request URIs used in HTTP requests from the MSGin5G Server towards the Non-3GPP Message Gateway shall have the Resource URI structure as defined in clause 7.5 with the following clarifications:
– The <apiName> shall be "msgg-n3gdelivery".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 9.2.3.
9.2.2 Resources
None.
9.2.3 Custom Operations without associated resources
9.2.3.1 Overview
The structure of the custom operation URIs of the MSGG_N3GDelivery service is shown in Figure 9.2.3.1-1.
Figure 9.2.3.1-1: Custom operation URI structure of the MSGG_N3GDelivery API
Table 9.2.3.1-1 provides an overview of the custom operations and applicable HTTP methods.
Table 9.2.3.1-1: Custom operations without associated resources
|
Custom operation URI |
Mapped HTTP method |
Description |
|
{apiRoot}/msgg-n3gdelivery/<apiVersion>/deliver-message |
POST |
Request of MSGin5G Server to deliver message to a given Non-3GPP Message Gateway |
|
{apiRoot}/msgg-n3gdelivery/<apiVersion>/deliver-report |
POST |
Request of MSGin5G Server to deliver status report to a given Non-3GPP Message Gateway |
9.2.3.2 Operation: deliver-message
9.2.3.2.1 Description
This operation is used by the MSGin5G Server to deliver message to a given Non-3GPP Message Gateway.
9.2.3.2.2 Operation Definition
This operation shall support the response data structures and response codes specified in table 9.2.3.2.2-1 and table 9.2.3.2.2-2.
Table 9.2.3.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N3gMessageDelivery |
M |
1 |
Represents the data to be used for MSGin5G Server to deliver message. |
Table 9.2.3.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 |
The Message is Delivered successfully. |
||
|
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. |
||||
9.2.3.3 Operation: deliver-report
9.2.3.3.1 Description
This operation is used by the MSGin5G Server to deliver status report to a given Non-3GPP Message Gateway.
9.2.3.3.2 Operation Definition
This operation shall support the response data structures and response codes specified in table 9.2.3.3.2-1 and table 9.2.3.3.2-2.
Table 9.2.3.3.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
DeliveryStatusReport |
M |
1 |
Represents the data to be used for MSGin5G Server to deliver status report. |
Table 9.2.3.3.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 |
The status report is Delivered successfully. |
||
|
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. |
||||
9.2.4 Notifications
None.
9.2.5 Data Model
9.2.5.1 General
This clause specifies the application data model supported by the API. Data types listed in clause 7.2 apply to this API. Table 9.2.5.1-1 specifies the data types defined specifically for the MSGG_N3GDelivery API service.
Table 9.2.5.1-1: MSGG_N3GDelivery API specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
N3gMessageDelivery |
9.2.5.2.2 |
Information within message delivery request. |
Table 9.2.5.1-2 specifies data types re-used by the MSGG_N3GDelivery API service.
Table 9.2.5.1-2: Re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
DeliveryStatusReport |
8.2.5.2.7 |
The message delivery status report request information. |
|
|
MessageSegmentPapameters |
8.2.5.2.5 |
Contains the message segment information of the message. |
|
|
Address |
9.1.5.2.3 |
The data type of the oriAddr and destAddr. |
9.2.5.2 Structured data types
9.2.5.2.1 Introduction
9.2.5.2.2 Type: N3gMessageDelivery
Table 9.2.5.2.2-1: Definition of type N3gMessageDelivery
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
oriAddr |
Address |
M |
1 |
The oriAddr is the service identity of the originating MSGin5G Client or the originating Application Server. This IE is copied from the associated inbound message (NOTE). |
|
|
destAddr |
Address |
M |
1 |
The destAddr is the service identity of the receiving entity. The receiving entity can only be Non-3GPP UE Service ID in MSGG_N3GDelivery API. |
|
|
appId |
string |
O |
0..1 |
Identifies the application(s) for which the payload is intended. This list of Application IDs IE is required when the message is sent to one or multiple Application Clients served by same MSGin5G Client. |
|
|
msgId |
string |
M |
1 |
Unique identifier of this message. This IE is copied from the associated inbound message request. |
|
|
delivStReqInd |
boolean |
O |
0..1 |
Indicates if delivery acknowledgement from the recipient is requested. This IE is copied from the associated inbound message. Set to "true" if delivery acknowledgement from the recipient is requested. otherwise set to "false". Default value is "false". |
|
|
payload |
string |
O |
0..1 |
Payload of the message. This IE is copied from the associated inbound message. |
|
|
segInd |
boolean |
O |
0..1 |
Indicates this message is part of a segmented message. Set to "true" if the message is part of a segmented message. otherwise set to "false". Default value is "false". |
|
|
segParams |
MessageSegmentParameters |
O |
0..1 |
The message segment parameters. This IE shall be included only if the value of segInd is true to indicate that message Segment services are requested. |
|
|
NOTE: The addrType in Address data type shall only include AS or UE to represent the originating of message request. |
|||||
9.2.6 Error Handling
9.2.6.1 General
HTTP error handling shall be supported as specified in clause 7.7.
In addition, the requirements in the following clauses shall apply.
9.2.6.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the MSGG_N3GDelivery API.
9.2.6.3 Application Errors
The application errors defined for the MSGG_N3GDelivery API are listed in table 9.2.6.3-1.
Table 9.2.6.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
Applicability |
9.2.7 Feature negotiation
General feature negotiation procedures are defined in clause 7.8. Table 9.2.7-1 lists the supported features for MSGG_N3GDelivery API.
Table 9.2.7-1: Supported Features
|
Feature number |
Feature Name |
Description |