Tech-invite3GPPspaceIETFspace
21222324252627282931323334353637384‑5x

Content for  TS 29.501  Word version:  19.0.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   F…

 

5.2  API Definitionp. 44

5.2.1  Resource Structurep. 44

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, Fig. 5.2.1-1: Resource URI structure of the <xyz > API
Up
In Figure 5.2.1-1 the following graphical conventions are used:
  • a child node with a solid-line frame represents:
    • a resource-URI that has at least one supported HTTP method associated, see e.g. "/resource A" in Figure 5.2.1-1. Such node may be any of the archetypes defined in Annex C.1, C.2 and C.3;
    • a resource-URI, which does not have any standard HTTP operation defined, but has a custom operation, see e.g. "/individual child resource A2" in Figure 5.2.1-1;
  • a child node with a dashed-line frame represents a a specific custom operation, see e.g. "/custom operation A3" and "/custom operation C1" in Figure 5.2.1-1. Such node is a Custom operation archetype, see Annex C.4;
  • a child node without a line around its frame (e.g. "/special node type B" in Figure 5.2.1-1) typically represents a path segment for which no standard HTTP operation is specified. This graphical representation is also used when a custom operation without an associated resource is defined for a path segment.
Resource purpose/name Resource URI (relative path after API URI) HTTP method or custom operation Description (service operation)
<Resource name><relative path after API URI>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 path after API URI>/releaserelease (POST)<Operation executed by Custom operation>
For a resource, the "relative path after API URI" is appended to the API URI to form the resource URI as defined in clause 3.1.
Up

5.2.2  Resources and HTTP Methodsp. 46

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
apiRootSee clause 4.4.1
< Name of resource URI variables for resource>< Definition of resource URI variables for resource >
 
The {apiRoot} URI variable 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 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 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 Resourcesp. 48

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.3A  Notifications |R16|p. 49

Notifications based on the Callback URI as specified in clause 4.6.2.3 and clause 6.2 of TS 29.500 may be supported. The description of each notification contains the Callback URI, the HTTP method (typically POST), data structures supported by the request body and the data structures supported by the response body.
An overview of the notifications is illustrated in Table 5.2.3A-1.
Notification Callback URI HTTP method or custom operation Description (service operation)
<notification 1> e.g. Status Change Notification< Callback URI > e.g. {StatusCallbackUri}e.g POSTe.g. Notify Event
 
Example:
Callback URI: {notifUri}
The callback URI variables shall be defined as Table 5.2.3A-2 illustrates.
Name Definition
notifUriString formatted as URI with the Callback Uri
 
Data structures supported by the request body of the method shall be specified as Table 5.2.3A-3 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.3A-4 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 Modelsp. 51

5.2.4.1  Generalp. 51

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.
Characters in an enumeration or string data type in both simple and structured/combination data types specific for the API or common to multiple APIs shall be handled as case sensitive by default, unless stated otherwise.
Strings representing a numerical value or a binary octet string, encoded as hexadecimal characters, shall be handled as case insensitive.
Up

5.2.4.2  Structured data typesp. 52

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 Data type P Cardinality Description Applicability
<attribute name> "array(map(<type>)" or "map(array(<type>)" or" array(array(<type>)" or "map(map(<type>)" "M", "C" or "O" "M1..N1(M2..N2)"<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 with nested structures, the cardinality is expressed in a nested manner, each level of the M and N values describe the cardinality of the corresponding level of the data structure. 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 enumerationsp. 53

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 OpenAPI specification [4]. 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 OpenAPI specification [4], i.e. Boolean, integer, string and so on.
Description:
Additional descriptions for simple data types like range, string length, string pattern (regular expression) 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 1The description of this enum value
Enumeration value 2The 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 Datap. 54

5.2.4.5  Data types describing alternative data types or combinations of data typesp. 54

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 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 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.5Void

5.2.6  3GPP Custom HTTP Headers |R18|p. 55

The definition of 3GPP APIs for the Service-Based Architecture includes the definition of 3GPP-specific HTTP headers, both generic (i.e. applicable to any API), and also API-specific headers.
The definition of the generic HTTP headers is done in TS 29.500. It consists of the ABNF definition of each header, along with a detailed description of the syntax and expected behaviour and handling by the receiver of such header; each header is specified in its own separate clause.
3GPP TS 29.500, Annex D, contains a self-contained full grammar of the entire set of custom HTTP headers, comprising both the definition of ABNF components/rules re-used from IETF RFCs, and the 3GPP-specific ABNF rule definitions.
In addition, the zip file of the published TS 29.500 shall contain a file, named "TS29500_CustomHeaders.abnf", that reflects the content of such Annex D, and the same file shall be made available on the 3GPP Forge GitLab repository mentioned in clause 5.3.1, along with the OpenAPI files, where tooling can be used for validation of the ABNF grammar.
For API-specific HTTP header definition, a similar procedure shall be followed: if an API defines custom HTTP headers, their ABNF shall be included in the TS where such API is defined, along with the description of each header; each header shall be described in its own separate clause.
Similarly, each TS that defines custom HTTP headers shall contain an Annex with a self-contained and minimal set of ABNF rules, including re-used rules from other sources (e.g. IETF RFCs, TS 29.500, etc.). The zip file of the published TS shall contain a file with ".abnf" extension, with the same content as the Annex, and such file shall be made available, and validated, on 3GPP Forge/GitLab.
Up

Up   Top   ToC