Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TS 29.501  Word version:  16.4.0

Top   Top   Up   Prev   Next
1…   4…   4.6…   4.7…   5…   5.3…   6…   A…

 

5  Documenting 5GC SBI APIs
5.1  Naming Conventions
5.1.1  Case Conventions
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;
b) 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 ConventionsWord‑p. 41
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
5.1.3.1  Introduction
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
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 IETF RFC 3986 [9]. IETF RFC 3986 [9] 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 IETF RFC 3986 [9]), 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 ConventionsWord‑p. 42
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
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:
BLACK_LISTED
d)
The names of data types shall be represented using UpperCamel.
Example 4:
ResourceHandle
Up
5.2  API Definition
5.2.1  Resource Structure
Resource structure shall define the structure of the resource URIs, the resources, the associated HTTP methods and custom operations used for the service.
Figure 5.2.1-1 provides an example of the resource URI structure (i.e. resource tree) of an API. Table 5.2.1-1 provides an example of an overview of the resources defined for the service, and their applicable HTTP methods and custom operations.
Reproduction of 3GPP TS 29.501, Figure 5.2.1-1: Resource URI structure of the <xyz > API
Up
In figure 5.2.1-1 a child node with a solid-line frame represents a resource-URI that has at least one supported HTTP method associated, and a child node with a dashed-line frame represents a sub-URI under a resource which supports specific custom operation. All child node names are examples only.
Resource name
Resource URI
HTTP method or custom operation
Description

<Resource name>
<relative URI below root>
GET
<Operation executed by GET>
PUT
<Operation executed by PUT>
PATCH
<Operation executed by PATCH>
POST
<Operation executed by POST>
DELETE
<Operation executed by DELETE>
<relative URI below root>/release
release (POST)
<Operation executed by Custom operation>

Up
5.2.2  Resources and HTTP MethodsWord‑p. 43
Resources and HTTP methods shall specify the resource URI, resource URI variables for the resource and the standard HTTP methods supported by the resource.
Example:
Resource URI: {apiRoot}/<apiName>/{apiVersion}/<apiSpecificResourceUriPart>
The resource URI variables supported by the resource shall be defined as table 5.2.2-1 illustrates.
Name
Definition

apiRoot
See clause xxx
apiVersion
See clause xxy
< Name of resource URI variables for resource>
< Definition of resource URI variables for resource >

The {apiRoot} and {apiVersion} URI variables should be defined in clauses and this definition should be referenced to ease a possible update of the apiVersion value.
Each method supported by the resource shall be described including the URI query parameters supported by the method, data structures supported by the request body, and the data structures supported by the response body.
URI query parameters supported by the method shall be defined as table 5.2.2-2 illustrates.
Name
Data type
P
Cardinality
Description
Applicability

<name> or n/a
<type> or <leave empty>
<M, C or O>
0..1 or 1 or 0..N or 1..N or <leave empty>
<only if applicable>

Name:
Name of query parameter in URI. If no query parameters are defined for the URI, the name should be marked as "n/a".
Data type:
Data type of URI query parameters, i.e. a data type defined in the specification. If no query parameter is defined for the URI, the column is left empty.
P:
Presence condition of URI query parameters. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional). If no query parameter is defined for the URI, the column is left empty.
Cardinality:
Defines the allowed number of occurrence. It shall be "0..1", "1", "0..N", "1..N" . If no query parameter is defined for the URI, the column is left empty.
Description:
Additional information for URI query parameter, i.e. describes the use of the parameter or the presence condition of the parameter and so on.
Applicability:
If the URI query parameter is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6.2 of TS 29.500, the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the attribute can be used with any feature.
Data structures supported by the request body of the method shall be specified as table 5.2.2-3 illustrates.
Data type
P
Cardinality
Description

"<type>" or "array(<type>)" or "map(<type>)" or n/a
"M", "C" or "O"
"0..1", "1", or "M..N", or <leave empty>
<only if applicable>

Data type:
Data type of the data structure in the request body. If the data type is indicated as "<type>", the request body shall be of data type <type>. If the data type is indicated as "array(<type>)", the request body shall be an array (see IETF RFC 8259 [3]) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the request body shall be an object (see IETF RFC 8259 [3]) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If no request body is allowed, the Data type shall be marked as "n/a".
P:
Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).
Cardinality:
Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers with M being greater than or equal 0, and N being greater than 0 and M. For data type "<type>", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M". The Cardinality shall be left empty if no request body is allowed.
Description:
Additional information for a data structure, i.e. describes the use of the data structure or the presence condition of the data structure and so on.
Data structures supported by the response body of the method shall be specified as table 5.2.2-4 illustrates.
Data type
P
Cardinality
Response codes
Description

"<type>" or "array(<type>)" or "map(<type>)" or n/a
"M", "C" or "O"
"0..1", "1", or "M..N", or <leave empty>
<list applicable codes with name from the applicable RFCs>
<Meaning of the success case>
or
<Meaning of the error case with additional statement regarding error handling>

