Content for TS 29.501 Word version: 18.4.0

1… 4… 4.3… 4.4… 4.6… 4.6.2… 4.7… 4.8… 4.9… 4.10 5… 5.2… 5.3… 6… A… D E…

3.1 Definitions 3.2 Abbreviations 3.3 Special characters, operators and delimiters 3.3.1 General 3.3.2 ABNF operators 3.3.3 URI reserved and special characters 3.3.4 SBI specific usage of delimiters
...

1 Scope p. 7

The present document defines design principles and documentation guidelines for 5GC SBI APIs. These principles and guidelines should be followed when drafting the 5G System SBI Stage 3 specifications.

2 References p. 7

The following documents contain provisions which, through reference in this text, constitute provisions of the present document.

References are either specific (identified by date of publication, edition number, version number, etc.) or non-specific.
For a specific reference, subsequent revisions do not apply.
For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same Release as the present document.

[1]

TR 21.905: "Vocabulary for 3GPP Specifications".

[2]

TS 29.500: "5G System; Technical Realization of Service Based Architecture; Stage 3".

[3]

RFC 8259: "The JavaScript Object Notation (JSON) Data Interchange Format".

[4]

OpenAPI: "OpenAPI Specification Version 3.0.0", https://spec.openapis.org/oas/v3.0.0.

[5]

TS 29.571: "5G System; Common Data Types for Service Based Interfaces Stage 3".

[6]

RFC 7231: "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content".

[7]

RFC 7396: "JSON Merge Patch".

[8]

RFC 6902: "JavaScript Object Notation (JSON) Patch".

[9]

RFC 3986: "Uniform Resource Identifier (URI): Generic Syntax".

[10]

RFC 5789: "PATCH Method for HTTP".

[11]

RFC 8288: "Web Linking".

[12]

IANA: "HTTP Status Code Registry at IANA", http://www.iana.org/assignments/http-status-codes.

[13]

RFC 7540: "Hypertext Transfer Protocol Version 2 (HTTP/2)".

[14]

Fielding, Roy Thomas: Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000.

[15]

Erik Wilde, Cesare Pautasso, REST: From Research to Practice, Springer.

[16]

YAML 1.2: "YAML Ain't Markup Language", http://yaml.org.

[17]

Semantic Versioning Specification: https://semver.org.

[18]

TS 29.510: "5G System; Network Function Repository Services; Stage 3".

[19]

RFC 9457: "Problem Details for HTTP APIs".

[20]

TS 29.502: "5G System; Session Management Services; Stage 3".

[21]

TS 29.509: "5G System; Authentication Server Services; Stage 3".

[22]

TS 33.501: "Security architecture and procedures for 5G system".

[23]

RFC 6749: "The OAuth 2.0 Authorization Framework".

[24]

TS 29.573: "5G System; Public Land Mobile Network (PLMN) Interconnection;Stage 3".

[25]

TR 21.900: "Technical Specification Group working methods".

[26]

RFC 5234: "Augmented BNF for Syntax Specifications: ABNF".

[27]

TS 23.003: "Numbering, addressing and identification".

[28]

TS 29.503: "5G System; Unified Data Management Services; Stage 3".

3 Definitions and abbreviations p. 8

3.1 Definitions p. 8

For the purposes of the present document, the terms and definitions given in TR 21.905 and the following apply. A term defined in the present document takes precedence over the definition of the same term, if any, in TR 21.905.

Absolute URI:

Absolute URI follows generic URI syntax and consists of a hierarchical sequence of the following components: the "scheme", "authority", "path" and "query", i.e. excluding the "fragment" component. See Section 4.3 in RFC 3986.

apiRoot:

apiRoot follows an absolute URI syntax, but excludes the following absolute URI identifiers: the "query" and "fragment" components. The API root contains the "scheme" and the "authority" components and may also contain an API prefix subcomponent. See clause 4.4.1. In 3GPP APIs, the default apiRoot value is "https://example.com" (see e.g. Annex A.2 in TS 29.502), where "example.com" is replaced by the operator specific FQDN (for FQDN examples see clause 28.3.2 in TS 23.003).

API Prefix:

API prefix is an optional, deployment-specific string, which is a subcomponent of the "apiRoot". API prefix format follows "path-absolute" syntax and that starts with a "/" reserved character (see clause 4.4.1 and also Section 3.3 in RFC 3986). In 3GPP APIs, the default apiRoot does not contain API Prefix (see e.g. Annex A.2 in TS 29.502).

API URI:

API URI has the following format: "{apiRoot}/<apiName>/<apiVersion>". For more details see clause 4.4.1. As an example, for the Nudm_SDM API defined in TS 29.503, the API URI is: "{apiRoot}/nudm-sdm/v2".

Base URI:

Base URI is used as a reference against which the relative URI reference is applied. See clause 4.6.1.1.1.2 and also Section 5.1 in RFC 3986. As an example, for the resource URI of the SM contexts collection that is defined in Nsmf_PDUSession API (see TS 29.502), the base URI is "{apiRoot}/nsmf-pdusession/<apiVersion>".

