Content for TS 29.501 Word version: 19.0.0
4.6 Use of HTTP Methods
4.6.1 Use of Request/Response Communication
4.6.1.1 CRUD
4.6.1.1.1 Creating a Resource
4.6.1.1.1.1 General
4.6.1.1.1.2 Creating a Resource using POST
4.6.1.1.1.3 Creating a Resource using PUT
4.6.1.1.2 Reading a Resource
4.6.1.1.2.1 Reading a Single Resource
4.6.1.1.2.2 Querying a Set of Resources
4.6.1.1.3 Updating a Resource
4.6.1.1.3.1 Usage of HTTP PUT
4.6.1.1.3.2 Usage of HTTP PATCH
4.6.1.1.4 Deleting a Resource
4.6.1.1.5 Query Parameters
4.6.1.1.5.1 General
4.6.1.1.5.2 Complex query expression
4.6.1.2 Custom Operations
4.6.1.3 Use of Asynchronous Operations
4.6.1.4 Special provisions to support the seamless change of AMF as NF service producer
...
...
4.6 Use of HTTP Methods p. 19
4.6.1 Use of Request/Response Communication p. 19
4.6.1.1 CRUD p. 19
4.6.1.1.1 Creating a Resource p. 19
4.6.1.1.1.1 General p. 19
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.
4.6.1.1.1.2 Creating a Resource using POST p. 19
The HTTP POST method (see RFC 9110) 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.
Step 1.
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 parent resource of which the new resource is to be created as a child is identified by the request URI. The content 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.
Step 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 content 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.
- 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.
4.6.1.1.1.3 Creating a Resource using PUT p. 20
The HTTP PUT method (see RFC 9110) 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.
Step 1.
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:
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 content 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.
Step 2.
On success, "201 Created" shall be returned, the content 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.
- 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.
- 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).
4.6.1.1.2 Reading a Resource p. 21
4.6.1.1.2.1 Reading a Single Resource p. 21
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 9110) to obtain the current representation of a resource.
Figure 4.6.1.1.2.1-1 illustrates reading a resource.
Step 1.
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).
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 content of the GET request shall be empty.
Step 2.
On success, "200 OK" shall be returned and the content of the GET response shall contain the obtained resource representation.
4.6.1.1.2.2 Querying a Set of Resources p. 21
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.
Step 1.
Clause 4.9 specifies some possible options for an NF Service Producer to return the representations of multiple resources to a NF Service Consumer.
The client shall send a HTTP GET request using the URI of a resource modelled as Collection or Store archetype, optionally with query parameters, to the server.
Step 2.
On success, the server shall return a set of sub-resources that includes only those entries filtered by the query parameters. If no sub-resource is matched for the querying service operation, the server shall return "200 OK" with an empty array (e.g. "[ ]" in JSON) in response body. If the resource in the URI doesn't exist on the server, the server shall return "404 Not Found" with optionally the cause information in response body.
4.6.1.1.3 Updating a Resource p. 22
4.6.1.1.3.1 Usage of HTTP PUT p. 22
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.
Step 1.
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:
The resource that is to be updated is identified by the request URI. The content 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.
Step 2.
On success, "204 No Content" or "200 OK" shall be returned.
- 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.
- 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).
4.6.1.1.3.2 Usage of HTTP PATCH p. 23
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.
- If a modification of a resource with multiple datasets needs to be supported, the HTTP multipart message with the multipart/mixed content-type as described in RFC 2046 shall be used.
Step 1.
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 resource that is to be updated is identified by the request URI. The content 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 resources with multiple datasets the encoding for HTTP multipart messages with the multipart/mixed content-type as defined in RFC 2046 shall be used. 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.
Step 2.
On success, "204 No Content" or "200 OK" shall be returned.
4.6.1.1.4 Deleting a Resource p. 24
Procedures that allow a service consumer NF (client) to delete a resource from the server shall be specified to use the HTTP DELETE method (see RFC 7231).
Figure 4.6.1.1.4-1 illustrates deleting a resource.
The resource that is to be deleted is identified by the request URI.
The payload body of the DELETE request shall be empty.
On success, "204 No Content" should be returned and then the payload body of the DELETE response shall be empty.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the DELETE response body (see clause 4.8).
4.6.1.1.5 Query Parameters p. 24
4.6.1.1.5.1 General p. 24
The optional query component in the URI contains non-hierarchical data that, along with data in the path component, serves 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. Absence of the query component from the URI is indicated by absence of a question mark character from 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 possibly empty series of "key=value" pairs (also referred to as series of query parameters), 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.
4.6.1.1.5.2 Complex query expression p. 24
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.
4.6.1.2 Custom Operations p. 25
Custom Operations provide procedures that allow a service consumer NF (client) to interact with an NF service producer in other ways than what is supported by the CRUD methods described in clause 4.6.1.1.
Custom Operation can be related to a resource or can be related to an entire service and be independent of a resource.
Figure 4.6.1.2-1 illustrates the use of a custom operation related to a resource.
Step 1.
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).
Figure 4.6.1.2-2 illustrates the use of a custom operation related to a service.
The request URI identifies the custom operation to be executed and the resource the custom operation relates to and is constructed by adding a verb as name for the custom operation at the end of the resource URI (see clauses 4.4.2 and 5.1.3.2). Parameters for the custom operation are included in the request body.
Step 2.
On success, "204 No Content" or "200 OK" shall be returned. "200 OK" shall contain a body with data related to the custom operation.
Step 1.
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).
The request URI identifies the custom operation to be executed and is constructed by adding a verb as name for the custom operation at the end of the service URI (see clauses 4.4.2 and 5.1.3.2). Parameters for the custom operation are included in the request body.
Step 2.
On success, "204 No Content" or "200 OK" shall be returned. "200 OK" shall contain a body with data related to the custom operation.
4.6.1.3 Use of Asynchronous Operations p. 26
Certain service operations may be designed to allow the invocation of a request so that the response can be received asynchronously: if the NF service consumer when sending a request cannot expect to receive an immediate final response, the service consumer may provide a callback reference for final result notification. The service provider, when receiving a request that contains a callback reference for final result notification, may then return an immediate "202 Accepted", and notify the service consumer about the final result using the received callback reference at a later point in time.
4.6.1.4 Special provisions to support the seamless change of AMF as NF service producer p. 26
Services provided by the AMF can be transferred seamlessly to a new AMF when the corresponding UE context is transferred to that AMF.
To support a seamless change of the AMF as NF service producer, the procedures in clause 4.6.1 are applied with the following special provisions:
- When becoming aware that a new AMF is serving the resource, the NF service consumer shall exchange the authority part of resource URIs with the address of a new NF service producer and shall use that URI in subsequent communication.
- Each AMF within a set of AMFs supporting seamless changes shall be prepared to receive updates for resource URIs constructed according to bullet 1 with the own IP address as authority part from the NF service consumer, by either handling the updates, or by replying with an HTTP "307 temporary redirect" error response pointing to new NF service producer, or by replying with another HTTP error such as an "404 Not found".
- For a service that includes notifications from the AMF, the NF service consumer shall be prepared to receive notifications for the that service from any NF service producer within a set of NF service producers supporting seamless changes.
