5 Services offered by the MSGin5G Servers

29.5383GPPApplication Programming Interfaces (API) specificationEnabling MSGin5G ServiceRelease 18Stage 3TS

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

5.1 Introduction

The Table 5.1-1 lists the services provided by the MSGin5G Server and corresponding service operations. A service description clause for each API gives a general description of the related API.

Table 5.1-1 List of services provided by the MSGin5G Servers

Service Name	Service Operations	Operation Semantics	Example Consumer(s)
MSGS_ASRegistration	MSGS_ASRegistration_Request	Request/Response	AS
	MSGS_ASRegistration_Deregister
MSGS_MSGDelivery	MSGS_MSGDelivery_ASODelivery	Request/ Response	AS, Legacy 3GPP Message Gateway, Non-3GPP Message Gateway
	MSGS_MSGDelivery_ASODeliveryReport
	MSGS_MSGDelivery_UEODelivery
	MSGS_MSGDelivery_UEODeliveryReport

Table 5.1-2 summarizes the corresponding APIs defined in this specification.

Table 5.1-2: API Descriptions

Service Name	Clause	Description	OpenAPI Specification File	apiName	Annex
MSGS_ASRegistration	8.1	AS Registration Service	TS29538_MSGS_ASRegistration.yaml	Msgs-asregistration	A.2
MSGS_MSGDelivery	8.2	Message Delivery Service	TS29538_MSGS_MSGDelivery.yaml	Msgs-msgdelivery	A.3

5.2 MSGS_ASRegistration Service

5.2.1 Service Description

The MSGS_ASRegistration API, as defined in 3GPP TS 23.554 [2], allows an AS via Mm5s interface to register, and deregister at a given MSGin5G Server.

5.2.2 Service Operations

5.2.2.1 Introduction

The service operation defined for MSGS_ASRegistration API is shown in the Table 5.2.2.1-1.

Table 5.2.2.1-1: Operations of the MSGS_ASRegistration API

Service operation name	Description	Initiated by
MSGS_ASRegistration_Request	This service operation is used by the AS to register itself to MSGin5G Server.	AS
MSGS_ASRegistration_Deregister	This service operation is used by the AS to deregister itself from a MSGin5G Server.	AS

5.2.2.2 MSGS_ASRegistration_Request

5.2.2.2.1 General

This service operation is used by the AS to register itself to MSGin5G Server.

5.2.2.2.2 Application Server registering to MSGin5G Server using MSGS_ASRegistration_Request operation

Figure 5.2.2.2.2-1: AS Registering to MSGin5G Server

To register itself at the MSGin5G Server, the AS shall send an HTTP POST message to the MSGin5G Server on the "AS Registrations" collection resource. The body of the HTTP POST message shall include ASRegistration data structure that shall include:

– the Application Server Identifier within the "asSvcId" attribute; and

may include:

– the Application Identifier within the "appId" attribute;

– the notification target URI within the "targetUri" attribute; and

– the Application Server Profile Information within the "asProf" attribute, that may include:

– the Application Server name within the "appName" attribute;

– the list of Application Providers name within the "appProviders" attribute;

– the list of Application scenarios within the "appScenarios" attribute;

– the list of Application Server category within the "appCategory" attribute; and

– the list of Application Server status within the "asStatus" attribute.

Upon receiving the HTTP POST message from the AS, the MSGin5G Server shall:

1. process the AS registration request information;

2. verify the identity of the AS and check if the AS is authorized to register itself at MSGin5G Server; and

3. if the AS is authorized to register to MSGin5G Server, then the MSGin5G Server shall:

a. store the AS registration information and create a new resource with the AS registration information as specified in clause 8.1.2.1; and

b. If the registration is successful, the MSGin5G Server shall respond to the AS with an HTTP "201 Created" status code, including an HTTP Location header field containing the URI of the created "AS Registration" resource and the response body containing ASRegistrationAck data structure that shall contain:

– the Application Server Identifier within the "asSvcId" attribute; and

– the registration result within the "result" attribute.

If errors occur when processing the HTTP POST request, the MSGin5G Server shall apply error handling procedures as specified in clause 8.1.6.

5.2.2.3 MSGS_ASRegistration_Deregister

5.2.2.3.1 General

This service operation is used by the AS to deregister itself from a MSGin5G Server.

5.2.2.3.2 Application Server deregistering from MSGin5G Server using MSGS_ASRegistration_Deregister operation

Figure 5.2.2.3.2-1: AS Deregistering from MSGin5G Server

To deregister itself from the MSGin5G Server, the AS shall send HTTP DELETE message to the MSGin5G Server on the "AS DeRegistration" collection resource, as specified in clause 8.1.2.3.3.2.

Upon receiving the HTTP DELETE request, the MSGin5G Server shall:

1. verify the identity of the AS and check if the AS is authorized to deregister the AS registration information;

