A.2 Retrieval of resources
32.1583GPPDesign rules for REpresentational State Transfer (REST) Solution Sets (SS)Management and orchestrationRelease 17TS
A.2.1 Retrieval of a single complete resource with HTTP GET
To retrieve a complete "XyzFunction" resource the MnS Consumer might send the following request.
|
GET /SubNetwork=SN1/ManagedElement=ME1/XyzFunction=XYZF1 HTTP/1.1 Host: example.org Accept: application/json |
The response includes the resource representation
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } } |
Alternatively, the response might include a key ("XyzFunction") specifying the class name of the returned resource
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "XyzFunction": [ { "id": "XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } } ] } |
In the example above "XyzFunction" is of type array to align with the JSON schema of "XyzFunction" defined in clause A.1. Alternatively, "XyzFunction" might also be an object, since the JSON schema specifying the response message body is not required to be identical to the JSON schema specifying the resources contained by a resource.
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "XyzFunction": { "id": "XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } } } |
Alternatively, when using a "data" object the response might look like
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "data": { "XyzFunction": { "id": "XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } } } } |
The MnS Consumer can request also to return a response constructed according to the flat response construction method. In this case the "Accept" header contains the " application/vnd.3gpp.object-tree-flat+json" media type.
|
GET /SubNetwork=SN1/ManagedElement=ME1/XyzFunction=XYZF1 HTTP/1.1 Host: example.org Accept: application/vnd.3gpp.object-tree-flat+json |
The response looks like:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/ vnd.3gpp.object-tree-flat+json [ { "id": "XYZF1", "objectClass": "XyzFunction", "objectInstance": "SubNetwork=SN1,ManagedElement=ME1,XyzFunction=XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } } ] |
The exact syntax of the response body is specified by the JSON schema included in the concrete MnS definition. In current MnS definitions the format of the first example response above is used. This style is also followed in subsequent examples.
A.2.2 Attribute and attribute field selection on a single resource
To retrieve only the "userLabel" attribute and the "mnc" attribute field of the "plmnId" attribute of the "SubNetwork", the MnS Consumer might send:
|
GET /SubNetwork=SN1?attributes=userLabel&fields=/attributes/plmnId/mcc HTTP/1.1 Host: example.org Accept: application/json |
Alternatively one might send as well
|
GET /SubNetwork=SN1?fields=/attributes/userLabel,/attributes/plmnId/mcc HTTP/1.1 Host: example.org Accept: application/json |
The response contains only the selected attribute "userLabel" and the selected attribute field "mnc":
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "SN1", "attributes": { "userLabel": "Berlin NW", "plmnId": { "mnc": 789 } } } |
In this example, the MnS Consumer retrieves the "userLabel" and "vendorName" of the "ManagedElement" whose "id" is equal to "ME1":
|
GET /SubNetwork=SN1/ManagedElement=ME1?attributes=userLabel,vendorName HTTP/1.1 Host: example.org Accept: application/json |
The MnS Producer responds as follows:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "ME1", "attributes": { "userLabel": "Berlin NW 1", "vendorName": "Company XY" } } |
The following request selects all attributes:
|
GET /SubNetwork=SN1/ManagedElement=ME1?fields=/attributes HTTP/1.1 Host: example.org Accept: application/json |
It is thus identical to:
|
GET /SubNetwork=SN1/ManagedElement=ME1 HTTP/1.1 Host: example.org Accept: application/json |
Both requests return the complete resource representation with all attributes:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "ME1", "attributes": { "userLabel": "Berlin NW 1", "vendorName": "Company XY", "location": "TV Tower" } } |
The following request returns the first item of the "perfMetrics" attribute, which is of type array:
|
GET /SubNetwork=SN1/ManagedElement=ME1/PerfMetricJob=PMJ1?fields=attributes/perfMetrics/0 HTTP/1.1 Host: example.org Accept: application/json |
Note indices start with "0" in JSON Pointer. The response looks like:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "PMJ1", "attributes": { "perfMetrics": [ "Metric1" ] } } |
A.2.3 Retrieval of multiple complete resources using scoping and filtering
The following example selects the "SubNetwork" as base object at scope level "0" and all objects at scope level "1":
|
GET /SubNetwork=SN1?scopeType=BASE_SUBTREE&scopeLevel=1 HTTP/1.1 Host: example.org Accept: application/json |
The base object and all objects at scope level "1", irrespective of their object class, are included in the response. The acceptable response media type specified by the "Accept" header field is "application/json", which indicates to the MnS producer to use the hierarchical response construction method
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "SN1", "attributes": { "userLabel": "Berlin NW", "userDefinedNetworkType": "5G", "plmnId": { "mcc": 456, "mnc": 789 } }, "ManagedElement": [ { "id": "ME1", "attributes": { "userLabel": "Berlin NW 1", "vendorName": "Company XY", "location": "TV Tower" } }, { "id": "ME2", "attributes": { "userLabel": "Berlin NW 2", "vendorName": "Company XY", "location": "Grunewald" } } ], "PerfMetricJob": [ { "id": "PMJ1", "attributes": { "granularityPeriod": 5, "perfMetrics": [ "Metric1", "Metric2" ], "objectInstances": [ "Obj1", "Obj2" ] } } ], "ThresholdMonitor": [ { "id": "TM1", "attributes": { "metric": "Metric1", "thresholdLevels": [ { "level": "1", "thresholdValue": 10 }, { "level": "2", "thresholdValue": 20 }, { "level": "3", "thresholdValue": 30 } ] } } ] } |
The MnS Consumer can request also to return a response constructed according to the flat response construction method. In this case the "Accept" header contains the "application/vnd.3gpp.object-tree-flat+json" media type.
|
GET /SubNetwork=SN1?scopeType=BASE_SUBTREE&scopeLevel=1 HTTP/1.1 Host: example.org Accept: application/vnd.3gpp.object-tree-flat+json |
The response looks like:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/vnd.3gpp.object-tree-flat+json [ { "id": "SN1", "objectClass": "SubNetwork", "objectInstance": "SubNetwork=SN1", "attributes": { "userLabel": "Berlin NW", "userDefinedNetworkType": "5G", "plmnId": { "mcc": 456, "mnc": 789 } } }, { "id": "ME1", "objectClass": "ManagedElement", "objectInstance": "SubNetwork=SN1,ManagedElement=ME1", "attributes": { "userLabel": "Berlin NW 1", "vendorName": "Company XY", "location": "TV Tower" } }, { "id": "ME2", "objectClass": "ManagedElement", "objectInstance": "SubNetwork=SN1,ManagedElement=ME2", "attributes": { "userLabel": "Berlin NW 2", "vendorName": "Company XY", "location": "Grunewald" } }, { "id": "PMJ1", "objectClass": "PerfMetricJob", "objectInstance": "SubNetwork=SN1,PerfMetricJob=PMJ1", "attributes": { "granularityPeriod": "5", "perfMetrics": [ "Metric1", "Metric2" ], "objectInstances": [ "Obj1", "Obj2" ] } }, { "id": "TM1", "objectClass": "ThresholdMonitor", "objectInstance": "SubNetwork=SN1,ThresholdMonitor=TM1", "attributes": { "metric": "Metric1", "thresholdLevels": [ { "level": "1", "thresholdValue": 10 }, { "level": "2", "thresholdValue": 20 }, { "level": "3", "thresholdValue": 30 } ] } } ] |
The "objectInstance" of each returned object is present in the response, as required in clause 6.1.4.
When only objects at scope level "1" are requested to be returned, the request looks like:
|
GET /SubNetwork=SN1?scopeType=BASE_NTH_LEVEL&scopeLevel=1 HTTP/1.1 Host: example.org Accept: application/json |
The response does not include the attributes of "SubNetwork" any more, only its "id" is included:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "SN1", "ManagedElement": [ { "id": "ME1", "attributes": { "userLabel": "Berlin NW 1", "vendorName": "Company XY", "location": "TV Tower" } }, { "id": "ME2", "attributes": { "userLabel": "Berlin NW 2", "vendorName": "Company XY", "location": "Grunewald" } } ], "PerfMetricJob": [ { "id": "PMJ1", "attributes": { "granularityPeriod": 5, "perfMetrics": [ "Metric1", "Metric2" ], "objectInstances": [ "Obj1", "Obj2" ] } } ], "ThresholdMonitor": [ { "id": "TM1", "attributes": { "metric": "Metric1", "thresholdLevels": [ { "level": "1", "thresholdValue": 10 }, { "level": "2", "thresholdValue": 20 }, { "level": "3", "thresholdValue": 30 } ] } } ] } |
Similarly, for reading all objects on scope level "2", the MnS Consumer may send:
|
GET /SubNetwork=SN1?scopeType=BASE_NTH_LEVEL&scopeLevel=2 HTTP/1.1 Host: example.org Accept: application/json |
When using the hierarchical response construction method, the response includes the complete representations of the two "XyzFunction" objects. The "SubNetwork" and "ManagedElement" are present with their "id" only; they provide the containment nodes for the "XyzFunction" objects.
|
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": "XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } }, { "id": "XYZF2", "attributes": { "attrA": "abc", "attrB": 552 } } ] } ] } |
The "PerfMetricJob" and "ThresholdMonitor" are not included altogether, not even with the "id" only. This is because these nodes do not represent necessary path components to the scoped objects on the second level.
When using the flat response construction method, the response includes only the two "XyzFunction" objects without containment nodes.
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json [ { "id": "XYZF1", "objectClass": "XyzFunction", "objectInstance": "SubNetwork=SN1,ManagedElement=ME1,XyzFunction=XYZF1", "attributes": { "attrA": "xyz", "attrB": 551 } }, { "id": "XYZF2", "objectClass": "XyzFunction", "objectInstance": "SubNetwork=SN1,ManagedElement=ME1,XyzFunction=XYZF2", "attributes": { "attrA": "abc", "attrB": 552 } } ] |
The following example selects all objects of any class on scope level "1" that have a "location" attribute whose value is equal to "Grunewald":
|
GET /SubNetwork=SN1?\ scopeType=BASE_NTH_LEVEL&scopeLevel=1&\ filter=/*/*[attributes[location="Grunewald"]] HTTP/1.1 Host: example.org Accept: application/json |
The response includes one "ManagedElement" object only:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "SN1", "ManagedElement": [ { "id": "ME2", "attributes": { "userLabel": "Berlin NW 2", "vendorName": "Company XY", "location": "Grunewald" } } ] } |
The input document to the XPath expression is a document whose root node is the object identified by the path component of the target URI and that includes the object representations of the scoped objects. In this example the root node is the "SubNetwork", but it is not scoped and hence included in the input document with its "id" only, i.e. without the "attributes" node. The input document includes furthermore all scoped objects on level "1" with their complete representations (without name-contained objects). These are the two "ManagedElement" objects, the "PerfMetricJob" object, and the "ThresholdMonitor" object.
|
{ "id": "SN1", "ManagedElement": [ { "id": "ME1", "attributes": { "userLabel": "Berlin NW 1", "vendorName": "Company XY", "location": "TV Tower" } }, { "id": "ME2", "attributes": { "userLabel": "Berlin NW 2", "vendorName": "Company XY", "location": "Grunewald" } } ], "PerfMetricJob": [ { "id": "PMJ1", "attributes": { "granularityPeriod": 5, "perfMetrics": [ "Metric1", "Metric2" ], "objectInstances": [ "Obj1", "Obj2" ] } } ], "ThresholdMonitor": [ { "id": "TM1", "attributes": { "metric": "Metric1", "thresholdLevels": [ { "level": "1", "thresholdValue": 10 }, { "level": "2", "thresholdValue": 20 }, { "level": "3", "thresholdValue": 30 } ] } } ] } |
An implementation may be based on available XPath tools. In that case the JSON document may have to be converted to a XML document Note that a valid XML document has one and only one root element. For that reason the "SubNetwork" element needs to be added as root element..
|
<SubNetwork> <id>SN1</id> <ManagedElement> <id>ME1</id> <attributes> <userLabel>Berlin NW 1</userLabel> <vendorName>Company XY</vendorName> <location>TV Tower</location> </attributes> </ManagedElement> <ManagedElement> <id>ME2</id> <attributes> <userLabel>Berlin NW 2</userLabel> <vendorName>Company XY</vendorName> <location>Grunewald</location> </attributes> </ManagedElement> <PerfMetricJob> <id>PMJ1</id> <attributes> <granularityPeriod>5</granularityPeriod> <perfMetrics>Metric1</perfMetrics> <perfMetrics>Metric2</perfMetrics> <objectInstances>Obj1</objectInstances> <objectInstances>Obj2</objectInstances> </attributes> </PerfMetricJob> <ThresholdMonitor> <id>TM1</id> <attributes> <ThresholdLevels> <level>1</level> <thresholdValue>10</thresholdValue> </ThresholdLevels> <ThresholdLevels> <level>2</level> <thresholdValue>20</thresholdValue> </ThresholdLevels> <ThresholdLevels> <level>3</level> <thresholdValue>30</thresholdValue> </ThresholdLevels> </attributes> </ThresholdMonitor> </SubNetwork> |
In this example the complete "ManagedElement" object is the result of applying the XPath expression:
|
<ManagedElement> <id>ME2</id> <attributes> <userLabel>Berlin NW 2</userLabel> <vendorName>Company XY</vendorName> <location>Grunewald</location> </attributes> </ManagedElement> |
XPath predicates allow to specify also ranges. The following example selects objects on scope level "2" that have an attribute with name "attrB" whose value is equal to or greater than 552 and less than 562.
|
GET /SubNetwork=SN1?\ scopeType=BASE_NTH_LEVEL&scopeLevel=2&\ filter=/*/*/*[attributes[attrB>=552 and attrB<562]] HTTP/1.1 Host: example.org Accept: application/json |
The response includes one "XyzFunction" object only:
|
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": "XYZF2", "attributes": { "attrA": "abc", "attrB": 552 } } ] } ] } |
An identical response is returned when using the following requests:
|
GET /SubNetwork=SN1?\ scopeType=BASE_ALL&\ filter=//*[attributes[attrB>=552 and attrB<562]] HTTP/1.1 Host: example.org Accept: application/json |
or
|
GET /SubNetwork=SN1?\ scopeType=BASE_SUBTREE&scopeLevel=2&\ filter=//*[attributes[attrB>=552 and attrB<562]] HTTP/1.1 Host: example.org Accept: application/json |
or
|
GET /SubNetwork=SN1?\ scopeType=BASE_ALL&\ filter=//XyzFunction[attributes[attrB>=552 and attrB<562]] HTTP/1.1 Host: example.org Accept: application/json |
It is possible to combine scoping and filtering with attribute and attribute field selection. The following example returns the containment tree, starting with the "SubNetwork" identified by the target URI.
|
GET /SubNetwork=SN1?scopeType=BASE_ALL&attributes= HTTP/1.1 Host: example.org Accept: application/json |
|
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": "XYZF1" }, { "id": "XYZF2" } ] }, { "id": "ME2" } ], "PerfMetricJob": [ { "id": "PMJ1" } ], "ThresholdMonitor": [ { "id": "TM1" } ] } |
The next example scopes the same subtree as in the previous example and requests to return only "vendorName" attributes instead of no attributes at all.
|
GET /ProvMnS/1700?\ scopeType=BASE_ALL&\ attributes=vendorName HTTP/1.1 Host: example.org Accept: application/json |
This results, according to clause 6.2.3, in removing from the response all scoped resources that do not have a "vendorName" attribute.
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "id": "SN1", "ManagedElement": [ { "id": "ME1", "attributes": { "vendorName": "Company XY" } }, { "id": "ME2", "attributes": { "vendorName": "Company XY" } } ] } |
If the retrieval request identifies resources that do not exist, such as in
|
GET /ProvMnS/1700?scopeType=BASE_NTH_LEVEL&scopeLevel=3 HTTP/1.1 Host: example.org Accept: application/json |
then the MnS producer returns "404 Not Found" in the response status line. More error information may be provided in the response body.
|
HTTP/1.1 204 Not Found Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { "error": { "errorInfo": "No resources at scope level specified in the request." } } |
When the MnS Consumer does not know the root object of the containment tree and wants to retrieve the complete tree starting with the root, the target URI needs to identify the NRM root, i.e. the resource above the root object. According to clause 4.4.2, this resource is identified by the path segment "/{MnSName}/{MnSVersion}", for example "/ProvMnS/1700". In the following example, the "attributes" query parameter is empty and only the name-containment hierarchy (without attributes) is returned.
|
GET /ProvMnS/1700?scopeType=BASE_ALL&attributes= HTTP/1.1 Host: example.org Accept: application/json |
The response is illustrated below. Properties of the MnS may be returned as siblings of "SubNetwork", as indicated in the example below by the placeholder "…".
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { …, "SubNetwork": [ { "id": "SN1", "ManagedElement": [ { "id": "ME1", "XyzFunction": [ { "id": "XYZF1" }, { "id": "XYZF2" } ] }, { "id": "ME2" } ], "PerfMetricJob": [ { "id": "PMJ1" } ], "ThresholdMonitor": [ { "id": "TM1" } ] } ] } |
Multiple root resources can be returned as well. For example, assume a NRM with three "SubNetwork" root resources, then the response may look like:
|
HTTP/1.1 200 OK Date: Tue, 06 Aug 2019 16:50:26 GMT Content-Type: application/json { …, "SubNetwork": [ { "id": "SN1", … }, { "id": "SN2", … }, { "id": "SN3", … } ] } |
Note that when the target URI identifies the NRM root, then the name of the document (root) element, to which an XPath expression is applied, is "nrmRoot". The first step of the location path of an XPath expression is hence "/nrmRoot". For example, the following HTTP GET request returns the "SubNetwork" with the identifier "SN1".
|
GET /ProvMnS/1700?\ scopeType=BASE_ALL&\ filter=/nrmRoot/SubNetwork[id="SN1"] HTTP/1.1 Host: example.org Accept: application/json |