Content for  TS 29.501  Word version:  18.4.0

Procedures that allow an NF service consumer to create a new resource at the NF service producer shall be specified to either use the HTTP POST method with procedures according to clause 4.6.1.1.1.2 or the HTTP PUT method with procedures according to clause 4.6.1.1.1.3.

The HTTP POST method (see RFC 7231) allows an NF service consumer to create a new child resource at the NF service producer in such a manner that the NF service producer selects the child resource identifier and the URI for the child resource. Figure 4.6.1.1.1.2-1 illustrates creating a resource using POST.

1. The parent resource of which the new resource is to be created as a child is identified by the request URI. The payload body of the POST request shall contain a representation of the resource to be created without a child resource identifier. For forward compatibility, the NF service producer ignores unknown attributes in the received resource representation unless specified otherwise by the particular application.
2. The NF service producer generates a child resource identifier and constructs the URI for the created resource by appending that child resource identifier to the parent resource URI received as request URI of the POST request (e.g. "…/parent-resource/childresource1").
   On success, "201 Created" shall be returned, the payload body of the POST response should contain a representation of the created resource, and the "Location" header shall be present and shall contain the URI of the created resource. The created resource shall be served by the same NF (service) instance that received the service request, unless the 5GC SBI API specifications explicitly specified that in specific use cases the created resource may be served by another NF (service) instance. If in such specific use cases the resource is created in a different NF (service) instance, the identifier of the serving NF (service) instance shall be included in the response message.
   If the HTTP scheme used in the returned URI is "https", then the authority of the URI included in the Location header shall be an FQDN, and not an IP address.
   The URI included in the "Location" header may be an absolute URI or a relative URI reference (see RFC 3986); when the URI is in relative form, the base URI used to resolve the URI reference is the target URI included in the received POST request.

On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.8). A collection may be used to model a resource that serves as a directory of resources that may be distributed on different processing instances or hosts. If so:

• the authority and/or deployment-specific string of the apiRoot of the created resource URI returned by the NF Service Producer in the "Location" header may differ from the authority and/or deployment-specific string of the apiRoot of the request URI received in the POST request.
• the NF Service Consumer shall be capable to receive and process an authority and/or deployment-specific string in the apiRoot of the created resource URI that differs from the authority and/or deployment-specific string of the apiRoot of the Request URI.

It needs to be clearly stated in the 5GC SBI API specifications when a NF Service Producer may return a different authority and/or deployment-specific string in the apiRoot of the created resource URI for a collection resource.

The HTTP PUT method (see RFC 7231) allows an NF service consumer to create a new resource at the NF service producer in such a manner that the NF service consumer selects the resource identifier and the URI for the resource. Figure 4.6.1.1.1.3-1 illustrates creating a resource using HTTP PUT.

1. The NF service consumer selects a resource identifier and constructs the URI for the resource to be created by appending that resource identifier to the parent resource URI. The resource that is to be created is identified by that URI as request URI. The payload body of the PUT request shall contain a representation of the resource to be created. For forward compatibility, the NF service producer ignores unknown attributes in the received resource representation unless specified otherwise by the particular application.
2. On success, "201 Created" shall be returned, the payload body of the PUT response should contain the representation of the created resource, and the "Location" header shall be present and shall contain the URI of the created resource. The created resource shall be served by the same NF (service) instance that received the service request, unless the 5GC SBI API specifications explicitly specified that in specific use cases the created resource may be served by another NF (service) instance. If in such specific use cases the resource is created in a different NF (service) instance, the identifier of the serving NF (service) instance shall be included in the response message.
   If the HTTP scheme used in the returned URI is "https", then the authority of the URI included in the Location header shall be an FQDN, and not an IP address.
   On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).

If the resource that is to be created already exists at the NF service producer, the following applies:

1. If the update of that resource by PUT is supported, the existing representation of the resource is replaced with the representation received in the PUT request body; see clause 4.6.1.1.3.1.
2. If the update of that resource by PUT is not supported, the "403 Forbidden" HTTP status code shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).

Procedures that allow a service consumer NF (client) to read information from the server shall be specified to use the HTTP GET method (see RFC 7231) to obtain the current representation of a resource. Figure 4.6.1.1.2.1-1 illustrates reading a resource.

1. The resource of which a representation is to be obtained is identified by the request URI. Query parameters may be used to control the content of the result.
   The payload body of the GET request shall be empty.
2. On success, "200 OK" shall be returned and the payload body of the GET response shall contain the obtained resource representation.

On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the GET response body (see clause 4.8).

