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