Content for  TS 29.501  Word version:  18.4.0

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.

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.

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.

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: The resource URI variables supported by the resource shall be defined as Table 5.2.2-1 illustrates.

  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: 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: 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:

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.

  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: 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:

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.

  Example: The callback URI variables shall be defined as Table 5.2.3A-2 illustrates.

  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: 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:

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.