Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TS 29.501  Word version:  16.4.0

Top   Top   None   None   Next
1…   4…   4.6…   4.7…   5…   5.3…   6…   A…

 

1  ScopeWord‑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
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 3.0.0 Specification", https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md.
[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 7807:  "Problem Details for HTTP APIs".
[20]  TS 29.502   "5G System; Session Management Services; Stage 3".
[21]  TS 29.509   "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".
Up
3  Definitions and abbreviationsWord‑p. 8
3.1  Definitions
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 clause 4.3 in IETF 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.
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 clause 3.3 in IETF RFC 3986).
API URI:
API URI has the following format: {apiRoot}/<apiName>/<apiVersion>. For more details see clause 4.4.1.
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 clause 5.1 in IETF RFC 3986.
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.
Relative URI:
Relative URI is a part of a URI to be used on top of a base URI, i.e. the base URI is a reference against which the relative URI is used. See clause 1.2.3 in IETF RFC 3986.
Resource URI:
Resource URI identifies an abstract or a physical resource. See the Abstract of the RFC 3986. In this specification this generally means "an URI of a resource".
Up
3.2  AbbreviationsWord‑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
Up
3.3  Special characters, operators and delimiters |R16|
3.3.1  General
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
Special characters that are used as delimires 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
/
Reserved character. The forward slash character is a delimiter, which precedes an URI path component and also separates a sequence of path segments. See clauses 2.2 and 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 clauses 2.2, 3.2, 3.3 and 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 clauses 2.2, 3.2, 3.3 and 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 clauses 1.2.3 and 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 clause 3.2.2 in IETF 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 clause 3.3 in IETF 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 clauses 2.2, and 3.2 in RFC 3986.
Up
3.3.4  SBI specific usage of delimitersWord‑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}

Up   Top   ToC