Data type:
Data type of the data structure in the response body. If the data type is indicated as "<type>", the response body shall be of data type <type>. If the data type is indicated as "array(<type>)", the response body shall be an array (see RFC 8259) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the response body shall be an object (see RFC 8259) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If no response body is allowed, the Data type shall be marked as "n/a".
P:
Presence condition of a data structure in response body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).
Cardinality:
Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers with M being greater than or equal 0, and N being greater than 0 and M. For data type "<type>", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M". The Cardinality shall be left empty if no response body is allowed.
Response codes:
Lists applicable response codes with name from HTTP Status Code Registry at IANA [12]. Mandatory HTTP status codes listed in Table 5.2.7.1-1 of TS 29.500 for the corresponding HTTP method shall only be included if specific clarifications in the description part or special data types of the response body are required. Applicable HTTP status codes in addition to the mandatory HTTP status codes listed in Table 5.2.7.1-1 of TS 29.500 for the corresponding HTTP method shall be included.
Description:
Additional information for a response, i.e. describes the meaning of the success case or meaning of the error case with additional statement regarding error handling.
Up
5.2.3  Representing RPC as Custom Operations on ResourcesWord‑p. 46
Custom operations (RPC-style interaction) may be used on a resource. The description of each custom operation contains the custom operation URI, the HTTP method on which the operation is mapped (typically POST), data structures supported by the request body and the data structures supported by the response body.
An overview of the custom operations on a resource is illustrated in table 5.2.3-1.
Custom operation URI
Mapped HTTP method
Description

<custom operation URI>
e.g. POST
<Operation executed by custom operation>

Data structures supported by the request body of the method shall be specified as table 5.2.3-2 illustrates.
Data type
P
Cardinality
Description

"<type>" or "array(<type>)" or "map(<type>)"
"M", "C" or "O"
"0..1", "1", or "M..N", or <leave empty>
<only if applicable>

Data type:
Data type of the data structure in the request body. If the data type is indicated as "<type>", the request body shall be of data type <type>. If the data type is indicated as "array(<type>)", the request body shall be an array (see RFC 8259) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the request body shall be an object (see RFC 8259) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If no request body is allowed, the Data type shall be marked as "n/a".
P:
Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).
Cardinality:
Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers with M being greater than or equal 0, and N being greater than 0 and M. For data type "<type>", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M". The Cardinality shall be left empty if no request body is allowed.
Description:
Additional information for a data structure, i.e. describes the use of the data structure or the presence condition of the data structure and so on.
Data structures supported by the response body of the method shall be specified as table 5.2.3-3 illustrates.
Data type
P
Cardinality
Response codes
Description

"<type>" or "array(<type>)" or "map(<type>)"
"M", "C" or "O"
"0..1", "1" or "M..N", or <leave empty>
<list applicable codes with name from the applicable RFCs>
<Meaning of the success case>
or
<Meaning of the error case with additional statement regarding error handling>

Data type:
Data type of the data structure in the response body. If the data type is indicated as "<type>", the response body shall be of data type <type>. If the data type is indicated as "array(<type>)", the response body shall be an array (see RFC 8259) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the response body shall be an object (see RFC 8259) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If no response body is allowed, the Data type shall be marked as "n/a".
P:
Presence condition of a data structure in response body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).
Cardinality:
Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers with M being greater than or equal 0, and N being greater than 0 and M. For data type "<type>", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M". The Cardinality shall be left empty if no response body is allowed.
Response codes:
Lists applicable response codes with name from HTTP Status Code Registry at IANA [12]. Mandatory HTTP status codes listed in Table 5.2.7.1-1 of TS 29.500 for the corresponding HTTP method shall only be included if specific clarifications in the description part or special data types of the response body are required. Applicable HTTP status codes in addition to the mandatory HTTP status codes listed in Table 5.2.7.1-1 of TS 29.500 for the corresponding HTTP method shall be included.
Description:
Additional information for a response, i.e. describes the meaning of the success case or meaning of the error case with additional statement regarding error handling.
Up
5.2.4  Data ModelsWord‑p. 47
5.2.4.1  General
The application data model supported by the API shall be specified with the following data types:
  1. Structured data types
  2. Simple data types
  3. Enumerations
  4. Binary data
  5. Data types describing alternative data types
  6. Data types describing combinations of data types
