docs/AAI REST API Documentation/genericQueries.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 AAI Generic Query Implementation Notes
   8
   9 Overview
  10 ========
  11
  12 The Generic Query mechanism allows to search for certain nodes of
  13 “include” node types at a specified “depth” from the from a particular
  14 start node of type “start-node-type” identified by specifying its
  15 “key” values.
  16
  17 The Generic Query is implemented using the GET method with the
  18 following URL that takes 4 query params:
  19
  20 .. code-block::
  21
  22    /aai/<version>/search/generic-query
  23
  24    Ex. /aai/v16/search/generic-query
  25
  26 Please look for other AAI documentation for what version to use in
  27 which environment/release.
  28
  29 **key** - multiple values that together specify the params to select a
  30  unique start node. For example for selecting a customer we would
  31  specify
  32
  33 .. code-block::
  34
  35     key=customer.global-customer-id:ma9181-203-customerid&key=service-subscription.service-type:example-service-type
  36
  37 **start-node-type** - node type of the start node. For example
  38  start-node-type=service-instance
  39
  40 **include** - multiple values of the node types that need to be
  41  returned as part of the query-result. For example
  42
  43 .. code-block::
  44
  45     include=vce&include=port-group
  46
  47 **depth** – look for include node types within a certain depth from
  48  the start-node-type
  49
  50 The queries return a search-results object back which includes a list
  51 of result-data which contains the node-type and a link for each
  52 resource that was found.
  53
  54 Requirements
  55 ============
  56
  57 * At depth=0, only the start node is returned, include is not needed
  58
  59 * At any depth > 0 and <= 6, If start-node-type is in the include –
  60   that should also be returned
  61
  62 * The depth has a max value of 6 – an error will be returned if a
  63   value higher than 6 is used
  64
  65 * A special node type of “all” can be specified for include when all
  66   nodes under the start node are to be searched for
  67
  68 * If a start-node cannot be found based on the key a HTTP response
  69   code of 404 Node not found error is returned
  70
  71 * If no nodes can be found that meet the search criteria a HTTP
  72   response code of 200 with an empty list is returned
  73
  74 * The search results can be asked to be returned in json or xml based
  75   on the ACCEPT header. For 1504, the queries are expected to be used
  76   by MSO and therefore will use an ACCEPT header of application/xml.
  77
  78 Supported Queries
  79 =================
  80
  81 Search customer and service-subscription by service instance id
  82
  83 .. code-block::
  84
  85    URL:
  86
  87    /aai/v16/search/generic-query?key=service-instance.service-instance-id:testserviceinstance&start-node-type=service-instance&include=customer&include=service-subscription&include=service-instance&depth=2
  88
  89 Search result:
  90
  91 .. code-block:: xml
  92
  93  <search-results xmlns="http://com.att.aai.inventory/v16">
  94    <result-data>
  95       <resource-type>customer</resource-type>
  96       <resource-link>https://mtinjvmsdn30.cip.att.com:8443/aai/v16/business/customers/customer/globalspanos/</resource-link>
  97    </result-data>
  98    <result-data>
  99       <resource-type>service-subscription</resource-type>
 100       <resource-link>https://mtinjvmsdn30.cip.att.com:8443/aai/v16/business/customers/customer/globalspanos/service-subscriptions/service-subscription/ptplgamma/</resource-link>
 101    </result-data>
 102    <result-data>
 103       <resource-type>service-instance</resource-type>
 104       <resource-link>https://mtinjvmsdn30.cip.att.com:8443/aai/v16/business/customers/customer/globalspanos/service-subscriptions/service-subscription/ptplgamma/service-instances/service-instance/arnoldave/</resource-link>
 105    </result-data>
 106  </search-results>
 107
 108 Search the VCE and its port groups and cvlan tags given the service instance id.
 109
 110 .. code-block::
 111
 112    URL: /aai/v16/search/generic-query?key=service-instance.service-instance-id:arnoldave&start-node-type=service-instance&include=vce&include=port-group&include=cvlan-tag&depth=3
 113
 114 Search result:
 115
 116 .. code-block:: xml
 117
 118  <search-results xmlns="http://org.onap.aai.inventory/v16">
 119    <result-data>
 120       <resource-type>cvlan-tag</resource-type>
 121       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/port-groups/port-group/spanosifc2/cvlan-tags/cvlan-tag/333/</resource-link>
 122    </result-data>
 123    <result-data>
 124       <resource-type>cvlan-tag</resource-type>
 125       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/port-groups/port-group/spanosifc1/cvlan-tags/cvlan-tag/333/</resource-link>
 126    </result-data>
 127    <result-data>
 128       <resource-type>cvlan-tag</resource-type>
 129       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/port-groups/port-group/spanosifc1/cvlan-tags/cvlan-tag/111/</resource-link>
 130    </result-data>
 131    <result-data>
 132       <resource-type>port-group</resource-type>
 133       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/port-groups/port-group/spanosifc1/</resource-link>
 134    </result-data>
 135    <result-data>
 136       <resource-type>vce</resource-type>
 137       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/</resource-link>
 138    </result-data>
 139    <result-data>
 140       <resource-type>cvlan-tag</resource-type>
 141       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/port-groups/port-group/spanosifc2/cvlan-tags/cvlan-tag/222/</resource-link>
 142    </result-data>
 143    <result-data>
 144       <resource-type>port-group</resource-type>
 145       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/spanosvce/port-groups/port-group/spanosifc2/</resource-link>
 146    </result-data>
 147  </search-results>
 148
 149 Customer GET based on tenant id
 150
 151 .. code-block::
 152
 153    URL:
 154
 155    /aai/v16/search/generic-query?key=tenant.tenant-id:spanospizzatenant&start-node-type=tenant&include=tenant&include=customer&include=service-subscription&depth=2
 156
 157 Search Result:
 158
 159 .. code-block:: xml
 160
 161  <search-results xmlns="http://org.onap.aai.inventory/v16">
 162    <result-data>
 163       <resource-type>customer</resource-type>
 164       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/examplecustomer/</resource-link>
 165    </result-data>
 166    <result-data>
 167       <resource-type>service-subscription</resource-type>
 168       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/examplecustomer/service-subscriptions/service-subscription/ptplgamma/</resource-link>
 169    </result-data>
 170    <result-data>
 171       <resource-type>tenant</resource-type>
 172       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/tenants/tenant/exampletenant/</resource-link>
 173    </result-data>
 174  </search-results>
 175
 176 Search the tenant given a customer and service subscription.
 177
 178 .. code-block::
 179
 180    URL:
 181
 182    /aai/v16/search/generic-query?key=customer.global-customer-id:example-customer&key=service-subscription.service-type:example-service-type&start-node-type=service-subscription&include=tenant&include=service-subscription&depth=1
 183
 184 Search Result:
 185
 186 .. code-block::
 187
 188   <search-results xmlns="http://org.onap.aai.inventory/v16">
 189    <result-data>
 190       <resource-type>service-subscription</resource-type>
 191       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/examplecustomer/service-subscriptions/service-subscription/ptplgamma/</resource-link>
 192    </result-data>
 193    <result-data>
 194       <resource-type>tenant</resource-type>
 195       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/tenants/tenant/spanospizzatenant/</resource-link>
 196    </result-data>
 197  </search-results>
 198
 199 For a service Instance - get its resource-link given the service-instance-id
 200
 201 .. code-block::
 202
 203    URL:
 204
 205    /aai/v16/search/generic-query?key=service-instance.service-instance-id:exampleservice&start-node-type=service-instance&depth=0
 206
 207 Search Result:
 208
 209 .. code-block:: xml
 210
 211  <search-results xmlns="http://org.onap.aai.inventory/v4">
 212    <result-data>
 213       <resource-type>service-instance</resource-type>
 214       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/examplecustomer/service-subscriptions/service-subscription/ptplgamma/service-instances/service-instance/arnoldave/</resource-link>
 215    </result-data>
 216  </search-results>
 217
 218 Get service-instance and service-subscription from vce
 219
 220 .. code-block::
 221
 222    URL:
 223    /aai/v16/search/generic-query?key=vce.vnf-id:spanosvce&start-node-type=vce&include=service-instance&include=service-subscription&depth=2
 224
 225 Search Result:
 226
 227 .. code-block:: xml
 228
 229  <search-results xmlns="http://org.onap.aai.inventory/v16">
 230    <result-data>
 231       <resource-type>service-instance</resource-type>
 232       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/examplecustomer/service-subscriptions/service-subscription/ptplgamma/service-instances/service-instance/arnoldave/</resource-link>
 233    </result-data>
 234    <result-data>
 235       <resource-type>service-subscription</resource-type>
 236       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/examplecustomer/service-subscriptions/service-subscription/ptplgamma/</resource-link>
 237    </result-data>
 238  </search-results>
 239
 240 Get all the nodes for a customer
 241
 242 .. code-block::
 243
 244    URL:
 245
 246    /aai/v16/search/generic-query?key=customer.global-customer-id:examplecustomer&start-node-type=customer&include=all&depth=6
 247
 248 Search Result:
 249
 250 .. code-block:: xml
 251
 252  <search-results xmlns="http://org.onap.aai.inventory/v16">
 253    <result-data>
 254       <resource-type>service-capability</resource-type>
 255       <resource-link>https://aai.onap:8443/aai/v16/service-design-and-creation/service-capabilities/service-capability/ptplgamma/ptplbrocade-vce/</resource-link>
 256    </result-data>
 257    <result-data>
 258       <resource-type>vserver</resource-type>
 259       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/tenants/tenant/examplepizzatenant/vservers/vserver/ccwvm1/</resource-link>
 260    </result-data>
 261    <result-data>
 262       <resource-type>cvlan-tag</resource-type>
 263       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/port-groups/port-group/exampleifc2/cvlan-tags/cvlan-tag/333/</resource-link>
 264    </result-data>
 265    <result-data>
 266       <resource-type>oam-network</resource-type>
 267       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/oam-networks/oam-network/examplentwk/</resource-link>
 268    </result-data>
 269    <result-data>
 270       <resource-type>cvlan-tag</resource-type>
 271       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/port-groups/port-group/exampleifc1/cvlan-tags/cvlan-tag/333/</resource-link>
 272    </result-data>
 273    <result-data>
 274       <resource-type>dvs-switch</resource-type>
 275       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/dvs-switches/dvs-switch/dvsswitch-id1/</resource-link>
 276    </result-data>
 277    <result-data>
 278       <resource-type>cvlan-tag</resource-type>
 279       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/port-groups/port-group/exampleifc1/cvlan-tags/cvlan-tag/111/</resource-link>
 280    </result-data>
 281    <result-data>
 282       <resource-type>customer</resource-type>
 283       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/globalexample/</resource-link>
 284    </result-data>
 285    <result-data>
 286       <resource-type>service-subscription</resource-type>
 287       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/globalexample/service-subscriptions/service-subscription/ptplgamma/</resource-link>
 288    </result-data>
 289    <result-data>
 290       <resource-type>port-group</resource-type>
 291       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/port-groups/port-group/exampleifc1/</resource-link>
 292    </result-data>
 293    <result-data>
 294       <resource-type>tenant</resource-type>
 295       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/tenants/tenant/examplepizzatenant/</resource-link>
 296    </result-data>
 297    <result-data>
 298       <resource-type>service-instance</resource-type>
 299       <resource-link>https://aai.onap:8443/aai/v16/business/customers/customer/globalexample/service-subscriptions/service-subscription/ptplgamma/service-instances/service-instance/arnoldave/</resource-link>
 300    </result-data>
 301    <result-data>
 302       <resource-type>pserver</resource-type>
 303       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/ptpnj101snd/</resource-link>
 304    </result-data>
 305    <result-data>
 306       <resource-type>availability-zone</resource-type>
 307       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/availability-zones/availability-zone/ptplaz1/</resource-link>
 308    </result-data>
 309    <result-data>
 310       <resource-type>vce</resource-type>
 311       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/</resource-link>
 312    </result-data>
 313    <result-data>
 314       <resource-type>image</resource-type>
 315       <resource-link>https://aai.onap:8443/aai/v1/cloud-infrastructure/images/image/valueOfImageId/</resource-link>
 316    </result-data>
 317    <result-data>
 318       <resource-type>cvlan-tag</resource-type>
 319       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/port-groups/port-group/exampleifc2/cvlan-tags/cvlan-tag/222/</resource-link>
 320    </result-data>
 321    <result-data>
 322       <resource-type>port-group</resource-type>
 323       <resource-link>https://aai.onap:8443/aai/v16/network/vces/vce/examplevce/port-groups/port-group/exampleifc2/</resource-link>
 324    </result-data>
 325    <result-data>
 326       <resource-type>ipaddress</resource-type>
 327       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/tenants/tenant/examplepizzatenant/vservers/vserver/ccwvm1/ipaddresses/ipaddress/10.10.10.5/guid of port or interface/</resource-link>
 328    </result-data>
 329    <result-data>
 330       <resource-type>flavor</resource-type>
 331       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/flavors/flavor/valueOfFlavorId/</resource-link>
 332    </result-data>
 333    <result-data>
 334       <resource-type>ipaddress</resource-type>
 335       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/tenants/tenant/examplepizzatenant/vservers/vserver/ccwvm1/ipaddresses/ipaddress/10.10.10.4/guid of port or interface/</resource-link>
 336    </result-data>
 337    <result-data>
 338       <resource-type>complex</resource-type>
 339       <resource-link>https://aai.onap:8443/aai/v16/cloud-infrastructure/complexes/complex/PTPLNJ08742/</resource-link>
 340    </result-data>
 341  </search-results>
 342
 343
 344