2. if the AS is authorized to deregister the AS registration information, then the MSGin5G Server shall deregister the AS profile from the MSGin5G Server and delete the resource representing AS registration information; and

3. return the HTTP "200 OK" status code to the AS, indicating the successful deregistration of the AS information and shall include ASRegistrationAck data structure within the response body or HTTP "204 No Content" status code to the AS.

If errors occur when processing the HTTP DELETE request, the MSGin5G Server shall apply error handling procedures as specified in clause 8.1.6.

5.3 MSGS_MSGDelivery Service

5.3.1 Service Description

The MSGS_MSGDelivery Service corresponding to Mm5s as defined in 3GPP TS 23.554 [2], is provided by the MSGin5G Server.

This service:

– allows AS invokes services provided by MSGin5G Server to send MSGin5G Messages to MSGin5G Server; and

– allows L3G/N3G invokes services provided by MSGin5G Server to send MSGin5G Messages to MSGin5G Server on behalf of Legacy 3GPP UE or Non-3GPP UE.

5.3.2 Service Operations

5.3.2.1 Introduction

The service operation defined for MSGS_MSGDelivery Service is shown in the Table 5.3.2.1-1.

Table 5.3.2.1-1: Operations of the MSGS_MSGDelivery Service

Service operation name	Description	Initiated by
MSGS_MSGDelivery_ASODelivery	This service operation is used by AS to deliver MSGin5G message to the MSGin5G Server. This service operation corresponds to clause 9.1.1.1.2 as defined in 3GPP TS 23.554 [2].	AS
MSGS_MSGDelivery_ASODeliveryReport	This service operation is used by AS to deliver the delivery status report to the MSGin5G Server. This service operation corresponds to clause 9.1.1.2.2 as defined in 3GPP TS 23.554 [2].	AS
MSGS_MSGDelivery_UEODelivery	This service operation is used by Legacy 3GPP Message Gateway or Non-3GPP Message Gateway (on behalf of Legacy 3GPP UE or Non-3GPP UE) to deliver MSGin5G message to the MSGin5G Server. This service operation corresponds to clause 9.1.1.3.2 as defined in 3GPP TS 23.554 [2].	Legacy 3GPP Message Gateway Non-3GPP Message Gateway
MSGS_MSGDelivery_UEODeliveryReport	This service operation is used by Legacy 3GPP Message Gateway or Non-3GPP Message Gateway (on behalf Legacy 3GPP UE or Non-3GPP UE) to deliver the delivery status report to the MSGin5G Server. This service operation corresponds to clause 9.2.1.4.2 as defined in 3GPP TS 23.554 [2].	Legacy 3GPP Message Gateway Non-3GPP Message Gateway

5.3.2.2 MSGS_MSGDelivery_ASODelivery

5.3.2.2.1 General

This service operation corresponding to clause 9.1.1.1.2 as defined in 3GPP TS 23.554 [2], is used by AS to deliver MSGin5G message to the MSGin5G Server.

5.3.2.2.2 AS Originating MSGin5G Message Delivery

Figure 5.3.2.2.2-1: AS Originating MSGin5G Message Delivery

When the AS needs to send the message to the MSGin5G Server, the AS shall send the HTTP POST method as step 1 of the Figure 5.3.2.2.2-1.

The AS shall include ASMessageDelivery data structure in the payload body of the HTTP POST request.

The ASMessageDelivery data structure shall include:

– the AS Service ID within the "oriAddr" attribute;

– the Recipient Address within the "destAddr" attribute;

– the Message ID within the "msgId" attribute;

– the store and forward flag within the "stoAndFwInd" attribute; and

may include:

– the Application ID within the "appId" attribute;

– the security credentials within the "secCred" attribute;

– the indication whether the message delivery status report is required within the "delivStReqInd" attribute;

– the Payload within the "payload" attribute;

– the priority type within the "priority" attribute;

– the message segment flag within the "segInd" attribute;

– the message segment parameters within the "segParams" attribute, this attribute may include:

– the segmentation set identifier within the "segId" attribute;

– the total number of message segments within the "totalSegCount" attribute;

– the message segment number within the "segNumb" attribute; and

– the last segment flag within the "lastSegFlag" attribute;

– the store and forward parameters within the "stoAndFwParams" attribute, this attribute may include:

– the message expiration time within the "exprTime" attribute;

– The latency within the "latency" attribute.

When the MSGin5G Server receives the HTTP POST request from the AS, the MSGin5G Server shall make an authorization based on the information received from the AS. If the authorization is successful, the MSGin5G Server shall respond to the AS with a 200 OK message.

If errors occur when processing the HTTP POST request, the MSGin5G Server shall apply error handling procedures as specified in clause 8.2.6.

5.3.2.3 MSGS_MSGDelivery_ASODeliveryReport

5.3.2.3.1 General

