Content for  TS 29.501  Word version:  18.4.0

Resources are either individual resources, or structured resources that can contain child resources. It is recommended to design each resource following one of the archetypes provided in the Annex C. A URI uniquely identifies a resource. In the 5GC SBI APIs, when a resource URI is an absolute URI, its structure shall be specified as follows: "apiRoot" shall be a concatenation of the following parts:

• scheme ("http" or "https")
• the fixed string "://"
• authority (host and optional port) as defined in IETF RFC 3986. The host should be represented by the operator specific FQDN (for FQDN examples see clause 28.3.2 in TS 23.003).
• an optional deployment-specific string (API prefix) that starts with a "/" character.

"apiName" shall define the name of the API. For example, 'nsmf-pdusession'. "apiVersion" shall indicate the MAJOR version of the API. The format is specified in clause 4.3.1.3. For example, 'v1'. While "apiRoot", "apiName" and "apiVersion" together define the API URI of the corresponding API, each "apiSpecificResourceUriPart" defines a resource URI of the API relative to the API URI. An API URI should not contain a trailing slash as defined in clause 3.1, and if it contains one, then it should be ignored/removed. Example of an API URI from TS 29.502:

• url: '{apiRoot}/nsmf-pdusession/v1'

The custom operation definition is in Annex C. The URI of a custom operation which is associated with a resource shall have the following structure: Custom operations can also be associated with the service instead of a resource. The URI of a custom operation which is not associated with a resource shall have the following structure: In the above URI structures, "apiRoot", "apiName", "apiVersion" and "apiSpecificResourceUriPart" are as defined in clause 4.4.1 and "custOpName" represents the name of the custom operation as defined in clause 5.1.3.2.

The purpose of the callback URI is to enable NF service consumer to provide the URI to be used by an NF Service Producer to send notification or callback requests. The callback URI shall be in the form of an absolute URI as defined in Section 4.3 of RFC 3986, including an authority, and excluding any query component, any fragment component and any userinfo subcomponent. Therefore, callback URI consists of the following components, specified with ABNF syntax (see RFC 5234): Where:

• scheme is either "http" or "https";
• 'host' is either an FQDN or an IP address;
• the URI may contain an optional port;
• the URI may contain an optional deployment-specific string (prefix) that starts with a "/" character;
• the "callbackUripart" is the part of the callback URI, after the prefix (if any), of the path to an HTTP resource on the consumer, which is implementation specific; and
• the path of the callback URI comprises the prefix (if any) and the "callbackUriPart".

A resource representation is a serialization of the resource state in a particular content format. It's included in the data frame of an HTTP/2 request or response. Representation header fields provide metadata about the representation. When a message includes a data frame, the representation data enclosed in the data frame. HTTP/2 reuses the definition of Representation header as HTTP 1.1 in RFC 7231. Content-type field in HTTP/2 header performs as representation header fields and describes the representation data that would have been enclosed in the data frame, e.g. if content-type is application/json, resource representation in data frame is serialized in JSON format. Server supports the content format of the representation received in the data frame of the request and returns the "200 OK" response code.

RFC 7231 provides a mechanism to negotiate the content format of a representation. In HTTP/2 requests and responses, the "Content-Type" HTTP/2 header field is used to signal the format of the actual representation included in the data frame. If the format of the representation in an HTTP/2 request is not supported by the server, it responds with the "415 Unsupported Media Type" response code. For GET method, the "Accept" HTTP header of the HTTP/2 request signals the content formats that a client supports. If the server cannot provide any of the accepted formats, it returns the "406 Not Acceptable" response code.