Tech-invite  3GPPspace  IETFspace
21  22  23  24  25  26  27  28  29  31  32  33  34  35  36  37  38  4‑5x

Content for  TS 29.501  Word version:  18.4.0

Top   Top   Up   Prev   Next
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… 
5 Documenting 5GC SBI APIs  5.1 Naming Conventions  5.1.1 Case Conventions  5.1.2 API Naming Conventions  5.1.3 Conventions for URI Parts  5.1.3.1 Introduction  5.1.3.2 URI Path Segment Naming Conventions  5.1.3.3 URI Query Naming Conventions  5.1.4 Conventions for Names in Data Structures 
...

 

5  Documenting 5GC SBI APIs  p. 42

5.1  Naming Conventions  p. 42

5.1.1  Case Conventions  p. 42

The following case conventions for names and strings are used in the 5GC SBI service APIs.
1)
UPPER_WITH_UNDERSCORE
All letters of a string are capital letters. Digits are allowed. Word boundaries are represented by the underscore "_" character. No other characters are allowed.
Example 1:
  1. DATA_MANAGEMENT
  2. CELL_CHANGE
2)
lower_with_underscore
All letters of a string are lowercase letters. Digits are allowed. Word boundaries are represented by the underscore "_" character. No other characters are allowed.
Example 2:
  1. data_management;
  2. cell_change.
3)
UPPER-WITH-HYPHEN
All letters of a string are capital letters. Digits are allowed. Word boundaries are represented by the hyphen "-" character. No other characters are allowed.
Example 3:
  1. DATA-MANAGEMENT
  2. CELL-CHANGE
4)
lower-with-hyphen
All letters of a string are lowercase letters. Digits are allowed. Word boundaries are represented by the hyphen "-" character. No other characters are allowed.
Example 4:
  1. data-management;
  2. cell-change.
5)
UpperCamel
A string is formed by concatenating words. Each word starts with a letter or a digit. The first letter of each word shall be an uppercase letter; all other characters in the word shall be lowercase letters or digits.
Abbreviations follow the same scheme (i.e. first letter uppercase, all other letters lowercase).
Example 5:
  1. DataManagement.
  2. CellChange
  3. 5QiPriorityLevel
  4. Amf3GppAccessRegistration
6)
lowerCamel
A string is formed by concatenating words.Each word starts with a letter or a digit. The first letter of the first word shall be a lowercase letter; the first letter of the rest of the words shall be an uppercase letter. All other characters in the words shall be lowercase letters or digits.
Abbreviations follow the same scheme.
Example 6:
  1. dataManagement
  2. cellChange
  3. 5qiPriorityLevel
Up

5.1.2  API Naming Conventions  p. 43

An API shall take the name of the corresponding service (e.g. Nudm_SubscriberDataManagement). When used in URIs the name shall be converted to lower-with-hyphen and may use an abbreviated form (e.g. nudm-sdm).

5.1.3  Conventions for URI Parts  p. 43

5.1.3.1  Introduction  p. 43

The parts of the URI syntax that are relevant in the context of the 5GC SBI service APIs are as follows:
  • Path, consisting of segments, separated by "/" (e.g. segment1/segment2/segment3).
  • Query, consisting of pairs of parameter name and value (e.g., ?mcc=262&mnc=01, where two pairs are presented).

5.1.3.2  URI Path Segment Naming Conventions  p. 44

a)
All path segments of a resource URI which represent a string constant shall use lower-with-hyphen (this implies that a path cannot end with "/").
Example 1:
subscriber-data
b)
If a resource represents a collection of entities and the last path segment of the resource URI is a string constant, that last path segment shall be plural.
Example 2:
…/prefix/api/v1/users
c)
For resources where the last path segment of the resource URI is a string constant, that last path segment shall be a noun or a composite noun.
Example 3:
…/prefix/api/v1/users
Example 4:
…/prefix/api/v1/user-session
d)
For custom operations, the last path segment of the URI via which the operation is invoked shall be a verb, or shall start with a verb.
Example 5:
…/app_instances/{appInstanceId}/instantiate
Example 6:
…/sessions/terminate-all
e)
All path segments of a URI which are variable names shall use lowerCamel, and shall be surrounded by curly brackets.
Example 7:
…/subscriber-data/{supi}
f)
Once a variable is replaced at runtime by an actual string, the string shall follow the rules for a path segment defined in RFC 3986. RFC 3986 disallows certain characters from use in a path segment. Each actual 5GC SBI service API specification shall define this restriction to be followed when generating values for path segment variables, or propose a suitable encoding (such as percent-encoding according to RFC 3986), to escape such characters if they can appear in input strings intended to be substituted for a path segment variable.
Up

5.1.3.3  URI Query Naming Conventions  p. 44

a)
URI query parameter names in queries shall use lower-with-hyphen.
Example 1:
?nf-type=AMF
b)
Variables that represent actual parameter values in queries shall use lowerCamel and shall be surrounded by curly brackets.
Example 2:
?nf-id={chooseAValue}
c)
When a variable is replaced at runtime by an actual string, the convention defined in clause 5.1.3.2 item f) applies to that string.

5.1.4  Conventions for Names in Data Structures  p. 45

The following syntax conventions apply when defining the names for attributes in the 5GC SBI service API data structures, carried in the payload body of http requests and responses.
a)
Names of attributes shall be represented using lowerCamel.
Example 1:
attributeName
b)
Names of arrays (i.e. those with cardinality 1..N or 0..N) shall be plural rather than singular.
Example 2:
users
c)
Each value of an enumeration type shall be represented using UPPER_WITH_UNDERSCORE.
Example 3:
PROHIBITTED_LISTED
d)
The names of data types shall be represented using UpperCamel.
Example 4:
ResourceHandle
Up

Up   Top   ToC