Procedures that allow a service consumer NF (client) to querying a set of resources from the server shall be specified to use HTTP GET method towards a resource modelled as Collection or Store archetype. Query parameters (see clause 4.6.1.1.5) may be provided when querying a set of resources. The query component contains non-hierarchical data that, along with data in the path component, to filter the resources identified within the scope of the URI's scheme to a subset of the resources matching the query parameters. The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI.

Clause 4.9 specifies some possible options for an NF Service Producer to return the representations of multiple resources to a NF Service Consumer.

Procedures that allow a service consumer NF (client) to update information stored at the server by means of a complete replacement shall be specified to use the HTTP PUT method to replace the current representation of a resource with a new representation. Figure 4.6.1.1.3.1-1 illustrates updating a resource using HTTP PUT.

1. The resource that is to be updated is identified by the request URI. The payload body of the PUT request shall contain the new representation of the resource. For forward compatibility, the NF service producer ignores unknown attributes in the received resource representation unless specified otherwise by the particular application.
2. On success, "204 No Content" or "200 OK" shall be returned.

On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8). If the resource that is to be updated does not exist at the NF service producer, the following applies:

1. If the creation of that resource by PUT is supported, the resource is created according to the procedure in clause 4.6.1.1.1.3.
2. If the creation of that resource by PUT is not supported, the "403 Forbidden" HTTP status code shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).

Procedures that allow a service consumer NF (client) to update information stored at the server by means of a partial replacement shall be specified to use the HTTP PATCH method (see RFC 5789) to modify the current representation of a resource according to given modification instructions. The format of the PATCH message body shall be specified for each resource where the PATCH method is supported using one or several of the following encodings:

• If no modification of individual elements within an array needs to be supported, the "JSON Merge Patch" encoding of changes defined in RFC 7396 should be used.
• If a modification of individual elements within an array needs to be supported, the "JSON Patch" encoding of changes defined in RFC 6902 shall be used.

A single of the above encodings shall be specified for each resource where the PATCH method is supported unless backward compatibility considerations necessitate the support of both encodings. Figure 4.6.1.1.3.2-1 illustrates updating a resource using HTTP PATCH.

1. The resource that is to be updated is identified by the request URI. The payload body of the PATCH request shall contain a description of the requested modifications of the resource. For the "JSON Merge Patch" encoding defined in RFC 7396 and the "Content-Type" header shall be set to "application/merge-patch+json". For the "JSON Patch" encoding of changes defined in RFC 6902 the "Content-Type" header shall be set to "application/json-patch+json". For forward compatibility, the NF service producer shall ignore received modification instructions of unknown attributes in the resource unless specified otherwise by the particular application.
2. On success, "204 No Content" or "200 OK" shall be returned.

On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PATCH response body (see clause 4.8).

The query component in the URI contains non-hierarchical data that, along with data in the path component, to filter the resources identified within the scope of the URI's scheme to a subset of the resources matching the query parameters. The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI. The syntax of the query component is specified in RFC 3986. When a server receives a request with a query component, it shall parse the query string in order to identify filters. The first question mark is used to be a separator and is not part of the query string. A query string is composed of a series of "key=value" pairs, separated by "&". If one query parameter contains more than one value, i.e. an array of data elements, different values shall be separated by comma (","). The behaviour of the server, when receiving an HTTP/2 method with a query parameter which is of type array and only some of the members in the array can be matched, depends on each API and the behaviour shall be clearly described. If multiple query parameters are defined for a method on the resource, the logical 'AND' represents the default logical relationship between the query parameters for this resource. If a logical relationship between multiple query parameters is specified in an API, then this overrides the default relationship. If multiple query parameters are defined for a method on the resource in an API, but there is no need to specify any logical relationship between these query parameters, the API shall explicitly state this.

The complex query expression is used when there are multiple query parameters in the URI and the query condition needs to be expressed by a logical combination of multiple query parameters which overrides the default logical relationship of the query parameters. The complex query expression is either a Conjunctive Normal Form (CNF) or a Disjunctive Normal Form (DNF) which is equivalent to the logical combination of query parameters reflecting the query condition. The "complex-query" query parameter may be used when a complex query expression is needed to express a query condition. The value of the "complex-query" query parameter is of type "ComplexQuery" which is a JSON object, the corresponding CNF or DNF is encoded into that JSON object (see TS 29.571 for the details of the data type "ComplexQuery"). The use of "complex-query" shall be negotiated using the feature negotiation procedure as defined in TS 29.500. If a query parameter is included in the "complexQuery" then the same query parameter shall not be included outside the "complexQuery" in the same request message.