This service operation corresponds to clause 9.1.1.2.2 as defined in 3GPP TS 23.554 [2], is used by AS to deliver the delivery status report to the MSGin5G Server.

5.3.2.3.2 AS Originating Message Delivery Status Report

Figure 5.3.2.3.2-1: AS Originating MSGin5G Delivery Report

When the AS needs to send the delivery report to the MSGin5G Server, the AS shall send the HTTP POST method as step 1 of the Figure 5.3.2.3.2-1.

The AS shall include DeliveryStatusReport data structure in the payload body of the HTTP POST request.

The DeliveryStatusReport data structure shall include:

– the AS Service ID within the "oriAddr" attribute;

– the Recipient Address within the "destAddr" attribute;

– the Message ID within the "msgId" attribute;

– the delivery status within the "delivSt" attribute; and

may include:

– the security credentials within the "secCred" attribute; and

– the failure cause within the "failureCause" attribute;

If errors occur when processing the HTTP POST request, the MSGin5G Server shall apply error handling procedures as specified in clause 8.2.6.

5.3.2.4 MSGS_MSGDelivery_UEODelivery

5.3.2.4.1 General

This service operation corresponds to clause 9.1.1.3.2 as defined in 3GPP TS 23.554 [2], is used by Legacy 3GPP Message Gateway or Non-3GPP Message Gateway (on behalf of Legacy 3GPP UE or Non-3GPP UE) to deliver MSGin5G message to the MSGin5G Server.

5.3.2.4.2 UE Originating Message Delivery

Figure 5.3.2.4.2-1: Legacy 3GPP UE or Non-3GPP UE Originating MSGin5G Message Delivery

When the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway (on behalf of Legacy 3GPP UE or Non-3GPP UE) needs to send the message to the MSGin5G Server, the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway shall send the HTTP POST method as step 1of the Figure 5.3.2.4.2-1.

The Legacy 3GPP Message Gateway or Non-3GPP Message Gateway shall include UEMessageDelivery data structure in the payload body of the HTTP POST request.

The UEMessageDelivery data structure shall include:

– the Originating UE Service ID within the "oriAddr" attribute;

– the Recipient Address within the "destAddr" attribute;

– the Message ID within the "msgId" attribute; and

– the store and forward flag within the "stoAndFwInd" attribute;

and may include:

– the Application ID within the "appId" attribute;

– the security credentials within the "secCred" attribute;

– the Payload within the "payload" attribute;

– the indication whether the message delivery status report is required within the "delivStReqInd" attribute; and

– the message segment flag within the "segInd" attribute;

– the message segment parameters within the "segParams" attribute, this attribute may include:

– the segmentation set identifier within the "segId" attribute;

– the total number of message segments within the "totalSegCount" attribute;

– the message segment number within the "segNumb" attribute;

– the last segment flag within the "lastSegFlag" attribute;

– the store and forward parameters within the "stoAndFwParams" attribute, this attribute may include:

– the message expiration time within the "exprTime" attribute;

When the MSGin5G Server receives the HTTP POST request from the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway, the MSGin5G Server shall make an authorization based on the information received from the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway. If the authorization is successful, the MSGin5G Server shall respond to the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway with a 200 OK message.

If errors occur when processing the HTTP POST request, the MSGin5G Server shall apply error handling procedures as specified in clause 8.2.6.

5.3.2.5 MSGS_MSGDelivery_UEODeliveryReport

5.3.2.5.1 General

This service operation corresponds to clause 9.2.1.4.2 as defined in 3GPP TS 23.554 [2], is used by Legacy 3GPP Message Gateway or Non-3GPP Message Gateway (on behalf Legacy 3GPP UE or Non-3GPP UE) to deliver the delivery status report to the MSGin5G Server.

5.3.2.5.2 UE Originating Message Delivery Status Report

Figure 5.3.2.5.2-1: Legacy 3GPP UE or Non-3GPP UE Originating MSGin5G Delivery Report

When the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway (on behalf of Legacy 3GPP UE or Non-3GPP UE) needs to send the delivery report to the MSGin5G Server, the Legacy 3GPP Message Gateway or Non-3GPP Message Gateway shall send the HTTP POST method as step 1 of the Figure 5.3.2.5.2-1.

The Legacy 3GPP Message Gateway or Non-3GPP Message Gateway shall include DeliveryStatusReport data structure in the payload body of the HTTP POST request.

The DeliveryStatusReport data structure shall include:

– the Originating UE Service ID within the "oriAddr" attribute;

– the Recipient Address within the "destAddr" attribute;

– the Message ID within the "msgId" attribute; and

– the delivery status within the "delivSt" attribute;

and may include:

– the security credentials within the "secCred" attribute;

– The failure cause within the "failureCause" attribute;

If errors occur when processing the HTTP POST request, the MSGin5G Server shall apply error handling procedures as specified in clause 8.2.6.