Content for TS 32.158 Word version: 18.1.0

5.1 Design pattern for creating a resource 5.1.1 Creating a resource with identifier creation by the MnS Producer 5.1.2 Creating a resource with identifier creation by the MnS Consumer 5.2 Design pattern for reading a resource 5.3 Design pattern for updating a resource 5.4 Design pattern for deleting a resource 5.5 Design pattern for subscribe/notify 5.5.1 Concept 5.5.2 Subscription creation 5.5.3 Subscription deletion 5.5.4 Notification emission 5.5.5 Subscription retrieval
...

5 Basic design patterns p. 14

5.1 Design pattern for creating a resource p. 14

5.1.1 Creating a resource with identifier creation by the MnS Producer p. 14

Operations to create a (single) resource shall be specified with the HTTP POST method, when the MnS Producer shall create the identifier of the new resource.

Reproduction of 3GPP TS 32.158, Fig. 5.1.1-1: Flow for creating a resource with HTTP POST

Figure 5.1.1-1: Flow for creating a resource with HTTP POST

The procedure is as follows:

The MnS Consumer sends an HTTP POST request to the MnS Producer. The target URI identifies the parent resource below which the new resource shall be created. The target URI shall have no query and no fragment component. The message body shall carry a representation of the resource to be created. The resource representation shall not contain the identifier of the new resource, unless the resource representation format mandates the presence of a resource identifier in which case it shall carry null semantics. If the identifier carries nevertheless a value, the MnS Producer may consider that as a non-binding recommendation by the MnS Consumer. The object class name of the resource to be created shall be specified in the message body as well.
The MnS Producer returns the HTTP POST response. On success, "201 Created" shall be returned. The "Location" header shall be present and carry the URI of the new resource. The URI shall be constructed by the MnS Producer by creating an identifier for the new resource and appending a new path segment containing this identifier to the request URI. The response message body should carry the representation of the new resource. If the resource representation received is not modified, the MnS Producer may also return "204 No Content", instead of "201 Created". The response message body shall be empty in this case. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

The resource representation in the request and response message may not be identical, and may not contain all properties (attributes) that are defined in a schema specifying the format of the representation.

For example, assume the schema for the representation of the resource defines the attributes "attrA", "attrB" and "attrC". When the MnS Consumer has valid values only for the attributes "attrA" and "attrB", then the representation sent to the MnS Producer shall include only these two attributes. When the MnS Producer has no valid value for "attrC" and no default value is defined for attrC, then the response is identical to the request, and a subsequent HTTP GET request for all attributes returns only a representation with the attributes "attrA" and "attrB", but not with the attribute "attrC". However, if the MnS Producer populates "attrC" with some value or a default value is defined for attrC, then the HTTP POST response shall include all three attributes. Likewise, a subsequent HTTP GET request for all attributes returns all three attributes.

A MnS Producer may also modify attribute values included in the request. In this case, the modified values shall be sent back to the MnS Cosumer.

It is also possible that a MnS Producer removes attributes received in the request and includes only a subset of the received attributes in the response.

When the created resource has child resources that are included in the schema definition of the created resource, a representation of these child resources shall neither be included in the resource representation sent to the MnS Producer nor in the resource represententation returned to the MnS Consumer. Including child resources would be an attempt to create multiple resources with a single request. HTTP POST shall be used for the creation of a single resource only.

Only resources, whose parent resource does exist, can be created (directly under that parent). The MnS Producer shall consider an attempt to create a resource, whose parent resource does not exist, as an error.

Note that the parent resource of resources for top-level (root) managed object instances is the NRM root. The NRM root always exists on MnS producers. This ensures that, when no resources for managed object instances have been created yet, the top-level resources can be created.

5.1.2 Creating a resource with identifier creation by the MnS Consumer p. 15

Operations to create a (single) resource shall be specified with the HTTP PUT method, when the MnS Consumer creates the identifier of the new resource.

Reproduction of 3GPP TS 32.158, Fig. 5.1.2-1: Flow for creating a resource with HTTP PUT

Figure 5.1.2-1: Flow for creating a resource with HTTP PUT

The procedure is as follows:

