Tech-invite  3GPPspace  IETF RFCs  SIP
index  21  22  23  24  25  26  27  28  29  31  32  33  34  35  36  37  38  4‑5x

Content for  TS 29.501  Word version:  18.0.0

Top   Top   Up   Prev   Next
1…   4…   4.6…   4.7…   5…   5.3…   6…   A… 
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.2 Reading a Resource  4.6.1.1.3 Updating a Resource  4.6.1.1.4 Deleting a Resource  4.6.1.1.5 Query Parameters  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.2 Use of Subscribe/Notify Communication  4.6.2.1 General  4.6.2.2 Management of Subscriptions  4.6.2.2.1 General  4.6.2.2.2 Creation of a Subscription  4.6.2.2.3 Modify a subscription  4.6.2.2.4 Delete a subscription  4.6.2.3 Notifications  4.6.2.4 Special provisions to support the seamless change of AMF as NF service consumer 
...

 

4.6  Use of HTTP Methods  p. 18

4.6.1  Use of Request/Response Communication  p. 18

4.6.1.1  CRUD  p. 18

4.6.1.1.1  Creating a Resource  p. 18
4.6.1.1.1.1  General  p. 18
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. 18
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.1.2-1: Creating a resource using POST
Figure 4.6.1.1.1.2-1: Creating a resource using POST
Up
  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.
Up
4.6.1.1.1.3  Creating a Resource using PUT  p. 19
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.1.3-1: Creating a Resource using HTTP PUT
Figure 4.6.1.1.1.3-1: Creating a Resource using HTTP PUT
Up
  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).
Up
4.6.1.1.2  Reading a Resource  p. 20
4.6.1.1.2.1  Reading a Single Resource  p. 20
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.2.1-1: Reading a resource
Figure 4.6.1.1.2.1-1: Reading a resource
Up
  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).
Up
4.6.1.1.2.2  Querying a Set of Resources  p. 20
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.2.2-1: Query of a collection of resources by using query parameters.
Figure 4.6.1.1.2.2-1: Query of a collection of resources by using query parameters.
Up
Step 1.
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.
Clause 4.9 specifies some possible options for an NF Service Producer to return the representations of multiple resources to a NF Service Consumer.
Up
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.3.1-1: Updating a Resource using HTTP PUT
Figure 4.6.1.1.3.1-1: Updating a Resource using HTTP PUT
Up
  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).
Up
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.
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.3.2-1: Updating a Resource using HTTP PATCH
Figure 4.6.1.1.3.2-1: Updating a Resource using HTTP PATCH
Up
  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).
Up
4.6.1.1.4  Deleting a Resource  p. 23
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.1.4-1: Deleting a resource
Figure 4.6.1.1.4-1: Deleting a resource
Up
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).
Up
4.6.1.1.5  Query Parameters  p. 24
4.6.1.1.5.1  General  p. 24
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.
Up
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.
Up

4.6.1.2  Custom Operations  p. 24

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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.2-1: Custom Operation on a Resource using HTTP POST
Figure 4.6.1.2-1: Custom Operation on a Resource using HTTP POST
Up
  1. 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.
  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.
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.
Reproduction of 3GPP TS 29.501, Fig. 4.6.1.2-2: Custom Operation related to Service using HTTP POST
Figure 4.6.1.2-2: Custom Operation related to Service using HTTP POST
Up
  1. 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.
  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.
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).
Up

4.6.1.3  Use of Asynchronous Operations  p. 25

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.
Up

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:
  1. 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.
  2. 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".
  3. 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.
Up

4.6.2  Use of Subscribe/Notify Communication  p. 26

4.6.2.1  General  p. 26

Subscribe/Notify communication between 5GC NFs can be used to keep involved NFs (consumers of a service) informed of data changes or events that occur at another NF (producer of the service). A notification is a message that contains information about the event.
Service consumer NFs (clients) need to subscribe to notifications at the service provider NF (server). This either happens explicitly by means of creating a new subscription resource (see clause 4.6.2.2), or implicitly by updating a relevant resource.
Service consumer NFs can in principle explicitly or implicitly subscribe to be notified about data change to any type of resource of any resource archetype (Document, Store or Collection). It is up to the API to define the resources that support subscriptions.
When the change/event occurs at the service producer NF, notifications (see clause 4.6.2.3) are sent from the service producer NF to the service consumer NFs. This communication initiated by the service producer to the service consumers requires that the service consumer NF (client) takes the role of an HTTP server and the service producer NF (server) takes the role of an HTTP client.
During the explicit subscription the service consumer NF (client) provides a callback URI and possibly additional filter criteria to the service producer NF (server). When the data-change/event occurs that matches the filter criteria in the subscription, the service producer NF (taking the role of an HTTP client) uses the provided callback URI to notify the service consumer NF (taking the role of an HTTP server) about the change.
Up