Callback URI:

Callback URI follows an absolute URI syntax, but excludes the following absolute URI identifiers: "userinfo" subcomponent of the "authority" component and also the "query" component ("fragment" component is already excluded from the absolute URI). Therefore, callback URI contains the "scheme", "authority" (excluding "userinfo" subcomponent) and the "path" components. See clause 4.4.3. As an example, for the Nsmf_PDUSession API defined in TS 29.502, "smContextStatusUri" is one of the callback references that can be provided by the NF Service Consumer. A complete callback URI for the "smContextStatusUri" has the following structure https://<comsumer-host>/<consumer-path-segment>/smContextStatus, where "consumer-host" is either an FQDN or an IP address (see clause 4.4.3).

Relative path after API URI:

Refers to the sequence of path segments of a resource URI that are below the API URI (see the definition of the "Paths Object" in OpenAPI specification [4]). When appended to the API URI of the concerned API, it constitutes the resource URI. As an example, for the Nudm_SDM API defined in TS 29.503 for which the API URI is "{apiRoot}/nudm-sdm/v2", the "relative path after API URI" for the "AccessAndMobilitySubscriptionData" resource is: "/{supi}/am-data".

Relative URI:

Relative URI is deprecated and shall not be used in SBI spcifications. See Section 1.2.3 in RFC 3986.

Resource URI:

Resource URI identifies an abstract or a physical resource. See the Abstract of the IETF RFC 3986. In this specification this generally means "an URI of a resource". Resource URI structure is defined in clause 4.4.1. As an example, for the resource URI of the SM contexts collection that is defined in Nsmf_PDUSession API (see TS 29.502), the resource URI is "{apiRoot}/nsmf-pdusession/<apiVersion>/sm-contexts".

3.2 Abbreviations p. 9

For the purposes of the present document, the abbreviations given in TR 21.905 and the following apply. An abbreviation defined in the present document takes precedence over the definition of the same abbreviation, if any, in TR 21.905.

5GC

5G Core Network

CNF

Conjunctive Normal Form

CRUD

Create, Read, Update, Delete

DNF

Disjunctive Normal Form

HAL

Hypertext Application Language

HATEOAS

Hypermedia as the Engine of Application State

REST

REpresentational State Transfer

RPC

Remote-Procedure-Call

SBI

Service Based Interface

YAML

YAML Ain't Markup Language

3.3 Special characters, operators and delimiters |R16| p. 9

3.3.1 General p. 9

A number of characters have special meaning and are used as delimiters in this document and also in other stage 3 SBI specifications. Below clauses specify the usage of a selected set of the special characters. Full set of these special characters are specified in the respective IETF specifications.

3.3.2 ABNF operators p. 9

Special characters that are used as delimiters in ABNF syntax have somewhat different purpose from the same characters when used by URI syntax. See clause 3.3.2 in TS 29.500.

3.3.3 URI reserved and special characters p. 9

Reserved character. The forward slash character is a delimiter, which precedes an URI path component and also separates a sequence of path segments. See Section 2.2 in RFC 3986 and Section 3.3 in RFC 3986.

Reserved character. The number sign (hash) character is a delimiter, which terminates either an URI path component, or an authority component, or a query component and starts a fragment component. See Section 2.2 in RFC 3986, Section 3.2 in RFC 3986, Section 3.3 in RFC 3986 and Section 3.5 in RFC 3986.

Reserved character. The question mark character is a delimiter, which terminates either an URI path component, or an authority component and starts a query component/parameter. See Section 2.2 in RFC 3986, Section 3.2 in RFC 3986, Section 3.3 in RFC 3986 and Section 3.4 in RFC 3986..

Reserved character. The equal sign character is a delimiter, which separates a parameter name and its value, e.g. in an URI query. See Section 1.2.3 in RFC 3986 and Section 3.3 in RFC 3986.

[ ]

Reserved character. The square bracket characters enclose an IPv6 literal address. This is the only place where square bracket characters are allowed in the URI syntax. See Section 3.2.2 in RFC 3986.

< >

Special characters. The angle bracket characters are delimiters and enclose a complete URI or an URI component or a subcomponent. See Appendix C in RFC 3986.

;

Reserved character. The semicolon character is a delimiter, which is often used to separates a parameter name and its value in a path segment. See Section 3.3 in RFC 3986.

Reserved character. The colon character is a delimiter, which either terminates an URI scheme component, or userinfo subcomponent, or separates host subcomponent from the port subcomponent, an authority component, or a query component and starts a fragment component. See Section 2.2 in RFC 3986, and Section 3.2 in RFC 3986.

3.3.4 SBI specific usage of delimiters p. 10

The braces (curly brackets) are used as delimiters across the SBI specifications, but have somewhat different purpose as specified below.

{ }

Delimiters. The braces (curly brackets) characters enclose a name of a variable in an URI path segment (see clause 5.1.3.2). Example: …/subscriber-data/{supi}.

{ }

Delimiters. The braces (curly brackets) characters enclose a parameter value in a query (see clause 5.1.3.3). Example: ?nf-id={chooseAValue}