The MnS Consumer sends an HTTP PUT request to the MnS Producer. The target URI identifies the location of the resource to be created. The target URI shall have no query and no fragment component. The message body shall carry the representation of the resource to be created. The representation shall include the identifier and object class name of the new resource.
The MnS Producer returns the HTTP PUT response. On success, "201 Created" shall be returned. The Location header shall carry the URI of the new resource. The response message body shall contain the representation of the new resource. If the resource representation received is not modified, the MnS Producer may also return "204 No Content", instead of "201 Created". The response message body shall be empty in this case. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

As for resource creation with HTTP POST, the resource representation in the request and response message may not be identical and may not contain all properties (attributes) that may be defined in a schema specifying the format of the representation. Also, just like for resource creation with HTTP POST, the resource representation sent to the MnS Producer or returned to the MnS Consumer shall not contain the representation of any child resources of the resource to be created.

As to the existence of parent resources for the resources to be created, the considerations set forth in the preceding clause for HTTP POST apply.

5.2 Design pattern for reading a resource p. 16

Operations to read the representation of a resource shall be specified with the HTTP GET method. The resource to be read is identified with a URI.

Reproduction of 3GPP TS 32.158, Fig. 5.2-1: Flow for reading a resource

Figure 5.2-1: Flow for reading a resource

The procedure is as follows:

The MnS Consumer sends a HTTP GET request to the MnS Producer. The resource to be read is identified with the target URI. The target URI shall have no query and no fragment component. The "Accept" header shall be included in the request and contain the media types acceptable to the MnS Consumer. The message body shall be empty.
The MnS Producer returns the HTTP GET response. On success, "200 OK" shall be returned. The resource representation is carried in the response message body. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

5.3 Design pattern for updating a resource p. 16

Operations to update the complete representation of a (single) resource shall be specified with the HTTP PUT method. The resource to be updated is identified with the target URI.

Reproduction of 3GPP TS 32.158, Fig. 5.3-1: Flow for updating a resource

Figure 5.3-1: Flow for updating a resource

The procedure is as follows:

The MnS Consumer sends an HTTP PUT request to the MnS Producer. The resource to be updated is identified with the target URI. The target URI shall have no query and no fragment component. The message body carries the new representation that shall completely replace the existing resource representation on the MnS Producer.
The MnS Producer returns the HTTP PUT response to the MnS Consumer. On success, "200 OK" or "204 No Content" shall be returned. In the former case the response shall carry the representation of the updated resource in the message body. In the latter case the response shall have no message body. A "200 OK" response including the representation of the updated resource shall be sent when the updated representation of the resource is not identical to the representation received in the request. On failure, the appropriate error code shall be returned. The response message body may provide additional error information. In case the resource does not exist, the resource shall be created if resource creation by MnS consumers is supported for that resource (see clause 5.1.2).

Note that the HTTP PUT method has replace semantics and not merge semantics. A complete resource update in this context does not mean that all properties (attributes) defined by a schema for the representation of the resource need to be contained in the request, but that the existing representation on the MnS producer is replaced completely by the received representation (assuming no default values are defined for any of the attributes of the resource and the MnS Producer does not populate any of the attributes not received in the request with a value).

For example, assume the schema for the representation of a resource defines the attributes "attrA", "attrB" and "attrC". No default value is defined for these attributes. The current representation of the resource on the MnS Producer contains only "attrA" and "attrB".

To update "attrA" and "attrB", the received resource representation needs to contain "attrA" with the new value and "attrB" with the new value.
To update only "attrA", the received resource representation needs to contain "attrA" with the new value and "attrB" with the old value. Sending only a representation with "attrA" deletes "attrB" on the MnS Producer. Vice versa, to update only "attrB", the received resource representation needs to contain "attrA" with the old value and "attrB" with the new value. Sending only a representation with "attrB" deletes "attrA" on the MnS Producer.
In case the received representation contains only "attrC" with some value, the new representation after the update contains only "attrC". The existing attributes "attrA" and "attrB" are deleted.

As for resource creation with HTTP PUT, this behavior is modified if default values are defined for attributes or if the MnS Producer populates attributes not contained in the HTTP PUT request with values. In both cases these attributes shall be returned in the response with the default value or assigned value.

Also, as for resource creation with HTTP PUT, a MnS Producer may modify attribute values included in the request and return the modified values to the MnS Consumer, or remove attributes received in the request and include only a subset of the received attributes in the response.

When the target resource has child resources that are included in the schema definition of the target resource, the representation of these child resources shall neither be included in the resource representation sent to the MnS Producer nor in the resource representation returned to the MnS Consumer. The overwrite semantic of PUT refers only to the target resource and not to child resources.

