A.3 Creation of resources
32.1583GPPDesign rules for REpresentational State Transfer (REST) Solution Sets (SS)Management and orchestrationRelease 17TS
A.3.1 Creation of a resource with HTTP PUT
In this example a new "XyzFunction" resource is created. The target URI specifies the location of the new resource. The object class name of the resource to be created is present in the request. The "id" of the new resource is "XYZF3" and created by the MnS Consumer. The "id" contained in the resource representation carried in the request message body and the "id" in the target URI are identical.
|
PUT /SubNetwork=SN1/ManagedElement=ME1/XyzFunction=XYZF3 HTTP/1.1 Host: example.org Content-Type: application/json { "id": "XYZF3", "objectClass": "XyzFunction", "attributes": { "attrA": "ghi", "attrB": 553 } } |
If the HTTP PUT request succeeds, the status code "201 Created" is returned in the response status line. The location header is present, its value is the URI of the created resource. The response message body contains the complete representation of the new resource. The name of the object class may or may not be present in the response.
|
HTTP/1.1 201 Created Date: Tue, 06 Aug 2019 16:50:26 GMT Location: http://example.org/SubNetwork=SN1/ManagedElement=ME1/XyzFunction=XYZF3 Content-Type: application/json { "id": "XYZF3", "attributes": { "attrA": "ghi", "attrB": 553 } } |
In this example, the MnS Producer creates the object with the attribute name/value pairs as provided in the request. For that reason, "204 No Content" may be returned in the status line instead of "201 Created". The response message body is absent in this case.
|
HTTP/1.1 204 No Content Date: Tue, 06 Aug 2019 16:50:26 GMT Location: http://example.org/SubNetwork=SN1/ManagedElement=ME1/XyzFunction=XYZF3 Content-Type: application/json |
A.3.2 Creation of a resource with HTTP POST
When creating a new resource with POST the target URI identifies the parent resource of the new resource to be created. The identifier of the new resource is created by the MnS Producer, hence the "id" is equal to "null" in the POST request. If the "id" carries a value, then the MnS Producer may consider that value as a non-binding recommendation by the MnS Consumer. The request message body includes the object class name of the resource to be created.
|
POST /SubNetwork=SN1/ManagedElement=ME1 HTTP/1.1 Host: example.org Content-Type: application/json { "id": "null", "objectClass": "XyzFunction", "attributes": { "attrA": "ghi", "attrB": 553 } } |
For the response body the same provisions as for resource creation with HTTP PUT apply.
|
HTTP/1.1 201 Created Date: Tue, 06 Aug 2019 16:50:26 GMT Location: http://example.org/ SubNetwork=SN1/ManagedElement=ME1/XyzFunction=123e4567-e89b Content-Type: application/json { "id": "123e4567-e89b", "attributes": { "attrA": "ghi", "attrB": 553 } } |
When creating a root resource of the model, the path component of the request URI refers to the parent resource of the top level managed object instances as defined in clause 4.4.4.
|
POST /ProvMnS/1700 HTTP/1.1 Host: example.org Content-Type: application/json { "id": "null", "objectClass": "SubNetwork", "attributes": { "userLabel": "Berlin NW", "userDefinedNetworkType": "5G", "plmnId": { "mcc": 456, "mnc": 789 } } } |
A.3.3 Creation of multiple resources with 3GPP JSON Merge Patch
One or more resources can be created with a single 3GPP JSON Merge Patch request. The following example shows the creation of a complete subtree for a new "ManagedElement" below "SubNetwork".
The target URI has been chosen to identify the first common ancestor of the resources to be created. In this case, it is the parent of the base object of the tree to be created. The "objectClass" property is present for the resources to be created.
|
PATCH /SubNetwork=SN1 HTTP/1.1 Host: example.org Content-Type: application/3gpp-merge-patch+json { "id": "SN1", "ManagedElement": [ { "id": "ME3", "objectClass": "ManagedElement", "attributes": { "userLabel": " Berlin NW 3", "vendorName": "Company XY", "location": "Spandau" }, "XyzFunction": [ { "id": "XYZF1", "objectClass": "XyzFunction", "attributes": { "attrA": "xyz", "attrB": 771 } }, { "id": "XYZF2", "objectClass": "XyzFunction", "attributes": { "attrA": "abc", "attrB": 772 } } ] } ] } |
The MnS Producer might respond as follows to indicate the PATCH request was successful and the received resource representation was not modified.
|
HTTP/1.1 204 No Content Date: Tue, 06 Aug 2019 16:50:26 GMT |
The next example shows how a new "XyzFunction" resource is added to each of the "ManagedElement" resouces.
In this case, the parent of the parent of the "XyzFunction" resources to be created has been chosen as the common ancestor referenced by the target URI. The "objectClass" property is present for the resources to be created.
The "ManagedElement" resources are present with their "id" only. These resources are required to bridge the containment tree from the "SubNetwork" target resource to the created "XyzFunction" resources.
|
PATCH /SubNetwork=SN1 HTTP/1.1 Host: example.org Content-Type: application/3gpp-merge-patch+json { "id": "SN1", "ManagedElement": [ { "id": "ME1", "XyzFunction": [ { "id": "XYZF3", "objectClass": "XyzFunction", "attributes": { "attrA": "def", "attrB": 553 } } ] }, { "id": "ME2", "XyzFunction": [ { "id": "XYZF1", "objectClass": "XyzFunction", "attributes": { "attrA": "def", "attrB": 661 } } ] } ] } |
The MnS Producer might respond again as follows to indicate the successful creation of the resources.
|
HTTP/1.1 204 No Content Date: Tue, 06 Aug 2019 16:50:26 GMT |
Assume now that for "XyzFunction" a third attribute "attrC" is defined and that this attribute has a default value of "5". The MnS Producer assigns the default value after reception of the PATCH request and before creating the resource when no value is provided for "attrC" in the request. In this case the response includes the modified resource representations.
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "SN1", "ManagedElement": [ { "id": "ME1", "XyzFunction": [ { "id": "XYZF3", "objectClass": "XyzFunction", "attributes": { "attrA": "def", "attrB": 553, "attrC": 5 } } ] }, { "id": "ME2", "XyzFunction": [ { "id": "XYZF1", "objectClass": "XyzFunction", "attributes": { "attrA": "def", "attrB": 661, "attrC": 5 } } ] } ] } |
A.3.4 Creation of multiple resources with 3GPP JSON Patch
One or more resources can be created with a single 3GPP JSON Patch request. The following example shows the creation of a complete subtree for a new network entity represented by a "ManagedElement" resource and two "XyzFunction" resources. The target URI has been chosen to identify the first common ancestor of the resources to be created. The "path" specifies the offset from the target resource to the resource to be created. The "path" has no fragment component. Parent resources are created before child resources following the order of the operations in the patch document. The class name of the object to be created is specified in each patch operation.
|
PATCH /SubNetwork=SN1 HTTP/1.1 Host: example.org Content-Type: application/3gpp-json-patch+json [ { "op": "add", "path": "/ManagedElement=ME3", "value": { "id": "ME3", "objectClass": "ManagedElement", "attributes": { "userLabel": " Berlin NW 3", "vendorName": "Company XY", "location": "Spandau" } } }, { "op": "add", "path": "/ManagedElement=ME3/XyzFunction=XYZF1", "value": { "id": "XYZF1", "objectClass": "XyzFunction", "attributes": { "attrA": "xyz", "attrB": 771 } } }, { "op": "add", "path": "/ManagedElement=ME3/XyzFunction=XYZF2", "value": { "id": "XYZF2", "objectClass": "XyzFunction", "attributes": { "attrA": "abc", "attrB": 772 } } } ] |
Note that each resource to be created shall be specified with a dedicated "add" operation. The following patch document is hence invalid as it attempts to create three resources with a single "add" operation.
|
PATCH /SubNetwork=SN1 HTTP/1.1 Host: example.org Content-Type: application/3gpp-json-patch+json [ { "op": "add", "path": "/ManagedElement=ME3", "value": { "id": "ME3", "objectClass": "ManagedElement", "attributes": { "userLabel": " Berlin NW 3", "vendorName": "Company XY", "location": "Spandau" }, "XyzFunction": [ { "id": "XYZF1", "objectClass": "XyzFunction", "attributes": { "attrA": "xyz", "attrB": 771 } }, { "id": "XYZF2", "objectClass": "XyzFunction", "attributes": { "attrA": "abc", "attrB": 772 } } ] } } ] |
It is not an error if the target location of an "add" operation as specified by the "path" property does exist. In this case the content of the target location is replaced with the content of the "value" property. For example, in the following example, the first "ManagedElement" resource already exists. The patch document is applied successfully though. The representation of the first "ManagedElement" resource is replaced and the second "ManagedElement" resource is created.
Note that the attributes "vendorName" and "location" are removed from the representation of the first "ManagedElement" resource. The "userLabel" attribute is updated.
|
PATCH /SubNetwork=SN1 HTTP/1.1 Host: example.org Content-Type: application/3gpp-json-patch+json [ { "op": "add", "path": "/ManagedElement=ME2", "value": { "id": "ME2", "objectClass": "ManagedElement", "attributes": { "userLabel": " Berlin NW 4" } } }, { "op": "add", "path": "/ManagedElement=ME3", "value": { "id": "ME3", "objectClass": "ManagedElement", "attributes": { "userLabel": " Berlin NW 3", "vendorName": "Company XY", "location": "Spandau" } } } ] |