docs/AAI REST API Documentation/AAIRESTAPI_DUBLIN.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 \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
   8
   9 ==============
  10  AAI REST API
  11 ==============
  12
  13 Overview
  14 ========
  15
  16 The A&AI REST API provides access to the A&AI active inventory graph.
  17 The API is largely configured off of models and configuration files.
  18 Each vertex in the graph has an API that can be called separately or,
  19 if part of a tree structure, as a nested element with one or more
  20 generations (parent, grandparent, etc.).
  21
  22 The edges of the graph are provisioned using a relationship list
  23 construct.  For PUT methods, a relationship contains the vertex type
  24 or category (related-to) and a URI that provides the identity of the
  25 resource within A&AI.  The URI can be used with the server root to
  26 call A&AI to get more details of the related resource but cannot be
  27 cached for long periods.  (e.g., the version of the URI may get
  28 deprecated when the release changes).
  29
  30 The REST API describes each API that A&AI provides, independent of the
  31 caller of the API, therefore there is no information to be found here
  32 regarding the expectations on the callers.  That information is
  33 conveyed in AID documents for each client.  AIDs will describe the
  34 information expected from specific clients, but may not contain the
  35 full payloads that would be needed on an update.  Please see the
  36 concurrency notes referenced below in order to do the right kind of
  37 PUTs (GET, replace just what you are changing, PUT) or use the PATCH
  38 capability.
  39
  40 Deprecation Warnings and History
  41 ================================
  42
  43 AAI will maintain backwards compatibility for three prior releases.
  44 This means, with the introduction of v14 AAI will support **v11**
  45 (Amsterdam), **v13** (Beijing), **v14** (Casablanca), and **v16** (Dublin)
  46
  47 Dublin (v16)
  48 ------------
  49
  50 Clients can call the REST API with any valid path ending in /relationship-list to retrieve just the relationship-list for that object.
  51
  52 For example:
  53  - /network/generic-vnfs/generic-vnf/{vnf-id}/relationship-list
  54    returns just the relationship-list of relationships for that generic-vnf
  55  - /cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}/tenants/tenant/{tenant-id}/vservers/vserver/{vserver-name}/relationship-list
  56    returns just the relationship-list of relationships for that vserver
  57
  58 Custom Queries for replacing named queries are now available for clients to switch to.
  59
  60 Casablanca (v14)
  61 ----------------
  62
  63 - A new API called recents API is now available mostly intended for DCAE use.
  64
  65 - A new and improved bulk api interface is also available now.
  66
  67 - More details on the above APIs can be found in wiki pages referenced
  68   in sections below.
  69
  70 Beijing (v13)
  71 -------------
  72
  73 - To handle security vulnerabilities that were raised as part of Nexus
  74   IQ scans in ONAP, the APIs are being hosted on a spring-boot with
  75   Jetty web container.
  76
  77 - The deletion rules are now applied to all the nodes that will be
  78   deleted by the delete request.
  79
  80   For example, if the graph is:
  81
  82   +------+----------+
  83   |nodeA |   nodeD  |
  84   +------+----------+
  85
  86   If nodeA is parent of nodeB and nodeB is parent of nodeC
  87
  88   +------+---------------------+
  89   |nodeA | CASCADE_TO_CHILDREN |
  90   +------+---------------------+
  91   |nodeB | CASCADE_TO_CHILDREN |
  92   +------+---------------------+
  93   |nodeC | ERROR_IF_IN_EDGES   |
  94   +------+---------------------+
  95
  96 - If request is to delete nodeA, it would fail because nodeC has an in
  97   edge from a node not being deleted in this transaction.
  98
  99 - A configurable server timeout was implemented to make sure the AAI
 100   server did not continue processing the request long after a client
 101   times out on their side. An error code ERR.5.4.7406 will be returned
 102   when this limit is hit. A configuration for clients known to have
 103   longer running queries currently overrides the default value.
 104
 105 - To handle a risk identified by Fortify scans, a maxOccurs of 5000
 106   was added to the XSD.
 107
 108 API changes
 109 ~~~~~~~~~~~
 110
 111 - DELETE request will generate a DMAAP event for each node deleted
 112   (not just the for which the DELETE request was made)
 113
 114 - Relationship list
 115
 116     Starting with Casablanca, multiple edges can exist
 117     in the graph between the same 2 nodes. The REST API has been
 118     enhanced via changing the relationship-list so clients can specify
 119     which edge they are creating and differentiate multiple edges
 120     between the same 2 nodes. Backwards compatibility with older API
 121     versions that do notspecify the edge will be maintained.
 122
 123 - A new property “relationship-label” has been added that when
 124   specified will be used to create any new edge. If not specified the
 125   default edge label between the two nodes will be used. The
 126   relationship-label will always be returned with the v12 version of
 127   GETs whenever the relationship-list is returned.
 128
 129 .. code-block:: json
 130
 131    {
 132        "relationship-list": {
 133            "relationship": [
 134                {
 135                    "related-link": "/aai/v12/cloud-infrastructure/complexes/complex/6d8f945d-8bd2-4fa2-ad37-36b21fc8fb23-PS2418",
 136                    "related-to": "complex",
 137                    "relationship-data": [
 138                        {
 139                            "relationship-key": "complex.physical-location-id",
 140                            "relationship-value": "6d8f945d-8bd2-4fa2-ad37-36b21fc8fb23-PS2418"
 141                        }
 142                    ],
 143                    "relationship-label": "locatedIn"
 144                }
 145            ]
 146        }
 147    }
 148
 149 Amsterdam (v11)
 150 ---------------
 151
 152 API retirements:
 153
 154 -  The actions/update API will be retired. Clients must switch to PATCH.
 155    There is one grandfathered usage for vpe update flows which will be
 156    retired in v11.
 157
 158 -  The edge tag query will be retired.
 159
 160 Notable attribute and/or valid value changes (generally also impacts
 161 events):
 162
 163 -  The persona-model-id and persona-version will be replaced with
 164    model-invariant-id (same value as persona-model-id) and
 165    model-version-id (the UUID of the specific version of a model).
 166    Persona-model-customization-id will be replaced by
 167    model-customization-id.
 168
 169 -  The operational-state attribute will be replaced by
 170    operational-status and the only valid values will be in-service-path
 171    and out-of-service-path
 172
 173 -  The vpn-binding object will be split in two to reflect more than one
 174    route-target per binding. The route-target will be a child of
 175    vpn-binding and some attributes will move from vpn-binding to
 176    route-target.
 177
 178 -  The following license related attributes will be removed from
 179    generic-vnf: license-key, entitlement-assignment-group-uuid,
 180    entitlement-resource-uuid, license-assignment-group-uuid, and
 181    license-key-uuid due to the introduction of the entitlement and
 182    license children.
 183
 184 Event Specific:
 185
 186 -  Normal impacts due to renaming or adding attributes, splitting
 187    objects, etc. Please see swagger documentation for objects of
 188    interest.
 189
 190 -  In v11, clients that require lineage, children, or relationship
 191    information need to subscribe to a different DMaaP topic than the
 192    current one.
 193
 194 Relationship List
 195
 196 -  The related-link will be a URI and thus not contain
 197    https://{serverroot} (impacts events)
 198
 199 -  The related-link will be used on a PUT as the "first choice" to
 200    identify the related resource. The relationship-data structure, which
 201    contains the unordered set of keys, is still an acceptable way to
 202    relate two objects but, *if both the relationship-data and the
 203    related-link are passed, and they don't agree, the related-link will
 204    be used without warning that the data is inconsistent*.
 205
 206 -  The relationship-data will be ignored on PUT.
 207
 208 Future Warning
 209 ==============
 210
 211 In the future, the hope is that individual node definitions will be
 212 separately versioned from API behavior and from one another (e.g.,
 213 vserver hasn't changed in many releases and so doesn't need to have
 214 its "definition" version updated).
 215
 216 Because relationships are starting to become more complex, it may be
 217 necessary for AAI to expose to clients the exact relationship between
 218 two nodes.  This will likely be done with a relationship-type
 219 attribute of relationships in the relationship-list.
 220
 221 To support the concept of events getting generated on specific changed
 222 items, AAI will be migrating towards a model of asking clients to do
 223 the most granular PUTs possible rather than leveraging the nested
 224 elements of a tree structure.
 225
 226 The vce, port-group, cvlan-tag, newvce, vpe, oam-network, and
 227 dvs-switch objects will eventually be deprecated in favor of
 228 generic-vnf, l3-network, ctag-assignment, segmentation-assignment, and
 229 TBD.
 230
 231 L3-network will eventually be replaced by virtual-network.
 232
 233 How to Use this Document
 234 ========================
 235
 236 The only attributes in our objects that are declared required are
 237 those which we know will be present at the creation of each object and
 238 which are needed to support the construction of the AAI Graph. This
 239 does not imply that one of AAI's clients doesn't need data.
 240
 241 When you click on the API documentation, you will see the Summary of
 242 APIs broken down by namespace (e.g., cloud-infrastructure, business,
 243 network, service-design-and-creation). You can search for **Tag:**
 244 (matching the explicit case) to move from namespace to namespace through
 245 the Summary.
 246
 247 Search for **Paths** to skip past the Summary section where there will
 248 be more detail about each API. Query parameters are provided here, as
 249 well as links to our error codes.
 250
 251 Search for **Schema definitions** to see the definitions of the
 252 payloads. In your browser URL, you can type /#/definitions/node-name at
 253 the end of the html address to skip directly to a payload definition.
 254
 255 Note that the schema definitions now contain information about the
 256 delete scope of a node, edges, and some related node information.
 257 Given this information can now be generated, it is no longer repeated
 258 in this document.
 259
 260 Once AAI has a model and configured it, the AAI development server can
 261 be used to generate sample XML and JSON payloads, according to the
 262 Accept header passed in the request. This is done by calling the
 263 "plural" version of an API followed by the word example (e.g.,
 264 /vserver/vservers/example). This returns a GET result array with one
 265 entry. That single entry can be sent in a PUT request with actual data
 266 (the resource-id does not need to be in the PUT payload as it is on the
 267 URL).
 268
 269 Finally, custom queries that are not simple GETs of a resource must be
 270 identified to AAI as separate user stories.  This includes searching
 271 for a resource with other attributes on the same resource, as well as
 272 searching for resources based on their relationship with other
 273 objects.
 274
 275 AAI API Definition
 276 ==================
 277
 278 Namespaces
 279 ----------
 280
 281 Cloud Infrastructure Domain
 282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 283
 284 The Cloud Infrastructure domain (cloud-infrastructure) represents the
 285 assets managed within a cloud site.  This includes the complex, the
 286 physical servers, the availability zones, oam-networks, tenants, and
 287 vserver-related resources (vservers, flavors, images, etc.).
 288
 289 Tenants, oam-networks, availability-zones, volume-groups, images,
 290 flavors, and dvs-switches will have cloud-region as its parent node.
 291
 292 Network Domain
 293 ~~~~~~~~~~~~~~
 294
 295 The network namespace contains virtual and physical network resources
 296 as well as connection resources such as physical links, logical links,
 297 lag links, etc.
 298
 299 The vce/port-group/cvlan-tag tree represents an immature model that
 300 blended several resources together in ways that were expedient but
 301 which need to be re-evaluated.  A newvce object exists which was the
 302 basis of the generic-vnf object.  Future efforts will attempt to
 303 migrate vce and vpe into generic-vnf.
 304
 305 Business Domain
 306 ~~~~~~~~~~~~~~~
 307
 308 The business namespace captures customers, service-subscriptions, and
 309 service-instances.  This domain is immature and will be evolving as
 310 service design and creation starts to gel.
 311
 312 Customers and service-subscriptions in particular will be evolving
 313 soon.  Any service that is customer facing will see customer and
 314 service-subscription data offboarding to BSSs.  The
 315 service-instance-id will be the "join point" within the BSS to
 316 correlate the service-instance to the product and customer.  Services
 317 that are for infrastructure purposes will have a new entity, an
 318 owning-entity, to replace the customer.  The owning-entity will be
 319 related to the SDC service models that use it.
 320
 321 Service Design and Creation
 322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 323
 324 The service design and creation namespace captures data we invented
 325 based on what we thought SDC would eventually provide.  The structure
 326 of that data is definitely not what the current plans are for SDC
 327 however we need to at least capture the spirit of what's intended and
 328 communicate that across ONAP sub components that need it.
 329
 330 To date, there are only five containers:
 331
 332 1. Service-capabilities capture the pairings of service to
 333    resources. At the time of construction, the only data we had to
 334    denote service was the service-type from SO.  The vnf-type is the
 335    resource.
 336
 337 2. Service captures the service model instances and this will be
 338    deprecated in the future as things mature
 339
 340 3. Vnf-image captures information about the resource image needed for
 341    a VNF.  This was created due to there being no info available on
 342    the vservers that run on uCPE
 343
 344 4. Models captures model definitions (subgraph definitions using the
 345    AAI widgets)
 346
 347 5. named-queries capture subgraph definitions that allow different
 348    data to be retrieved for a given type of asset
 349
 350 Security
 351 --------
 352
 353 All REST APIs must be called using https.
 354
 355 HTTPS Basic Authentication will be used to authenticate clients.  The
 356 remote user from the HTTP Servlet Request is used against an AAI
 357 policy to see if the authenticated user is authorized for the resource
 358 and actions being request.
 359
 360 Client should use credentials provided to their system via AAF.
 361
 362 Headers
 363 -------
 364
 365 The following will be used for logging and interface diagnostic purposes.
 366
 367  * X-FromAppId  Unique Application ID assigned to the user of these APIs
 368  * X-TransactionId Unique ID that identifies an API request
 369
 370 The X-FromAppId will be assigned to each application by the AAI team.
 371 The X-TransactionId must be unique to each transaction within the
 372 context of an X-FromAppId.
 373
 374 SO, SDN-C, and AAI have agreed to use the Java UUID class to generate
 375 unique ids for X-TransactionId.
 376
 377 The Accept and Content-type header should be set to either
 378 application/json or application/xml except as documented for PATCH.
 379
 380 Response Codes and Error Handling
 381 ---------------------------------
 382
 383 AAI will use the following HTTP codes
 384
 385 HTTP Codes:
 386 ~~~~~~~~~~~
 387
 388 - 200 – Success
 389 - 201 – Created
 390 - 202 - Accepted
 391 - 204 – Success, no payload returned
 392 - 400 - Bad Request
 393 - 401 - Unauthorized
 394 - 403 - Forbidden
 395 - 404 - Not Found
 396 - 405 – Method Not Allowed
 397 - 409 - The request could not be completed due to a conflict with the
 398   current state of the target resource. This code is used in situations
 399   where the user might be able to resolve the conflict and resubmit the
 400   request. If the resource version doesn’t match AAI or a required
 401   resource version isn't sent but should have been
 402 - 410 - You are using a version of the API that has been retired
 403 - 412 – Precondition failed (If the resource version doesn’t match AAI or arequired resource version isn't sent but should have been
 404 - 415 – Unsupported Media Type
 405 - 500 - Internal Server Error
 406
 407 Successful PUT responses shall return the following codes:
 408  * 200 (OK): used when an existing resource has been modified and
 409    there is a response buffer
 410  * 201 (Created): MUST be used when a new resource is created
 411  * 202 (Accepted): used when AAI completed the action requested but
 412    may have taken other actions as well, which are returned in the
 413    response payload
 414  * 204 (No Content): used when the existing resource has been modified
 415    and there is no response buffer
 416
 417 Successful DELETE responses shall return the following codes:
 418  * 200 (OK): for a successful response if the response includes an
 419    entity describing the status.
 420  * 204 (No Content): if the action has been enacted but the response
 421    does not include an entity.
 422
 423 Successful GET responses shall return the following codes:
 424  * 200 (OK): for a successful response for a resource that has been found
 425  * 404 (Not Found) for a successful response retrieving a list of
 426    items and there were no items found, i.e., the GET of the specific
 427    plural resource was not found
 428  * 404 (Not Found): when a specific resource was not found
 429
 430 Failures:
 431  * 400 Bad Request will be returned if headers are missing
 432  * 404 Not Found will be returned if an unknown URL is used
 433
 434 In addition, the standard response buffer will be structured as follows unless otherwise specified.
 435 There are two types of requestErrors.
 436
 437  * Service Exceptions – These exceptions occur when a service is
 438    unable to process a request and retrying the request will result in
 439    a consistent failure (e.g., an application provides invalid input).
 440  * Policy Exceptions – These exceptions occur when a policy criteria
 441    has not been met (e.g., the (N+1)th request arrives when an
 442    application’s service level agreement only allows N transactions
 443    per time interval).
 444
 445 Italics are specific to the error returned, and generally described in the notes
 446
 447 .. parsed-literal::
 448
 449   HTTP/1.1 405 *Method Not Allowed*
 450   Content-Type: application/json
 451   Content-Length: nnnnn
 452   Date: *Thu, 04 Jun 2009 02:51:59 GMT*
 453   {
 454      “requestError”:{
 455        “policyException”:{
 456        “messageId”:"*POL8007*",
 457        “text”:”*The resource was invoked with an unsupported operation: %1.*”,
 458        “variables”: [”*PUT*”]
 459      }
 460   }
 461
 462 Notes:
 463
 464 a. On the first line, substitute the appropriate status response code.
 465
 466 b. On the second line, substitute the appropriate content type.
 467
 468 c. Express the requestError structure in the required content type (e.g., either JSON or XML).   AAI will use JSON.
 469
 470 d. ‘requestError’ contains either a ‘policyException’ or a ‘serviceException’ structure.
 471
 472 e. url is optional
 473
 474 In 1512, AAI is introducing a response payload that is possible during a successful PUT.  This payload is used to inform the client that, while AAI completed the action requested, the result could be interpreted as a warning or request for additional action, as negotiated with the client.
 475
 476 Sample response to a vserver PUT where the pserver and complex did not exist:
 477
 478 .. code-block:: json
 479
 480  {"responseMessages": {"responseMessage": [
 481       {
 482       "messageId": "INF0003",
 483       "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
 484       "variables": {"variable":       [
 485          "PUTvserver",
 486          "ccwvm388",
 487          "complex",
 488          "physical-location-id=fakeccwcomplex",
 489          "Added prerequisite object to db:complex",
 490          "0.3.0004"
 491       ]}
 492   },
 493       {
 494       "messageId": "INF0003",
 495       "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
 496       "variables": {"variable":       [
 497          "PUTvserver",
 498          "ccwvm388",
 499          "pserver",
 500          "hostname=fakeccwpserver",
 501          "Added prerequisite object to db:pserver",
 502          "0.3.0004"
 503       ]}
 504    }
 505  ]}}
 506
 507 Referential Integrity
 508 ---------------------
 509
 510 AAI is primarily a view to the relationships between instances of
 511 services, physical and virtual components, etc.  It stores just the
 512 details it needs to be efficient to its tasks and knows how to get
 513 more details if needed.
 514
 515 As such, a transaction sent to AAI may be refused if would break
 516 referential integrity.  The referential integrity rules of AAI are
 517 still evolving as we understand the services and customers that will
 518 use us.
 519
 520 AAI uses a graph database on a NoSQL data store. The following are
 521 true for AAI:
 522
 523 * Some vertices are exposed to the outside world through APIs, others
 524   are internal to how we store the data (i.e., it may look like one
 525   resource to our customers but it is expressed as more than one
 526   vertex in our graph)
 527
 528 * Vertices that are internal to AAI will be deleted when the parent
 529   vertex is deleted, if deletion of the parent leaves the child vertex
 530   orphaned
 531
 532 * Vertices that are exposed need to be managed using specific rules
 533   for each vertex.
 534
 535 * Vertices may have more than just parent/child relationships.  One
 536   example is a vserver, which will be owned by a tenant and used by a
 537   VNF.
 538
 539
 540 URLs Sent To and Retrieved From A&AI
 541 ------------------------------------
 542
 543 A&AI receives URLs from clients that point back to that client in
 544 order to get more details about the data sent to A&AI.  A&AI expects
 545 the URLs sent by clients (e.g., self links) to be URL encoded
 546 (UTF-8) and A&AI will store them unchanged.
 547
 548 URIs that A&AI constructs that point to A&AI resources will be
 549 returned URLEncoded (UTF-8) to clients.  This affects URIs in
 550 relationship lists and search results.  Note that A&AI used to send
 551 URLs but, as reported in the 1707 impacts, these will now be URIs.
 552
 553 A&AI expects space to be %20, and not plus(+).
 554
 555 The Relationship-List
 556 ---------------------
 557
 558 The REST interface does not lend itself to creating more than
 559 parent-child relationships and the backend structure of AAI is a
 560 graph.  A goal of AAI, and shared with ONAP, is to do as little coding
 561 as possible to introduce a new service into the service design and
 562 creation environment.
 563
 564 To that end, we've introduced a relationship-list structure.  AAI will
 565 ask its clients to provide certain data in the relationship-list
 566 structure.
 567
 568 Each relationship has a related-to attribute and a list of key/value
 569 pairs.  The related-to attribute identifies the node type that the
 570 resource being acted on is to be related to using the data in the
 571 key/value pairs.  AAI will encode a set of rules for each resource
 572 type to verify that only valid edges are being made.  AAI will keep
 573 the directionality and cardinality, and the edge attributes within its
 574 own logic.  In the near future, the definition of relationships, their
 575 validity, and cardinality will be captured in the ONAP TOSCA models.
 576
 577 AAI also has a concept of a related-to category.  To date, the only
 578 category is vnf.  The vnf category is used as the related-to value to
 579 indicate that the relationship being establish is to a Virtual Network
 580 Function of unknown type.  The vnf-id happens to be unique for all
 581 services across all nodes in the graph.  By providing vnf.vnf-id with
 582 a specific value, AAI can look at all VNFs in the graph and find the
 583 appropriate vertex.  Note that this only applies to PUTs.
 584
 585 Category vnf is used for node types of vce, vpe, and generic-vnf.
 586
 587 If an attempt is made to add a relationship to a node that doesn't
 588 exist (e.g., from a vserver to a vnf, and the vnf doesn't exist), a
 589 unique message Id (3003) will be returned with a specific error code
 590 (ERR.5.4.6129).  Arguments will tell the client which node type was
 591 missing (e.g., vnf) and the key data for that node type (vnf.vnf-id).
 592
 593 Single relationships can be PUT to the graph in the following way:
 594
 595 .. code::
 596
 597  https://{serverRoot}/{namespace}/{resource}/relationship-list/relationship
 598
 599 or
 600
 601 .. code::
 602
 603  https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/pserver-123456789-01/p-interfaces/p-interface/p-interface-name-123456789-01/l-interfaces/l-interface/l-interface-name-123456789-01/relationship-list/relationship
 604
 605 with a payload containing the relationship information.
 606
 607 AAI will accept and give preference to the related-link URI
 608
 609 XML
 610
 611 .. code-block:: xml
 612
 613    <relationship xmlns="http://org.onap.aai.inventory/vX">
 614      <related-link>*/aai/v16/network/logical-links/logical-link/logical-link-123456789-01*</related-link>
 615      <related-to>logical-link</related-to>
 616      <relationship-data>
 617        <relationship-key>logical-link.link-name</relationship-key>
 618        <relationship-value>logical-link-123456789-01</relationship-value>
 619      </relationship-data>
 620    </relationship>
 621
 622 JSON
 623
 624 .. code-block:: json
 625
 626    {
 627        "related-link": " /aai/v16/network/logical-links/logical-link/logical-link-123456789-01",
 628        "related-to": "logical-link",
 629        "relationship-data": [
 630            {
 631                "relationship-key": "logical-link.link-name",
 632                "relationship-value": " logical-link-123456789-01"
 633            }
 634        ]
 635    }
 636
 637 Health Check API
 638 ----------------
 639
 640 The util domain is where AAI locates utility functions.  There is
 641 currently one utility function, echo, which serves as a ping test that
 642 authenticated authorized clients can call to ensure there is
 643 connectivity with AAI.
 644
 645 The URL for the echo utility is:
 646
 647 .. code::
 648
 649    https://aai.onap:8443/aai/util/echo
 650
 651 If the response is unsuccessful, an error will be returned following
 652 the standard format.
 653
 654 The successful payload returns the X-FromAppId and X-TransactionId
 655 sent by the client.
 656
 657 Successful XML Response Payload
 658 -------------------------------
 659
 660 .. code-block:: xml
 661
 662    <Info>
 663       <responseMessages>
 664          <responseMessage>
 665             <messageId>INF0001</messageId>
 666             <text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text>
 667             <variables>
 668                <variable>CCW</variable>
 669                <variable>CCW33335</variable>
 670                <variable>Successful health check:OK</variable>
 671                <variable>0.0.0002</variable>
 672             </variables>
 673          </responseMessage>
 674       </responseMessages>
 675    </Info>
 676
 677 Successful JSON Response Payload
 678 --------------------------------
 679
 680 .. code-block:: json
 681
 682    {
 683        "responseMessages": {
 684            "responseMessage": [
 685                {
 686                    "messageId": "INF0001",
 687                    "text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)",
 688                    "variables": {
 689                        "variable": [
 690                            "CCW",
 691                            "CCW33335",
 692                            "Successful health check:OK",
 693                            "0.0.0002"
 694                        ]
 695                    }
 696                }
 697            ]
 698        }
 699    }
 700
 701 AAI Resources CRUD APIs
 702 =======================
 703
 704 The API structure is composed of:
 705
 706   * The HTTP command, which indicates the operation to perform
 707   * The HTTP URI, which defines what object this operation is related to
 708   * The HTTP version, which MUST be 1.1
 709
 710 Available HTTP commands are:
 711
 712   * PUT: used to create or update an object
 713   * DELETE: used to delete an object or a set of objects
 714   * GET : used to query an object or set of objects
 715   * PATCH :  used to update specific fields owned by the client doing the update
 716
 717 The HTTP URI is built according to this pattern:
 718
 719 .. code::
 720
 721    https://{serverRoot}/{namespace}/{resource}
 722
 723 * {serverRoot} refers to the server base url: hostname+port+base path+version. Port and base path are OPTIONAL but AAI will use port 8443 and base path aai. Note that the base path may change before production, so please make this configurable. Versions will change as releases are made.
 724
 725 * {namespace} refers to the API namespace. Supported namespaces are cloud-infrastructure, business, service-design-and-creation, and network
 726
 727 * {resource} refers to how the object is identified according to the namespace specifications.
 728
 729 Example GET Request
 730
 731 .. code::
 732
 733    GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}
 734
 735 Swagger and XSD:
 736 ----------------
 737
 738 `Offered APIs <../platform/offeredapis.html>`_
 739
 740 Data Assumptions
 741 ----------------
 742
 743 Given AAI is largely a correlation engine among disparate inventory
 744 types, AAI will for the most part accept values as they are sent,
 745 without validating the format or value of the input.  **It is
 746 incumbent upon the source of truth to provide valid information to
 747 AAI.**
 748
 749 Clients should either use the PATCH API to only change
 750 the attribute values they mean to change, or do a GET prior to a PUT
 751 and change only the data that they mean to affect.
 752
 753 The PUT REST APIs expect the payload passed to replace the resource in
 754 AAI.  **A GET before PUT is vital in our concurrency scheme.  The
 755 client will be returned an opaque value per entity which needs to be
 756 returned back in the PUT. AAI will reject the PUT or DELETE if the
 757 opaque value doesn't match what AAI has stored for that entity.**
 758
 759 If an attribute has been added to a model in vN+1, and a GET/PUT of a
 760 vN resource is done, AAI should not affect the new attribute (i.e., it
 761 should be left unchanged).
 762
 763 Concurrency Control
 764 -------------------
 765
 766 Concurrency control for AAI is in place.
 767
 768 * A client always gets a resource before updating through PUT or deleting it.
 769
 770 * All resource updates and deletions are done via the AAI REST APIs
 771
 772 * This solution will apply to PUT and DELETE operations.
 773
 774 * The resource-version attribute is now in every container
 775
 776 * The PATCH REST verb is not subject to concurrency control, because
 777   it is only intended to be used by clients who are the definitive
 778   source of truth for the attributes they are changing.  An update
 779   through the PATCH API will however reset the resource-version so
 780   clients using PUT and DELETE will not risk updating with stale data.
 781   If a client would like us to do concurrency control for PATCH, we
 782   will need a feature request.  PATCH is recommended for clients who
 783   know they are the definitive source of data, as there is less risk
 784   of destroying other data.
 785
 786 If you use PUT, you MUST send back the entire resource, not just the
 787 pieces you know about.  This is best illustrated by example.  Note:
 788 Specific interfaces only show you the data you are responsible for but
 789 that does not mean that's all the data that the resource you GET will
 790 contain.  You are responsible to overlay only your changes and leave
 791 everything else untouched.
 792
 793 Imagine this is the existing resource:
 794
 795 .. code-block:: json
 796
 797    {
 798        "node-id": "valueOfNodeId",
 799        "node-name": "valueOfNodeName",
 800        "prov-status": "NVTPROV",
 801        "relationship-list": {
 802            "relationship": [
 803                {
 804                    "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
 805                    "related-to": "generic-vnf",
 806                    "relationship-data": [
 807                        {
 808                            "relationship-key": "generic-vnf.vnf-id",
 809                            "relationship-value": "generic-vnf-20160902a"
 810                        }
 811                    ]
 812                },
 813                {
 814                    "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
 815                    "related-to": "generic-vnf",
 816                    "relationship-data": [
 817                        {
 818                            "relationship-key": "generic-vnf.vnf-id",
 819                            "relationship-value": "generic-vnf-20161010"
 820                        }
 821                    ]
 822                }
 823            ]
 824        },
 825        "resource-version": "1474912794"
 826    }
 827
 828 And you want to update the name and add a relationship to an l3-network.
 829
 830 The payload you need to send back, if you choose PUT, is this.  The
 831 node-name and the third relationship block is the new data, and the
 832 other data and relationships previously existed and must still be PUT.
 833
 834 .. code-block:: json
 835
 836    {
 837        "node-id": "valueOfNodeId",
 838        "node-name": "NEWvalueOfNodeName",
 839        "prov-status": "NVTPROV",
 840        "relationship-list": {
 841            "relationship": [
 842                {
 843                    "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
 844                    "related-to": "generic-vnf",
 845                    "relationship-data": [
 846                        {
 847                            "relationship-key": "generic-vnf.vnf-id",
 848                            "relationship-value": "generic-vnf-20160902a"
 849                        }
 850                    ]
 851                },
 852                {
 853                    "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
 854                    "related-to": "generic-vnf",
 855                    "relationship-data": [
 856                        {
 857                            "relationship-key": "generic-vnf.vnf-id",
 858                            "relationship-value": "generic-vnf-20161010"
 859                        }
 860                    ]
 861                },
 862                {
 863                    "related-link": " /aai/v16/network/l3-networks/l3-network/network-name-for-me",
 864                    "related-to": "l3-network",
 865                    "relationship-data": [
 866                        {
 867                            "relationship-key": "l3-network.network-name",
 868                            "relationship-value": "network-name-for-me"
 869                        }
 870                    ]
 871                }
 872            ]
 873        },
 874        "resource-version": "1474912794"
 875    }
 876
 877 A Warning About PUT and Lists
 878 -----------------------------
 879
 880 The PUT verb is used to both create and replace a resource.  A given
 881 resource may have child resources (e.g., customers have service
 882 subscriptions, generic-vnfs have vf-modules, tenants have vservers and
 883 vservers have volumes).
 884
 885 The following convention will be followed:
 886
 887   If a resource is replaced and there are no tags for children, the
 888   children that exist will be left alone.
 889
 890   If a resource is replaced and there are tags for children, the
 891   children will be replaced by the list passed.  If the list is empty,
 892   then children will be deleted.
 893
 894 Note that the relationship list is a type of child resource.  The same
 895 conventions are followed.  It is especially critical to ensure that
 896 you do not send an incomplete relationship list and therefore remove
 897 edges in the graph.  See `The Relationship-List`_ for more information on
 898 relationship lists.  See `Concurrency Control`_ for an example of GET followed by
 899 PUT containing the entire resource (i.e., overlaying your changes on
 900 what already exists so that you don't wipe out other data).
 901
 902 PATCH
 903 -----
 904
 905 To move towards industry standards and to make our APIs easier to use
 906 by clients who own specific attributes and do not require AAI to
 907 enforce concurrency control around them, the PATCH verb has been
 908 introduced.
 909
 910 .. _RFC 7386: https://tools.ietf.org/html/rfc7386
 911
 912 - RFC Algorithm implemented JSON Merge PATCH: `RFC 7386`_
 913 - HTTP Verb = PATCH
 914 - Clients can send a POST with "X-HTTP-Method-Override" = "PATCH" and
 915   Content-Type = "application/merge-patch+json" to send a PATCH
 916   request to AAI.
 917 - PATCH does not support XML
 918 - PATCH does not require a resource version to perform these modifications
 919 - Clients should only send what they wish to modify and whose value they "own"
 920 - PATCH returns a 200 with no response body for success
 921
 922 Example:
 923
 924 .. code::
 925
 926    PATCH  https://aai.onap:8443/aai/v16/network/generic-vnfs/generic-vnf/cscf0001v
 927    {
 928       "vnf-id": "cscf0001v", <-- This key needs to be here but you cannot modify the key
 929       "regional-resource-zone": null,
 930       "ipv4-oam-address": "10.10.99.11"
 931    }
 932
 933 This payload would result in the generic-vnf with the vnf-id =
 934 cscf0001v having ipv4-oam-address set to "10.10.99.11" and
 935 regional-resource-zone having its value removed from the database.
 936
 937 Note: PATCH is used only to update attributes on a single node that
 938 already exists in AAI.  That means it is not applicable to lists of
 939 any type.
 940
 941  * You do not manage relationships with PATCH.  There is a
 942    relationship API for that.
 943
 944  * You cannot include child objects in a PATCH payload, i.e., you
 945    cannot PATCH an l3-network's attributes as well as supply some
 946    subnet children or their attributes within the same PATCH payload.
 947    You can GET/overlay/PUT parent/child payloads or you can PUT or
 948    PATCH each object individually with separate REST API calls.
 949
 950 Optional Query Parameters
 951 -------------------------
 952
 953 A **depth** query parameter is available allowing a query to stop after it
 954 has reached a certain point in the graph.  This allows clients to
 955 minimize the data that is returned to them and make the queries more
 956 performant. A depth=0 will return information of the node referred to
 957 by the URI only without any information on the children.
 958
 959 Example
 960
 961 .. code::
 962
 963    GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0
 964
 965 A **nodes-only** parameter is available allowing a query to only
 966 display the properties of the nodes being queried without any
 967 relationship information. This allows clients to minimize data that is
 968 returned to them and make the queries more performant.
 969
 970 Example
 971
 972 .. code::
 973
 974    GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?nodes-only
 975
 976 These parameters may be used in combination with each other.
 977
 978 Example
 979
 980 .. code::
 981
 982    GET https://aai.onap:8443/aai/v14/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0&nodes-only
 983
 984 Delete Scope and Edges
 985 ----------------------
 986
 987 An attempt to remove a node which would result in a delete scope being
 988 violated will return error 5.4.6110.
 989
 990 The swagger documentation has been updated to show information about
 991 delete scope and edges.
 992
 993 Here is a subset of the generic-vnf definition that will be used to
 994 demonstrate how the delete scope and edges are documented.
 995
 996 The following table summarizes actions AAI will take upon deletion of a resource, i.e., its default delete scope:
 997
 998 +-----------------------------+--------------------------------------------------------------------+
 999 | ERROR_IF_ANY_EDGES          | If the resource being deleted has any edges at all                 |
1000 |                             | an error should be returned                                        |
1001 +-----------------------------+--------------------------------------------------------------------+
1002 | ERROR_IF_ANY_IN_EDGES       | If the resource being deleted has any edges that point IN towards  |
1003 |                             | it, an error should be returned                                    |
1004 +-----------------------------+--------------------------------------------------------------------+
1005 | THIS_NODE_ONLY              | Delete the vertex being requested by first deleting its edge to    |
1006 |                             | other vertices, but do not delete the other vertices.  Note, the   |
1007 |                             | delete will be rejected if the deletion target has DEPENDENT       |
1008 |                             | children (e.g., tenants that have vservers)                        |
1009 +-----------------------------+--------------------------------------------------------------------+
1010 | CASCADE_TO_CHILDREN         | Cascade the delete through vertices who have a parentOf            |
1011 |                             | relationship to the vertex being deleted, as long as the vertex is |
1012 |                             | orphaned by the delete of its parent                               |
1013 +-----------------------------+--------------------------------------------------------------------+
1014 | ERROR_4_IN_EDGES_OR_CASCADE | Error if there are any in edges and, if not, cascade to            |
1015 |                             | children                                                           |
1016 +-----------------------------+--------------------------------------------------------------------+
1017
1018 Edge Documentation
1019
1020 * Node A is the object being defined - e.g.,  generic-vnf
1021
1022 * Node B is the XXX of OUT TO XXX
1023
1024 * Direction is always Node A OUT TO Node B.  Node A has requirement
1025   satisfied by Node B and the relationship is the edgelabel
1026
1027 * Multiplicity is listed on the OUT TO edges
1028
1029 * The former hasDelTarget is indicated by deletion statements that
1030   make it clear what gets deleted as a side effect of deleting
1031   something else.
1032
1033 * The former isChild is indicated by full statements
1034
1035
1036 .. parsed-literal::
1037
1038  *generic-vnf: object*
1039  *General purpose VNF*
1040
1041  *Default Delete Scope*
1042
1043  CASCADE_TO_CHILDREN
1044
1045   * *OUT TO vnfc (org.onap.relationships.inventory.Uses, One2Many, delete of generic-vnf will delete vnfc)*
1046   * *IN FROM l-interface (l-interface child of generic-vnf)*
1047   * *IN FROM service-instance*
1048
1049 Server Timeout
1050 --------------
1051
1052 A Server timeout is implemented for these APIs to make sure the server
1053 did not continue processing the request long after a client times out
1054 on their side. An error code ERR.5.4.7406 will be returned when this
1055 limit is hit. The default value for Resources API is 60 secs. The
1056 clients should set their timeouts accordingly.
1057
1058 Bulk APIs
1059 ---------
1060
1061 The Bulk API allows clients to make multiple requests in a single
1062 transaction. Please look for additional details on the following wiki
1063 page: `Bulk API <bulkApi.html>`_
1064
1065 AAI Traversal APIs
1066 ==================
1067
1068 Not all queries of the graph are purely GETs of a specific resource
1069 and its related vertexes.  The following capabilities are available to
1070 meet more advanced search needs.  Please contact the AAI team if you
1071 need another search.
1072
1073 Nodes Query
1074 -----------
1075
1076 The Nodes Query mechanism was implemented in support of searching the
1077 pservers which do not have the ipv4-oam-ipaddress set.  It will allow
1078 nodes to be searched based on certain properties of the nodes. It will
1079 allow search based on properties being set, not set or set to specific
1080 values.
1081
1082 Please reference `Nodes Query <nodesQuery.html>`_ for details on the
1083 API and test queries.
1084
1085 Nodes API
1086 ---------
1087
1088 In working with A&AI's standard REST API, you may have noticed that
1089 certain API paths have a hierarchy to them and require a client to
1090 know multiple object keys to preform GETs. For example: the vserver
1091 object is under tenant, which is itself under cloud-region. If you
1092 wanted to look up a vserver by name, you would still need to know the
1093 tenant-id and cloud-region-id (and cloud-owner) in order to
1094 successfully perform that GET. The nodes API allows for more freedom
1095 in querying A&AI, allowing clients to circumvent the need to know
1096 every key in the hierarchy.
1097
1098 See `Nodes Query <nodesQuery.html>`_ for more information.
1099
1100 Generic Queries
1101 ---------------
1102
1103 The Generic Query mechanism allows to search for certain nodes of
1104 “include” node types at a specified “depth” from the from a particular
1105 start node of type “start-node-type” identified by specifying its
1106 “key” values
1107
1108
1109
1110 Model Based Query and Delete
1111 ----------------------------
1112
1113 AAI supports a search and delete capability that allows a client to
1114 retrieve or delete an instance of a service based on the model
1115 subgraph definition provided to AAI by ASDC.
1116
1117 The instance filters must uniquely identify a service instance.
1118
1119 The URL is as follows:
1120
1121 .. code::
1122
1123    https://{serverRoot}/aai/search/model[?action=DELETE]
1124
1125 .. code-block:: json
1126
1127    {
1128        "query-parameters": {
1129            "model": {
1130                "model-invariant-id": "$modelInvariantId",
1131                "model-vers": {
1132                    "model-ver": [
1133                        {
1134                            "model-version-id": "$modelVersionId"
1135                        }
1136                    ]
1137                }
1138            },
1139            "instance-filters": {
1140                "instance-filter": [
1141                    {
1142                        "customer": {
1143                            "global-customer-id": "$globalCustID"
1144                        },
1145                        "service-instance": {
1146                            "resource-version": "$resourceversionID",
1147                            "service-instance-id": "$serviceInstanceID"
1148                        },
1149                        "service-subscription": {
1150                            "service-type": "$serviceType"
1151                        }
1152                    }
1153                ]
1154            }
1155        }
1156    }
1157
1158 Named Query
1159 -----------
1160
1161 These queries provide the ability to upload a json file describing the
1162 inputs and designed output based on traversing the graph in a
1163 particular way. Existing named queries are supported but will be
1164 migrated to custom queries. **Named queries will be deprecated (no new
1165 queries, just support for existing ones) in Dublin and clients will be
1166 asked to migrate to use the custom queries instead.**
1167
1168 Custom Query
1169 ------------
1170
1171 This API provides AAI clients an API for complex data retrieval. To
1172 execute a custom query, a client will perform an HTTP PUT request on
1173 the query API and include a payload indicating the starting node and
1174 the query to be run. While the client is performing a PUT request,
1175 this is actually a data query and no data is created or changed.
1176
1177 Assumptions
1178 ~~~~~~~~~~~
1179
1180 +----------+-----------------------------+--------------------------+
1181 | No.      | Assumption                  | Approach                 |
1182 +==========+=============================+==========================+
1183 | 1        | Assume that client will     |                          |
1184 |          | not request large amounts   |                          |
1185 |          | of data from AAI w/out      |                          |
1186 |          | using secondary filters     |                          |
1187 +----------+-----------------------------+--------------------------+
1188
1189 Depdendencies
1190 ~~~~~~~~~~~~~
1191
1192 Data has been PUT to AAI prior to the query.
1193
1194 Custom Query URI
1195 ~~~~~~~~~~~~~~~~
1196
1197 .. code::
1198
1199    PUT /aai/v$/query?format={format}
1200
1201 Query Formats
1202 ~~~~~~~~~~~~~
1203
1204 The format determines what information is returned from the
1205 query. Acceptable formats are: count, id, pathed, resource,
1206 resource_and_url, or simple.
1207
1208 count
1209 ^^^^^
1210
1211 Provides an count of the objects returned in the query.
1212
1213 .. code::
1214
1215    PUT /aai/v$/query?format=count
1216
1217 Example reponse
1218
1219 .. code-block:: json
1220
1221    {
1222      "results": [
1223        {
1224          "pnf": 4,
1225          "p-interface": 5,
1226          "l-interface": 3,
1227          "pserver": 1
1228        }
1229      ]
1230    }
1231
1232 id
1233 ^^^
1234
1235 Provides an array of objects containing resource-type (AAI's node
1236 type; i.e., pnf) and a URI using the vertex ID from AAI's graph.
1237
1238 .. code::
1239
1240    PUT /aai/v$/query?format=id
1241
1242 Example Response
1243
1244 .. code-block:: json
1245
1246    {
1247      "results": [
1248        {
1249          "resource-type": "complex",
1250          "resource-link": "/aai/v1/resources/id/8159312"
1251        },
1252        {
1253          "resource-type": "complex",
1254          "resource-link": "/aai/v1/resources/id/389256"
1255        }
1256      ]
1257    }
1258
1259 pathed
1260 ^^^^^^
1261
1262 Provides an array of objects containing resource-type (AAIs node type;
1263 i.e., pnf) and a URI using the AAI REST API pathed URIs
1264
1265 .. code::
1266
1267    PUT /aai/v$/query?format=pathed
1268
1269 Example Response
1270
1271 .. code-block:: json
1272
1273    {
1274      "results": [
1275        {
1276          "resource-type": "complex",
1277          "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1278        },
1279        {
1280          "resource-type": "complex",
1281          "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1282        }
1283      ]
1284    }
1285
1286 resource
1287 ^^^^^^^^
1288
1289 Provides each object in the results array in the same format as AAI's
1290 REST API with depth = 1 (first level children and cousin
1291 relationships).
1292
1293 .. code::
1294
1295    PUT /aai/v$/query?format=resource
1296
1297
1298 Example Response
1299
1300 .. code-block:: json
1301
1302    {
1303        "results": [
1304            {
1305                "complex": {
1306                    "city": "Anywhere",
1307                    "complex-name": "complex-mccomplexface",
1308                    "country": "USA",
1309                    "data-center-code": "CHG",
1310                    "latitude": "30.123456",
1311                    "longitude": "-78.135344",
1312                    "physical-location-id": "complextest1",
1313                    "physical-location-type": "lab",
1314                    "postal-code": "90210",
1315                    "region": "West",
1316                    "relationship-list": {
1317                        "relationship": [
1318                            {
1319                                "related-link": "/aai/v1/network/zones/zone/zone1",
1320                                "related-to": "zone",
1321                                "related-to-property": [
1322                                    {
1323                                        "property-key": "zone.zone-name",
1324                                        "property-value": "zone-name1"
1325                                    }
1326                                ],
1327                                "relationship-data": [
1328                                    {
1329                                        "relationship-key": "zone.zone-id",
1330                                        "relationship-value": "zone1"
1331                                    }
1332                                ],
1333                                "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1334                            },
1335                            {
1336                                "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1337                                "related-to": "cloud-region",
1338                                "related-to-property": [
1339                                    {
1340                                        "property-key": "cloud-region.owner-defined-type"
1341                                    }
1342                                ],
1343                                "relationship-data": [
1344                                    {
1345                                        "relationship-key": "cloud-region.cloud-owner",
1346                                        "relationship-value": "Cloud-Region"
1347                                    },
1348                                    {
1349                                        "relationship-key": "cloud-region.cloud-region-id",
1350                                        "relationship-value": "Region1"
1351                                    }
1352                                ],
1353                                "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1354                            }
1355                        ]
1356                    },
1357                    "resource-version": "1531233769164",
1358                    "state": "CA",
1359                    "street1": "100 Main St",
1360                    "street2": "C3-3W03"
1361                }
1362            }
1363        ]
1364    }
1365
1366 resource_and_uri
1367 ^^^^^^^^^^^^^^^^
1368
1369 Provides each object in the results array in the same format as AAI’s
1370 REST API with depth = 1 (first level children and cousin
1371 relationships) plus the pathed url for the result object in AAI.
1372
1373 .. code::
1374
1375    PUT /aai/v$/query?format=resource_and_url
1376
1377 Example Response
1378
1379 .. code-block:: json
1380
1381   {
1382       "results": [
1383           {
1384               "complex": {
1385                   "city": "Anywhere",
1386                   "complex-name": "complex-mccomplexface",
1387                   "country": "USA",
1388                   "data-center-code": "CHG",
1389                   "latitude": "30.123456",
1390                   "longitude": "-78.135344",
1391                   "physical-location-id": "complextest1",
1392                   "physical-location-type": "lab",
1393                   "postal-code": "90210",
1394                   "region": "West",
1395                   "relationship-list": {
1396                       "relationship": [
1397                           {
1398                               "related-link": "/aai/v16/network/zones/zone/zone1",
1399                               "related-to": "zone",
1400                               "related-to-property": [
1401                                   {
1402                                       "property-key": "zone.zone-name",
1403                                       "property-value": "zone-name1"
1404                                   }
1405                               ],
1406                               "relationship-data": [
1407                                   {
1408                                       "relationship-key": "zone.zone-id",
1409                                       "relationship-value": "zone1"
1410                                   }
1411                               ],
1412                               "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1413                           },
1414                           {
1415                               "related-link": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1416                               "related-to": "cloud-region",
1417                               "related-to-property": [
1418                                   {
1419                                       "property-key": "cloud-region.owner-defined-type"
1420                                   }
1421                               ],
1422                               "relationship-data": [
1423                                   {
1424                                       "relationship-key": "cloud-region.cloud-owner",
1425                                       "relationship-value": "Cloud-REgion"
1426                                   },
1427                                   {
1428                                       "relationship-key": "cloud-region.cloud-region-id",
1429                                       "relationship-value": "Region1"
1430                                   }
1431                               ],
1432                               "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1433                           }
1434                       ]
1435                   },
1436                   "resource-version": "1531233769164",
1437                   "state": "CA",
1438                   "street1": "100 Main St",
1439                   "street2": "C3-3W03"
1440               },
1441               "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1"
1442           }
1443       ]
1444   }
1445
1446 simple
1447 ^^^^^^
1448
1449 Provides each result object in a simplified format. The node-type,
1450 graph vertex id, pathed url, object properties, and directly related
1451 objects in the graph are all returned. Both direct parent/child
1452 objects and cousin objects are included in the related-to array.
1453
1454 .. code::
1455
1456    PUT /aai/v$/query?format=simple
1457
1458 Example Response
1459
1460 .. code-block:: json
1461
1462    {
1463        "results": [
1464            {
1465                "id": "81924184",
1466                "node-type": "complex",
1467                "properties": {
1468                    "city": "Anywhere",
1469                    "complex-name": "complex-mccomplexface",
1470                    "country": "USA",
1471                    "data-center-code": "CHG",
1472                    "latitude": "30.123456",
1473                    "longitude": "-78.135344",
1474                    "physical-location-id": "complextest1",
1475                    "physical-location-type": "lab",
1476                    "postal-code": "90210",
1477                    "region": "West",
1478                    "resource-version": "1531233769164",
1479                    "state": "CA",
1480                    "street1": "100 Main St",
1481                    "street2": "C3-3W03"
1482                },
1483                "related-to": [
1484                    {
1485                        "id": "40968400",
1486                        "node-type": "zone",
1487                        "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1488                        "url": "/aai/v16/network/zones/zone/zone1"
1489                    },
1490                    {
1491                        "id": "122884184",
1492                        "node-type": "cloud-region",
1493                        "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1494                        "url": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1"
1495                    },
1496                    {
1497                        "id": "122884296",
1498                        "node-type": "rack",
1499                        "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1500                        "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1/racks/rack/rackname1-1test"
1501                    }
1502                ],
1503                "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1"
1504            }
1505        ]
1506    }
1507
1508 graphson
1509 ^^^^^^^^
1510
1511 Provides the results using the graphson standard.
1512
1513 .. code::
1514
1515    PUT /aai/v$/query?format=graphson
1516
1517 Example Response
1518
1519 .. code-block:: json
1520
1521    {
1522        "results": [
1523            {
1524                "id": 81924184,
1525                "inE": {
1526                    "org.onap.relationships.inventory.LocatedIn": [
1527                        {
1528                            "id": "oeioq-oe3f4-74l-1crx3s",
1529                            "outV": 40968400,
1530                            "properties": {
1531                                "aai-uuid": "9e75af3d-aa7f-4e8e-a7eb-32d8096f03cc",
1532                                "contains-other-v": "NONE",
1533                                "delete-other-v": "NONE",
1534                                "prevent-delete": "IN",
1535                                "private": false
1536                            }
1537                        },
1538                        {
1539                            "id": "216a6j-215u1k-74l-1crx3s",
1540                            "outV": 122884184,
1541                            "properties": {
1542                                "aai-uuid": "4b3693be-b399-4355-8747-4ea2bb298dff",
1543                                "contains-other-v": "NONE",
1544                                "delete-other-v": "NONE",
1545                                "prevent-delete": "IN",
1546                                "private": false
1547                            }
1548                        },
1549                        {
1550                            "id": "215xjt-215u4o-74l-1crx3s",
1551                            "outV": 122884296,
1552                            "properties": {
1553                                "aai-uuid": "958b8e10-6c42-4145-9cc1-76f50bb3e513",
1554                                "contains-other-v": "IN",
1555                                "delete-other-v": "IN",
1556                                "prevent-delete": "NONE",
1557                                "private": false
1558                            }
1559                        }
1560                    ]
1561                },
1562                "label": "vertex",
1563                "properties": {
1564                    "aai-created-ts": [
1565                        {
1566                            "id": "1crvgr-1crx3s-6bk5",
1567                            "value": 1531231973518
1568                        }
1569                    ],
1570                    "aai-last-mod-ts": [
1571                        {
1572                            "id": "215vkb-1crx3s-6dxh",
1573                            "value": 1531233769164
1574                        }
1575                    ],
1576                    "aai-node-type": [
1577                        {
1578                            "id": "215urv-1crx3s-69z9",
1579                            "value": "complex"
1580                        }
1581                    ],
1582                    "aai-uri": [
1583                        {
1584                            "id": "1crxfv-1crx3s-6gat",
1585                            "value": "/cloud-infrastructure/complexes/complex/complextest1"
1586                        }
1587                    ],
1588                    "aai-uuid": [
1589                        {
1590                            "id": "1crvuz-1crx3s-1ybp",
1591                            "value": "3959ceca-3a89-4e92-a2ff-073b6f409303"
1592                        }
1593                    ],
1594                    "city": [
1595                        {
1596                            "id": "1cs0zv-1crx3s-4irp",
1597                            "value": "Beverley Hills"
1598                        }
1599                    ],
1600                    "complex-name": [
1601                        {
1602                            "id": "215wcr-1crx3s-4d8l",
1603                            "value": "chcil"
1604                        }
1605                    ],
1606                    "country": [
1607                        {
1608                            "id": "1cs26j-1crx3s-4l51",
1609                            "value": "USA"
1610                        }
1611                    ],
1612                    "data-center-code": [
1613                        {
1614                            "id": "215ssr-1crx3s-4bnp",
1615                            "value": "CHG"
1616                        }
1617                    ],
1618                    "last-mod-source-of-truth": [
1619                        {
1620                            "id": "215vyj-1crx3s-696t",
1621                            "value": "aai-AppId"
1622                        }
1623                    ],
1624                    "latitude": [
1625                        {
1626                            "id": "1cs2yz-1crx3s-4mpx",
1627                            "value": "30.123456"
1628                        }
1629                    ],
1630                    "longitude": [
1631                        {
1632                            "id": "1cs3d7-1crx3s-4nid",
1633                            "value": "-174.135344"
1634                        }
1635                    ],
1636                    "physical-location-id": [
1637                        {
1638                            "id": "1crzez-1crx3s-4a2t",
1639                            "value": "complextest1"
1640                        }
1641                    ],
1642                    "physical-location-type": [
1643                        {
1644                            "id": "1crzt7-1crx3s-4ged",
1645                            "value": "lab"
1646                        }
1647                    ],
1648                    "postal-code": [
1649                        {
1650                            "id": "1cs1sb-1crx3s-4kcl",
1651                            "value": "90210"
1652                        }
1653                    ],
1654                    "region": [
1655                        {
1656                            "id": "1cs2kr-1crx3s-4lxh",
1657                            "value": "West"
1658                        }
1659                    ],
1660                    "resource-version": [
1661                        {
1662                            "id": "215v63-1crx3s-glh",
1663                            "value": "1531233769164"
1664                        }
1665                    ],
1666                    "source-of-truth": [
1667                        {
1668                            "id": "1crv2j-1crx3s-6epx",
1669                            "value": "foo"
1670                        }
1671                    ],
1672                    "state": [
1673                        {
1674                            "id": "1cs1e3-1crx3s-4jk5",
1675                            "value": "CA"
1676                        }
1677                    ],
1678                    "street1": [
1679                        {
1680                            "id": "1cs07f-1crx3s-4h6t",
1681                            "value": "100 Main St"
1682                        }
1683                    ],
1684                    "street2": [
1685                        {
1686                            "id": "1cs0ln-1crx3s-4hz9",
1687                            "value": "Room 101"
1688                        }
1689                    ]
1690                }
1691            }
1692        ]
1693    }
1694
1695
1696 Optional Query Parameters
1697 ~~~~~~~~~~~~~~~~~~~~~~~~~
1698
1699 depth
1700 ^^^^^
1701
1702 You can pass the depth query parameter to specify how many levels of
1703 children/grandchildren to return. The default depth is 1.
1704
1705 .. code::
1706
1707    PUT /aai/v$/query?format={format}&depth=0
1708
1709 nodesOnly
1710 ^^^^^^^^^
1711
1712 You can pass the nodesOnly query parameter to have the output only
1713 contain the object properties with no relationships.
1714
1715 .. code::
1716
1717    PUT /aai/v$/query?format={format}&nodesOnly=true
1718
1719 subgraph
1720 ^^^^^^^^
1721
1722 You can pass a subgraph query parameter that determines the behavior
1723 of the output.  Using subgraph=prune returns all of the objects from
1724 the query and only the edges between those objects. Using
1725 subgraph=star returns all of the objects from the query plus all of
1726 the objects they relate to.
1727
1728 The default is subgraph=star
1729
1730 .. code::
1731
1732    PUT /aai/v$/query?format={format}&subgraph={subgraph}
1733
1734 HTTP Headers
1735 ~~~~~~~~~~~~
1736
1737 +--------------------------+--------------------------------------------------------------------------------------+
1738 |   X-FromAppID={client ID}| Unique application identifier.                                                       |
1739 +--------------------------+--------------------------------------------------------------------------------------+
1740 |  X-TransactionID={UUDID} | must be a UUID and unique to each transaction within the context of an X-FromAppID.  |
1741 +--------------------------+--------------------------------------------------------------------------------------+
1742 |  Content-Type={format}   | format of the request. Should be application/json or application/xml.                |
1743 +--------------------------+--------------------------------------------------------------------------------------+
1744 |  Accept={format}         | format of the response. Should be application/json or application/xml.               |
1745 +--------------------------+--------------------------------------------------------------------------------------+
1746
1747 Request Payload
1748 ~~~~~~~~~~~~~~~
1749
1750 Typically the query payload will include both a "start" and a "query"
1751 portion. The "start" can indicate one or more starting nodes in the
1752 graph. If multiple nodes are specified, the result will contain the
1753 query results for all of the start nodes. The "query" indicates the
1754 name of the query to be run and also takes query parameters depending
1755 on the query. Please reference the queries on the AAI wiki for
1756 specific saved queries and how they should be usServer Timeout A
1757 Server timeout is implemented for these APIs to make sure the server
1758 did not continue processing the request long after a client times out
1759 on their side. An error code ERR.5.4.7406 will be returned when this
1760 limit is hit. The default value for Traversal API is 60 secs. The
1761 clients should set their timeouts accordingly.
1762
1763 List of Queries and Payloads
1764 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1765
1766 For a full list of available custom queries, please refer to our
1767 `Custom Queries <customQueries.html>`_ document
1768
1769 Recents API
1770 -----------
1771
1772 The Recents API allows a client to get the list of objects that has
1773 been created or updated recently, up to a maximum of 1 week
1774 back.
1775
1776 `Recents API <recentsApi.html>`_