5.4 Design pattern for deleting a resource p. 17

Operations to delete the representation of a (single) resource shall be specified with the HTTP DELETE method. The resource to be deleted is identified with the target URI in the request message.

Reproduction of 3GPP TS 32.158, Fig. 5.4-1: Flow for deleting a resource

Figure 5.4-1: Flow for deleting a resource

The procedure is as follows:

The MnS Consumer sends an HTTP DELETE request to the MnS Producer. The resource to be deleted is identified with the URI. The target URI shall have no query and no fragment component. The message body is empty.
The MnS Producer returns the HTTP DELETE response to the MnS Consumer. On success, "204 No Content" shall be returned. The response message body shall be empty. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

When resources are structured with parent-child relations in a hierarchical tree, it shall not be possible to delete other resources than leaf resources. Attempts to delete other resources shall result in an error and the "409 Conflict" status code shall be returned by the MnS Producer.

5.5 Design pattern for subscribe/notify p. 18

5.5.1 Concept p. 18

HTTP is based on requests and responses. There is no built-in support for notifications and subscriptions to notifications. These mechanisms need to be modelled based on special subscription resources and the available HTTP methods. When notifications are used the server shall expose at least one subscription resource.

5.5.2 Subscription creation p. 18

To subscribe to notifications the subscriber shall send an HTTP POST request to the subscription resource.

Reproduction of 3GPP TS 32.158, Fig. 5.5.2-1: Flow for creating a subscription

Figure 5.5.2-1: Flow for creating a subscription

The procedure is as follows:

The MnS Consumer (notification subscriber) sends an HTTP POST request to the MnS Producer. The URI shall indicate a subscriptions collection resource. The resources representing existing subscriptions are created below the collection resource. The subscriber shall indicate in the message body the URI to which notifications will be sent (notification sink) and the type of notifications that are subscribed to. Additional filter information may be included in the message body.
The MnS Producer shall return "201 Created" on success. The message body shall carry the representation of the created subscription resource. The "Location" header shall carry the URI of the created subscription resource. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

5.5.3 Subscription deletion p. 18

To cancel a subscription, the subscriber shall delete the corresponding resource with HTTP DELETE.

Reproduction of 3GPP TS 32.158, Fig. 5.5.3-1: Flow for deleting a subscription

Figure 5.5.3-1: Flow for deleting a subscription

The procedure is as follows:

The MnS Consumer (notification subscriber) sends an HTTP DELETE request to the MnS Producer. The URI shall indicate the subscription resource to be deleted.
The MnS Producer returns the HTTP DELETE response to the MnS Consumer. On success, "204 No Content" shall be returned. The message body shall be empty. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

5.5.4 Notification emission p. 19

To send a notification on the occurrence of a notifiable event the MnS Producer sends an HTTP POST request to the notification sink.

Reproduction of 3GPP TS 32.158, Fig. 5.5.4-1: Flow for sending a notification

Figure 5.5.4-1: Flow for sending a notification

The procedure is as follows:

The MnS Producer sends an HTTP POST request to the MnS Consumer. The URI identifies the notification sink. The notification content shall be included in the message body.
The MnS Consumer returns "204 No Content". The message body shall be empty. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

This design pattern requires the MnS Producer (HTTP server) to contain a reduced feature HTTP client for sending HTTP POST requests and receiving HTTP POST responses, and vice versa, the MnS Consumer (HTTP client) to contain a reduced feature HTTP server for receiving HTTP POST requests and sending HTTP POST responses.

5.5.5 Subscription retrieval p. 19

The subscriber can retrieve the information about a specific subscription by invoking the HTTP GETmethod on the URI returned by the server upon creation of this subscription. Information about all subscriptions can be read by invoking the HTTP GET method on the subscriptions collection resource.

Reproduction of 3GPP TS 32.158, Fig. 5.5.5-1: Flow for subscription retrieval

Figure 5.5.5-1: Flow for subscription retrieval

The procedure is as follows:

The MnS Consumer sends an HTTP GET request to the MnS Producer. The URI specifies the subscription resource or subscriptions collection resource to be read.
The MnS Producer returns the HTTP Get response. On success, "200 OK" shall be returned. The representation of the subscription resource or subscriptions collection resource shall be carried in the response message body. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.