7 Common information applicable to several APIs

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

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

7.1 General

MSGin5G APIs allow secure access to the capabilities provided by the MSGin5G.

This document specifies the procedures triggered at different functional entities as a result of API invocation requests and event notifications. The stage-2 level requirements and signalling flows are defined in 3GPP TS 23.554 [2].

Several design aspects, as mentioned in the following clauses, are specified in 3GPP TS 29.500 [4] and referenced by this specification.

7.2 Data Types

7.2.1 General

This clause defines structured data types, simple data types and enumerations that are applicable to several APIs defined in the present specification and can be referenced from data structures defined in the subsequent clauses.

In addition, data types that are defined in OpenAPI Specification [6] can also be referenced from data structures defined in the subsequent clauses.

NOTE: As a convention, data types in the present specification are written with an upper-case letter in the beginning. Parameters are written with a lower-case letter in the beginning. As an exception, data types that are also defined in OpenAPI Specification [6] can use a lower-case case letter in the beginning for consistency.

Table 7.2.1-1 specifies data types re-used by the MSGin5G from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the APIs of this specification.

Table 7.2.1-1: Re-used Data Types

Data type	Reference	Comments

7.2.2 Referenced structured data types

Table 7.2.2-1 lists structured data types defined in this specification referenced by multiple services.

Table 7.2.2-1: Referenced Structured Data Types

Data type	Reference	Description
Address	Clause 9.1.5.2.3	Represent an address
DeliveryStatusReport	Clause 8.2.5.2.7	The message delivery status report request information.
MessageSegmentParameters	Clause 8.2.5.2.5	Parameters for message segmentation

7.2.3 Referenced Simple data types and enumerations

Following simple data types defined in Table 7.2.3.1-1 are applicable to several APIs in this document:

Table 7.2.3.1-1: Simple data types applicable to several APIs

Type name	Reference	Description

7.3 Usage of HTTP

For MSGin5G APIs, support of HTTP/1.1 (IETF RFC 7230 [10], IETF RFC 7231 [11], IETF RFC 7232 [12], IETF RFC 7233 [13], IETF RFC 7234 [14] and IETF RFC 7235 [15]) over TLS is mandatory and support of HTTP/2 (IETF RFC 7540 [16]) over TLS is recommended.

A functional entity desiring to use HTTP/2 shall use the HTTP upgrade mechanism to negotiate applicable HTTP version as described in IETF RFC 7540 [16].

7.4 Content type

JSON, IETF RFC 8259 [17], 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".

7.5 URI structure

7.5.1 Resource URI structure

The resource URI structure of all the APIs specified in this document shall be as specified in clause 5.2.4 of 3GPP TS 29.501 [9].

7.5.2 Custom operations URI structure

The custom operation definition is in Annex C of 3GPP TS 29.501 [9].

The URI of a custom operation which is associated with a resource shall have the following structure:

{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>/<custOpName>

Custom operations can also be associated with the service instead of a resource. The URI of a custom operation which is not associated with a resource shall have the following structure:

{apiRoot}/<apiName>/<apiVersion>/<custOpName>

In the above URI structures, "apiRoot", "apiName", "apiVersion" and "apiSpecificResourceUriPart" are as defined in clause 7.5.1 and "custOpName" represents the name of the custom operation as defined in clause 5.1.3.2 of 3GPP TS 29.501 [9].

7.6 Notifications

None.

7.7 Error Handling

HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [4].

7.8 Feature negotiation

The procedures in clause 6.6.2 of 3GPP TS 29.500 [4] shall be applicable for the APIs defined in the present specification. For each of the APIs defined, the applicable list of features is contained in the related API definition.

7.9 HTTP headers

The MSGin5G API shall support mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] and may support HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [4]. No specific custom headers are defined for the MSGin5G API in the present specification.

7.10 Conventions for Open API specification files

The conventions for Open API specification files as specified in clause 5.3 of 3GPP TS 29.501 [9] shall be applicable for all APIs in this document.