Each data type can be specific for the API or common to multiple APIs (offered by the same or different NFs). The common data types shall be specified in TS 29.571.
5.2.4.2  Structured data typesWord‑p. 48
The structured data types shall represent an object (see RFC 8259). The structured data types shall contain attributes that are simple data types, structured data types, arrays (see below), maps (as defined below), enumerations, data types describing alternative data types, data types describing combinations of data types or "Any Type" (as described below).
An array (see RFC 8259) shall represent a list of values without keys and with significance in the order of sequence. All values shall be of the same type.
A map shall represent an object (see RFC 8259) with a list of key-value pairs (with no significance in the order of sequence), where all keys are of type string and shall be unique identifiers assigned by the application rather than by the schema, and where all values shall be of the same type.
Each structured data type shall be specified in a separate clause as illustrated in table 5.2.4.2-1.
Attribute name
Data type
P
Cardinality
Description
Applicability

<attribute name>
"<type>" or "array(<type>)" or "map(<type>)" or "Any Type"
"M", "C" or "O"
"0..1", "1" or "M..N"
<only if applicable>

Attribute name:
Name of attributes that belong to the specified data type. The attribute names within a structured data type shall be unique, and their relative order inside the structured data type shall not imply any specific ordering of the corresponding JSON elements in a JSON object.
Data type:
Data type of the attribute. If the data type is indicated as "<type>", the attribute shall be of data type <type>. If the data type is indicated as "array(<type>)", the attribute shall be an array (see RFC 8259) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the attribute shall be an object (see RFC 8259) encoding a map that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If the data type is indicated as "Any Type", the attribute can either be "integer", "number", "string", "boolean", "array" or "object" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification.
P:
Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).
Cardinality:
Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers; with M being greater than or equal 0, and N being greater than 0 and M. For data type "<type>" and "Any Type", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M".
Description:
Describes the meaning and use of the attribute and may contain normative statements.
Applicability:
If the attribute is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of TS 29.500, the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the attribute can be used with any feature.
Up
5.2.4.3  Simple data types and enumerationsWord‑p. 49
The simple data types and enumerations can be referenced from data structures. All simple data types and enumerations should map to base types supported by IDL. Simple data types shall be specified as illustrated in table 5.2.4.3-1.
Type Name
Type Definition
Description
Applicability

<one simple data type, i.e. boolean, integer, number, or string>

Type Name: The name of the simple data type.
Type Definition: Base types supported by IDL, i.e. Boolean, integer, string and so on.
Description: Additional descriptions for simple data types like range, string length and so on.
Applicability: If the type is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of TS 29.500, the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the type can be used with any feature.
Each enumeration type shall be respectively specified for their elements sets as illustrated in table 5.2.4.3-2.
Enumeration value
Description
Applicability

Enumeration value 1
The description of this enum value
Enumeration value 2
The description of this other enum value

Enumeration value:
Defines the valid values, which can be integer, string or boolean, it is suggested to keep the same value style in one API specification.
Description:
Additional descriptions for enumeration attributes, like the meaning and usage of enumeration elements.
Applicability:
If the enumeration value is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of TS 29.500, the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the enumeration value can be used with any feature.
Up
5.2.4.4  Binary Data
5.2.4.5  Data types describing alternative data types or combinations of data types
The data types describing alternative data types or combinations of data types shall represent an OpenAPI schema object using the "oneOf" , "anyOf" or "allOf" keyword to list alternative or to be combined data types (see the OpenAPI specification [4] and https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
An instance (i.e. a corresponding part of a JSON file to be evaluated against the schema) matches a list of mutually exclusive alternative data types , as described using the OpenAPI "oneOf" keyword, if the instance matches against one and only one of the alternative data types.
An instance (i.e. a corresponding part of a JSON file to be evaluated against the schema) matches a list of non-exclusive alternative data types, as described using the OpenAPI "anyOf" keyword, if the instance matches against one or more of the alternative data types.
An instance (i.e. a corresponding part of a JSON file to be evaluated against the schema) matches a list of to be combined data types, as described using the OpenAPI "allOf" keyword, if the instance matches against all of the to be combined data types.
The alternative or to be combined data types shall be simple data types, structured data types, arrays (see clause 5.2.4.2), maps (see clause 5.2.4.2), enumerations, data types describing alternative data types, or data types describing combinations of data types.
Each structured data type shall be specified in a separate clause as illustrated in table 5.2.4.2-1.
Data type
Cardinality
Description
Applicability

"<type>" or "array(<type>)" or "map(<type>)"
"1" or "M..N"
<only if applicable>

Data type:
Data type of the alternative or to be combined data type. If the data type is indicated as "<type>", the alternative or to be combined data type shall be of data type <type>. If the data type is indicated as "array(<type>)", the alternative or to be combined data type shall be an array (see IETF RFC 8259 [3]) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the alternative or to be combined data type shall be an object (see IETF RFC 8259 [3]) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification.
Cardinality:
Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers; with M being greater than or equal 0, and N being greater than 0. For data type "<type>", the cardinality shall be set to "1".
Description:
Describes the meaning and use of the attribute and may contain normative statements.
Applicability:
If the type is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of TS 29.500, the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the type can be used with any feature.
Up
5.2.5  Relation typesWord‑p. 51

Up   Top   ToC