blob: e54c0360926bbcc94eb7f42973ad6969e8c30015 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
.. contents::
:depth: 3
..
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
Nodes Query
===========
In working with AAI's standard REST API, you may have noticed that
certain API paths have a hierarchy to them and require a client to
know multiple object keys to preform GETs. For example: the vserver
object is under tenant, which is itself under cloud-region. If you
wanted to look up a vserver by name, you would still need to know the
tenant-id and cloud-region-id (and cloud-owner) in order to
successfully perform that GET. The nodes API allows for more freedom
in querying AAI, allowing clients to circumvent the need to know
every key in the hierarchy. Using the previous example, the below is
how the API called would change for looking up a vserver by name:
.. code::
GET /aai/v$/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}/tenants/tenant/{tenant-id}/vservers?vserver-name={vserver-name}
becomes
GET /aai/v$/nodes/vservers?vserver-name={vserver-name}
A side effect of this is that if the same vserver name was reused between
multiple cloud-regions or tenants the client will receive multiple
vservers in the response. Vserver ID and vserver name are
intentionally non-unique outside of their cloud-region/tenant
hierarchy, as are many other keys for nested objects.
API URI
~~~~~~~
nodes can be used to start a URI from any node type, whether singular or plural.
.. code::
GET /aai/v$/nodes/{plural}
OR
GET /aai/v$/nodes/{singular}/{key}
From there, it can be expanded on similarly to our Resources API. For example:
.. code::
GET /aai/v$/nodes/{plural}?{property}={value}
GET /aai/v$/nodes/tenant/{tenant-id}/vservers
GET /aai/v$/nodes/generic-vnf/{vnf-id}/related-to/platforms
Optional Query Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~
The Nodes API can make use of all the optional query
parameters available on the standard REST API.
Depth
~~~~~
You can pass a depth query parameter to indicate what level of child objects you want
returned. By default the output will be depth = 0 (no "children", only
"cousin" relationships). When using depth in conjunction with the
format query parameter, it will only apply to the on the resource or
resource_and_url formats.
.. code::
GET /aai/v$/nodes/{plural}/{singular}/{key}?depth={integer}
Nodes Only
~~~~~~~~~~
You can pass a nodes only query parameter to have the output only contain
the object properties with no relationships.
.. code::
GET /aai/v$/nodes/{plural}/{singular}/{key}?nodes-only
OR
GET /aai/v$/nodes/{plural}/{singular}/{key}?format={format}&nodesOnly=true
Format
~~~~~~
You can optionally request an output format different from the default
REST API output. You can reference the list of formats on the `Custom
Query <customQueries.html>`_ wiki page for the full list of available
formats and examples.
.. code::
GET /aai/v$/nodes/{plural}/{singular}/{key}?format={format}
Usage with Custom Query
~~~~~~~~~~~~~~~~~~~~~~~
The Nodes API can be called directly or as the start node for Custom
Queries. Please reference the Custom Queries wiki page for full
documentation on how to use that interface.
.. code::
PUT /aai/v$/query?format={format} with payload like..
{ "start": ["nodes/{plural}/{singular}/{key}"], "query": "query/{query-name}" }
|