4.6.2.2  Management of Subscriptions  p. 27

4.6.2.2.1  General  p. 27
The HTTP method to create a subscription shall be POST. The HTTP method to modify a subscription shall be PUT or PATCH. The HTTP method to delete a subscription (i.e. to unsubscribe) shall be DELETE (see RFC 7231).
Subscriptions may be implicit, i.e. exist without being explicitly created by a dedicated subscribe operation.
Two types of implicit subscriptions exist:
  1. The subscription is implied by an explicit operation different from the subscribe operation, which does not use the GET method. The subscription implied by the explicit operation and the corresponding notification shall be part of the same service.
  2. The subscription exists without any explicit operation.
As an example for the first type, at the UDM the registered AMF (as long as it is registered) is implicitly subscribed to notification about de-registration and (possibly) P-CSCF restoration as side effect of the registration.
As another example for the first type, at the SMF, the AMF that created a SM Context for a PDU session is implicitly subscribed for SM Context Status notification. At AMF change the new AMF updates the SMF with its callback URI for receiving subsequent SM Context Status notification.
As an example for the second type, at the UDR any available UDM is implicitly subscribed to notification about changes of provisioned subscriber data. When provisioned subscriber data are modified at the UDR by means of provisioning, the UDR selects one of the available UDMs (i.e. one of the implicitly subscribed UDMs) and notifies it about the subscriber data change.
In the OpenAPI specification file, notifications for the second type of implicit subscriptions shall be specified as part of an explicit subscription.
Up
4.6.2.2.2  Creation of a Subscription  p. 27
Figure 4.6.2.2.2-1 illustrates explicit creation of a subscription.
Reproduction of 3GPP TS 29.501, Fig. 4.6.2.2.2-1: Creation of a subscription
Figure 4.6.2.2.2-1: Creation of a subscription
Up
The parent resource (collection of subscriptions) is identified by the request URI.
The data structure in the payload body of the POST request shall contain a callback URI, and may contain additional criteria to filter the set of events that trigger a notification. The request may contain an expiry time, suggested by the NF Service Consumer as a hint, representing the time up to which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications.
On success, "201 Created" shall be returned, the payload body of the POST response shall contain a representation of the created subscription, and the "Location" header 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 response based on operator policies and taking into account the expiry time included in the request, may contain an expiry time (i.e. a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time. If the expiry time is not included in the response, the NF Service Consumer shall consider the subscription to be valid without an expiry time.
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.9).
Up
4.6.2.2.3  Modify a subscription  p. 28
4.6.2.2.3.1  Modification of a Subscription Using HTTP PUT  p. 28
Procedures that allow a NF service consumer to update the subscription at the server by means of a complete replacement shall use the HTTP PUT method to replace the current subscription with a new representation.
Figure 4.6.2.2.3.1-1 illustrates modification a subscription using HTTP PUT.
Reproduction of 3GPP TS 29.501, Fig. 4.6.2.2.3.1-1: Modification a subscription using HTTP PUT
Figure 4.6.2.2.3.1-1: Modification a subscription using HTTP PUT
Up
  1. The NF Service Consumer shall send a PUT request to the resource URI representing the individual subscription. The payload body of the PUT request shall contain the subscription information to be replaced including the criteria to filter the set of events that trigger a notification. The request may contain an updated expiry time, suggested by the NF Service Consumer as a hint, to extend the subscription lifetime, representing the time upto which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications. If the request does not contain an expiry time, the NF Service Producer shall consider that the NF Service Consumer requests for an extension of the existing subscription lifetime without indicating any specific expiration time; still, the NF Service Producer shall be authoritative to set the expiry time in the subscription response according to its own policies.
  2. On success, "204 No Content" without any response body or "200 OK" with a response body providing current resource representation shall be returned.
    When "200 OK" is returned, the response based on operator policies and taking into account the expiry time included in the request, may contain an expiry time (i.e a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer, as specified in clause 4.6.2.2.2. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time. If the expiry time is not included in the response, the NF Service Consumer shall consider the subscription to be valid without an expiry time.
    When "204 No Content" is returned, it shall be interpreted that the NF Service Producer accepted entirely the resource representation provided by the NF Service Consumer in the request; e.g., if the request contained a proposed expiry time, a 204 response shall be interpreted as if such timestamp is accepted by the NF Service Producer as the expiration time for the subscription and, similarly, if the request did not contain a proposed expiry time, a 204 response shall be interpreted as if no expiration time is set by the NF Service Producer for the subscription.
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 NF Service Consumer is not allowed to update the subscription information, 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).
If the resource that is to be updated does not exist at the NF service producer, the "404 Not Found" HTTP status code shall be returned.
Up
4.6.2.2.3.2  Modification of a Subscription Using HTTP PATCH  p. 29
Procedures that allow a NF service consumer to update subscription at the server by means of a partial replacement shall use the HTTP PATCH method (see RFC 5789) to modify the current subscription according to given modification instructions.
Figure 4.6.2.2.3.2-1 illustrates updating a resource using HTTP PATCH.
Reproduction of 3GPP TS 29.501, Fig. 4.6.2.2.3.2-1: Modification a subscription using HTTP PATCH
Figure 4.6.2.2.3.2-1: Modification a subscription using HTTP PATCH
Up
  1. The NF Service Consumer shall send a PATCH request to the resource URI representing the individual subscription. The payload body of the PATCH request shall contain the modification instructions. The request may contain an expiry time (i.e. a future timestamp), requested by the NF Service Consumer, representing the time upto which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications.
  2. On success, "204 No Content" without any response body or "200 OK" with a response body containing the modified subscription information shall be returned. When "204 No Content" is returned and if the request included an expiry time, then the requested expiry time shall be accepted by the NF Service Producer. When "200 OK" is returned and if the request included an expiry time then the response based on operator policies and taking into account the expiry time included in the request, shall contain an expiry time (i.e. a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer, as specified in clause 4.6.2.2.2. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time.
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).
Up
4.6.2.2.4  Delete a subscription  p. 29
Figure 4.6.2.2.4-1 illustrates explicit deletion of a subscription.
Reproduction of 3GPP TS 29.501, Fig. 4.6.2.2.4-1: Deletion of a subscription
Figure 4.6.2.2.4-1: Deletion of a subscription
Up
  1. The NF Service Consumer shall send a DELETE request to the resource URI representing the individual subscription. The request body shall be empty.
  2. On success, "204 No Content" shall be returned. The response body shall be empty.
    On failure, the appropriate HTTP status code indicating the error shall be returned in the DELETE response body (see clause 4.8).

