summaryrefslogtreecommitdiffstats
path: root/docs/AAI REST API Documentation/nodesQuery.rst
blob: 3c2ae5541d5394248cd7eae1cfe84b5e779a3d3e (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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
.. 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
===========

A&AI Nodes Query Implementation Notes:	

Overview
--------

AAI continues to support this API, but clients may find that `Custom
Queries <customQueries.html>`_ meet the needs more most queries.

The Nodes Query mechanism is mostly being implemented in support of
searching the pservers which do not have the ipv4-oam-ipaddress
set. It will allow nodes to be searched based on certain properties of
the nodes. It will allow search based on properties being set, not set
or set to specific values.

The Nodes Query API is implemented using the GET method with the following URL:

.. code::

   /aai/<version>/search/nodes-query

   ex. /aai/v16/search/nodes-query

New version numbers will be supported and older versions eventually
retired. Please look for other AAI documentation for what version to
use in which environment/release.

The URL expects the following URL parameters:

**search-node-type** - node type of the node to be searched. 

**filter** – list of properties that specify the search
criterion. Format will be

.. code::

 filter=<property-name>:<EQUALS|DOES-NOT-EQUAL|EXISTS|DOES-NOT-EXIST>:<property-value>
 
 such as

 filter=ipv4-oam-address:DOES-NOT-EXIST:

For EXISTS and DOES-NOT-EXIST the property value is not specified
(second colon is included). Multiple filter criteria may be specified.

The queries return a search-results object back which includes a list
of result-data which contains the node-type and a link for each
resource that was found. 


Requirements
------------

* If the search-node-type is not supported by the application, a HTTP
  response code of 400 and Parameter passed error is returned

* If no nodes can be found that meet the search criteria a HTTP
  response code of 200 with an empty list is returned

* The search results can be asked to be returned in json or xml based
  on the ACCEPT header.
  
* If no filter params are specified, it would return all nodes of that node type.

Design
------

* REST GET api and dbmap classes added to process the search payload via a GET

* New method searchForNodes() created in dbgen:DbSearch that does the
  search based on the node type and the filter list and returns the
  SearchResults object

  - The search does not require the properties used in the search to
    be indexed

  - The filterParams will just be properties of the node itself.  A
    future version could have another parameter with some more
    interesting search stuff – we’ll see what other queries are being
    asked for and what makes sense to treat like this.

  - As other requests come in, this query mechanism may be re-used if
    the requirements are able to fit this.

Supported queries
-----------------

* Search pserver nodes for which ipv4-oam-address DOES-NOT-EXIST 

.. code::

 URL:
 /aai/v4/search/nodes-query?search-node-type=pserver&filter=ipv4-oam-address:DOES-NOT-EXIST:
 
Search result

.. code::

 <search-results xmlns="http://org.onap.aai.inventory/v16">
   <result-data>
      <resource-type>pserver</resource-type>
      <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/mygreatpserver</resource-link>
   </result-data>
   <result-data>
      <resource-type>pserver</resource-type>
      <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/myothergreatpserver/</resource-link>
   </result-data>
   <result-data>
      <resource-type>pserver</resource-type>
      <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/stillanothergreatpserver</resource-link>
   </result-data>
   <result-data>
      <resource-type>pserver</resource-type>
      <resource-link>https://aai.onap:8443/aai/v4/cloud-infrastructure/pservers/pserver/testbestestpserver</resource-link>
   </result-data>
 </search-results>