docs/AAI REST API Documentation/nodesQuery.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 A&AI Nodes Query Implementation Notes:
  11
  12 Overview
  13 --------
  14
  15 AAI continues to support this API, but clients may find that `Custom
  16 Queries <customQueries.html>`_ meet the needs more most queries.
  17
  18 The Nodes Query mechanism is mostly being implemented in support of
  19 searching the pservers which do not have the ipv4-oam-ipaddress
  20 set. It will allow nodes to be searched based on certain properties of
  21 the nodes. It will allow search based on properties being set, not set
  22 or set to specific values.
  23
  24 The Nodes Query API is implemented using the GET method with the following URL:
  25
  26 .. code::
  27
  28    /aai/<version>/search/nodes-query
  29
  30    ex. /aai/v16/search/nodes-query
  31
  32 New version numbers will be supported and older versions eventually
  33 retired. Please look for other AAI documentation for what version to
  34 use in which environment/release.
  35
  36 The URL expects the following URL parameters:
  37
  38 **search-node-type** - node type of the node to be searched.
  39
  40 **filter** – list of properties that specify the search
  41 criterion. Format will be
  42
  43 .. code::
  44
  45  filter=<property-name>:<EQUALS|DOES-NOT-EQUAL|EXISTS|DOES-NOT-EXIST>:<property-value>
  46
  47  such as
  48
  49  filter=ipv4-oam-address:DOES-NOT-EXIST:
  50
  51 For EXISTS and DOES-NOT-EXIST the property value is not specified
  52 (second colon is included). Multiple filter criteria may be specified.
  53
  54 The queries return a search-results object back which includes a list
  55 of result-data which contains the node-type and a link for each
  56 resource that was found.
  57
  58
  59 Requirements
  60 ------------
  61
  62 * If the search-node-type is not supported by the application, a HTTP
  63   response code of 400 and Parameter passed error is returned
  64
  65 * If no nodes can be found that meet the search criteria a HTTP
  66   response code of 200 with an empty list is returned
  67
  68 * The search results can be asked to be returned in json or xml based
  69   on the ACCEPT header.
  70
  71 * If no filter params are specified, it would return all nodes of that node type.
  72
  73 Design
  74 ------
  75
  76 * REST GET api and dbmap classes added to process the search payload via a GET
  77
  78 * New method searchForNodes() created in dbgen:DbSearch that does the
  79   search based on the node type and the filter list and returns the
  80   SearchResults object
  81
  82   - The search does not require the properties used in the search to
  83     be indexed
  84
  85   - The filterParams will just be properties of the node itself.  A
  86     future version could have another parameter with some more
  87     interesting search stuff – we’ll see what other queries are being
  88     asked for and what makes sense to treat like this.
  89
  90   - As other requests come in, this query mechanism may be re-used if
  91     the requirements are able to fit this.
  92
  93 Supported queries
  94 -----------------
  95
  96 * Search pserver nodes for which ipv4-oam-address DOES-NOT-EXIST
  97
  98 .. code::
  99
 100  URL:
 101  /aai/v4/search/nodes-query?search-node-type=pserver&filter=ipv4-oam-address:DOES-NOT-EXIST:
 102
 103 Search result
 104
 105 .. code::
 106
 107  <search-results xmlns="http://org.onap.aai.inventory/v16">
 108    <result-data>
 109       <resource-type>pserver</resource-type>
 110       <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/mygreatpserver</resource-link>
 111    </result-data>
 112    <result-data>
 113       <resource-type>pserver</resource-type>
 114       <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/myothergreatpserver/</resource-link>
 115    </result-data>
 116    <result-data>
 117       <resource-type>pserver</resource-type>
 118       <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/stillanothergreatpserver</resource-link>
 119    </result-data>
 120    <result-data>
 121       <resource-type>pserver</resource-type>
 122       <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/testbestestpserver</resource-link>
 123    </result-data>
 124  </search-results>