docs/AAI REST API Documentation/nodesApi.rst

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