4.6.2.3  Notifications  p. 30

The HTTP method for the notification that corresponds to an explicit subscription shall be POST (see RFC 7231).
Figure 4.6.2.3-1 illustrates a notification.
Reproduction of 3GPP TS 29.501, Fig. 4.6.2.3-1: Notification
Figure 4.6.2.3-1: Notification
Up
  1. The callback reference provided during creation of the subscription resource, or otherwise known from implicit subscription, is used as the request URI. The callback reference for implicit subscriptions are obtained from the NRF. When an NF / NF service registers with the NRF, the default notification subscriptions along with the callback URI for receiving those notifications may be provided (see clause 6.1.6.2.3 of TS 29.510).
    The payload body of the POST request shall contain the notification payload.
    The payload body of the notification should follow the resource definition of the subscribed resource and can for example be based on the resource definition of the GET operation, but it is up to the API to define the notification resource definition.
    Each API that supports subscription to collection/store archetype resources, should specify in their semantics whether notifications should be sent by changes on the collection/store resource ONLY (i.e. creation/deletion of the main top-level resource itself, and creation/deletion of its children), or if in addition the consumer can expect to get notifications from changes on the resource representation.
  2. On success, "200 OK" shall be returned if any information needs to be included in the payload body of the POST response; otherwise, "204 No Content" shall be returned and the payload body of the POST 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 POST response body (see clause 4.8).
Up

4.6.2.4  Special provisions to support the seamless change of AMF as NF service consumer  p. 31

Services consumed by an 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 AMF as NF service consumer, the procedures in clause 4.6.2 are applied with the following special provisions:
  1. When becoming aware that a new AMF is requiring notifications related to a subscription resource, the NF service producer shall exchange the authority part of the corresponding Notification URI with the address of that new NF service consumer and shall use that URI in subsequent communication.
  2. Each AMF within a set of AMFs supporting seamless changes shall be prepared to receive notifications at the Notification URI constructed according to bullet 1 with the own IP address as authority part from the NF service producer, by either handling the notifications, or by replying with an HTTP "307 temporary redirect" error response pointing to new NF service consumer, or by replying with another HTTP error such as an "404 Not found".
Up

Up   Top   ToC