diff options
| -rw-r--r-- | docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst | 685 | ||||
| -rw-r--r-- | docs/AAI REST API Documentation/customQueries.rst | 15 | ||||
| -rw-r--r-- | docs/index.rst | 2 |
3 files changed, 700 insertions, 2 deletions
diff --git a/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst b/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst index 19506bf5..95f5cdc2 100644 --- a/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst +++ b/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst @@ -704,7 +704,7 @@ Example GET Request Swagger and XSD: ---------------- -`Offered APIs <../platform/offeredapis.rst>`_ +`Offered APIs <../platform/offeredapis.html>`_ Data Assumptions ---------------- @@ -1031,3 +1031,686 @@ The Bulk API allows clients to make multiple requests in a single transaction. Please look for additional details on the following wiki page +AAI Traversal APIs +================== + +Not all queries of the graph are purely GETs of a specific resource +and its related vertexes. The following capabilities are available to +meet more advanced search needs. Please contact the AAI team if you +need another search. + +Node Queries +------------ + +The Nodes Query mechanism was implemented in support of searching the +pservers which do not have the ipv4-oam-ipaddress set. It will allow +nodes to be searched based on certain properties of the nodes. It will +allow search based on properties being set, not set or set to specific +values. + +Generic Queries +--------------- + +The Generic Query mechanism allows to search for certain nodes of +“include” node types at a specified “depth” from the from a particular +start node of type “start-node-type” identified by specifying its +“key” values + +Model Based Query and Delete +---------------------------- + +AAI supports a search and delete capability that allows a client to +retrieve or delete an instance of a service based on the model +subgraph definition provided to AAI by ASDC. + +The instance filters must uniquely identify a service instance. + +The URL is as follows: + +.. code:: + + https://{serverRoot}/aai/search/model[?action=DELETE] + +.. code-block:: json + + { + "query-parameters": { + "model": { + "model-invariant-id": "$modelInvariantId", + "model-vers": { + "model-ver": [ + { + "model-version-id": "$modelVersionId" + } + ] + } + }, + "instance-filters": { + "instance-filter": [ + { + "customer": { + "global-customer-id": "$globalCustID" + }, + "service-instance": { + "resource-version": "$resourceversionID", + "service-instance-id": "$serviceInstanceID" + }, + "service-subscription": { + "service-type": "$serviceType" + } + } + ] + } + } + } + +Named Query +----------- + +These queries provide the ability to upload a json file describing the +inputs and designed output based on traversing the graph in a +particular way. Existing named queries are supported but will be +migrated to custom queries. **Named queries will be deprecated (no new +queries, just support for existing ones) in Dublin and clients will be +asked to migrate to use the custom queries instead.** + +Custom Query +------------ + +This API provides AAI clients an API for complex data retrieval. To +execute a custom query, a client will perform an HTTP PUT request on +the query API and include a payload indicating the starting node and +the query to be run. While the client is performing a PUT request, +this is actually a data query and no data is created or changed. + +Assumptions +~~~~~~~~~~~ + ++----------+-----------------------------+--------------------------+ +| No. | Assumption | Approach | ++==========+=============================+==========================+ +| 1 | Assume that client will | | +| | not request large amounts | | +| | of data from AAI w/out | | +| | using secondary filters | | ++----------+-----------------------------+--------------------------+ + +Depdendencies +~~~~~~~~~~~~~ + +Data has been PUT to AAI prior to the query. + +Custom Query URI +~~~~~~~~~~~~~~~~ + +.. code:: + + PUT /aai/v$/query?format={format} + +Query Formats +~~~~~~~~~~~~~ + +The format determines what information is returned from the +query. Acceptable formats are: count, id, pathed, resource, +resource_and_url, or simple. + +count +^^^^^ + +Provides an count of the objects returned in the query. + +.. code:: + + PUT /aai/v$/query?format=count + +Example reponse + +.. code-block:: json + + { + "results": [ + { + "pnf": 4, + "p-interface": 5, + "l-interface": 3, + "pserver": 1 + } + ] + } + +id +^^^ + +Provides an array of objects containing resource-type (AAI's node +type; i.e., pnf) and a URI using the vertex ID from AAI's graph. + +.. code:: + + PUT /aai/v$/query?format=id + +Example Response + +.. code-block:: json + + { + "results": [ + { + "resource-type": "complex", + "resource-link": "/aai/v1/resources/id/8159312" + }, + { + "resource-type": "complex", + "resource-link": "/aai/v1/resources/id/389256" + } + ] + } + +pathed +^^^^^^ + +Provides an array of objects containing resource-type (AAIs node type; +i.e., pnf) and a URI using the AAI REST API pathed URIs + +.. code:: + + PUT /aai/v$/query?format=pathed + +Example Response + +.. code-block:: json + + { + "results": [ + { + "resource-type": "complex", + "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1" + }, + { + "resource-type": "complex", + "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1" + } + ] + } + +resource +^^^^^^^^ + +Provides each object in the results array in the same format as AAI's +REST API with depth = 1 (first level children and cousin +relationships). + +.. code:: + + PUT /aai/v$/query?format=resource + + +Example Response + +.. code-block:: json + + { + "results": [ + { + "complex": { + "city": "Anywhere", + "complex-name": "complex-mccomplexface", + "country": "USA", + "data-center-code": "CHG", + "latitude": "30.123456", + "longitude": "-78.135344", + "physical-location-id": "complextest1", + "physical-location-type": "lab", + "postal-code": "90210", + "region": "West", + "relationship-list": { + "relationship": [ + { + "related-link": "/aai/v1/network/zones/zone/zone1", + "related-to": "zone", + "related-to-property": [ + { + "property-key": "zone.zone-name", + "property-value": "zone-name1" + } + ], + "relationship-data": [ + { + "relationship-key": "zone.zone-id", + "relationship-value": "zone1" + } + ], + "relationship-label": "org.onap.relationships.inventory.LocatedIn" + }, + { + "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1", + "related-to": "cloud-region", + "related-to-property": [ + { + "property-key": "cloud-region.owner-defined-type" + } + ], + "relationship-data": [ + { + "relationship-key": "cloud-region.cloud-owner", + "relationship-value": "Cloud-Region" + }, + { + "relationship-key": "cloud-region.cloud-region-id", + "relationship-value": "Region1" + } + ], + "relationship-label": "org.onap.relationships.inventory.LocatedIn" + } + ] + }, + "resource-version": "1531233769164", + "state": "CA", + "street1": "100 Main St", + "street2": "C3-3W03" + } + } + ] + } + +resource_and_uri +^^^^^^^^^^^^^^^^ + +Provides each object in the results array in the same format as AAI’s +REST API with depth = 1 (first level children and cousin +relationships) plus the pathed url for the result object in AAI. + +.. code:: + + PUT /aai/v$/query?format=resource_and_url + +Example Response + +.. code-block:: json + + { + "results": [ + { + "complex": { + "city": "Anywhere", + "complex-name": "complex-mccomplexface", + "country": "USA", + "data-center-code": "CHG", + "latitude": "30.123456", + "longitude": "-78.135344", + "physical-location-id": "complextest1", + "physical-location-type": "lab", + "postal-code": "90210", + "region": "West", + "relationship-list": { + "relationship": [ + { + "related-link": "/aai/v1/network/zones/zone/zone1", + "related-to": "zone", + "related-to-property": [ + { + "property-key": "zone.zone-name", + "property-value": "zone-name1" + } + ], + "relationship-data": [ + { + "relationship-key": "zone.zone-id", + "relationship-value": "zone1" + } + ], + "relationship-label": "org.onap.relationships.inventory.LocatedIn" + }, + { + "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1", + "related-to": "cloud-region", + "related-to-property": [ + { + "property-key": "cloud-region.owner-defined-type" + } + ], + "relationship-data": [ + { + "relationship-key": "cloud-region.cloud-owner", + "relationship-value": "Cloud-REgion" + }, + { + "relationship-key": "cloud-region.cloud-region-id", + "relationship-value": "Region1" + } + ], + "relationship-label": "org.onap.relationships.inventory.LocatedIn" + } + ] + }, + "resource-version": "1531233769164", + "state": "CA", + "street1": "100 Main St", + "street2": "C3-3W03" + }, + "url": "/aai/v11/cloud-infrastructure/complexes/complex/complextest1" + } + ] + } + +simple +^^^^^^ + +Provides each result object in a simplified format. The node-type, +graph vertex id, pathed url, object properties, and directly related +objects in the graph are all returned. Both direct parent/child +objects and cousin objects are included in the related-to array. + +.. code:: + + PUT /aai/v$/query?format=simple + +Example Response + +.. code-block:: json + + { + "results": [ + { + "id": "81924184", + "node-type": "complex", + "properties": { + "city": "Anywhere", + "complex-name": "complex-mccomplexface", + "country": "USA", + "data-center-code": "CHG", + "latitude": "30.123456", + "longitude": "-78.135344", + "physical-location-id": "complextest1", + "physical-location-type": "lab", + "postal-code": "90210", + "region": "West", + "resource-version": "1531233769164", + "state": "CA", + "street1": "100 Main St", + "street2": "C3-3W03" + }, + "related-to": [ + { + "id": "40968400", + "node-type": "zone", + "relationship-label": "org.onap.relationships.inventory.LocatedIn", + "url": "/aai/v1/network/zones/zone/zone1" + }, + { + "id": "122884184", + "node-type": "cloud-region", + "relationship-label": "org.onap.relationships.inventory.LocatedIn", + "url": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1" + }, + { + "id": "122884296", + "node-type": "rack", + "relationship-label": "org.onap.relationships.inventory.LocatedIn", + "url": "/aai/v1/cloud-infrastructure/complexes/complex/complextest1/racks/rack/rackname1-1test" + } + ], + "url": "/aai/v1/cloud-infrastructure/complexes/complex/complextest1" + } + ] + } + +graphson +^^^^^^^^ + +Provides the results using the graphson standard. + +.. code:: + + PUT /aai/v$/query?format=graphson + +Example Response + +.. code-block:: json + + { + "results": [ + { + "id": 81924184, + "inE": { + "org.onap.relationships.inventory.LocatedIn": [ + { + "id": "oeioq-oe3f4-74l-1crx3s", + "outV": 40968400, + "properties": { + "aai-uuid": "9e75af3d-aa7f-4e8e-a7eb-32d8096f03cc", + "contains-other-v": "NONE", + "delete-other-v": "NONE", + "prevent-delete": "IN", + "private": false + } + }, + { + "id": "216a6j-215u1k-74l-1crx3s", + "outV": 122884184, + "properties": { + "aai-uuid": "4b3693be-b399-4355-8747-4ea2bb298dff", + "contains-other-v": "NONE", + "delete-other-v": "NONE", + "prevent-delete": "IN", + "private": false + } + }, + { + "id": "215xjt-215u4o-74l-1crx3s", + "outV": 122884296, + "properties": { + "aai-uuid": "958b8e10-6c42-4145-9cc1-76f50bb3e513", + "contains-other-v": "IN", + "delete-other-v": "IN", + "prevent-delete": "NONE", + "private": false + } + } + ] + }, + "label": "vertex", + "properties": { + "aai-created-ts": [ + { + "id": "1crvgr-1crx3s-6bk5", + "value": 1531231973518 + } + ], + "aai-last-mod-ts": [ + { + "id": "215vkb-1crx3s-6dxh", + "value": 1531233769164 + } + ], + "aai-node-type": [ + { + "id": "215urv-1crx3s-69z9", + "value": "complex" + } + ], + "aai-uri": [ + { + "id": "1crxfv-1crx3s-6gat", + "value": "/cloud-infrastructure/complexes/complex/complextest1" + } + ], + "aai-uuid": [ + { + "id": "1crvuz-1crx3s-1ybp", + "value": "3959ceca-3a89-4e92-a2ff-073b6f409303" + } + ], + "city": [ + { + "id": "1cs0zv-1crx3s-4irp", + "value": "Middletown" + } + ], + "complex-name": [ + { + "id": "215wcr-1crx3s-4d8l", + "value": "chcil" + } + ], + "country": [ + { + "id": "1cs26j-1crx3s-4l51", + "value": "USA" + } + ], + "data-center-code": [ + { + "id": "215ssr-1crx3s-4bnp", + "value": "CHG" + } + ], + "last-mod-source-of-truth": [ + { + "id": "215vyj-1crx3s-696t", + "value": "aai-AppId" + } + ], + "latitude": [ + { + "id": "1cs2yz-1crx3s-4mpx", + "value": "30.123456" + } + ], + "longitude": [ + { + "id": "1cs3d7-1crx3s-4nid", + "value": "-74.135344" + } + ], + "physical-location-id": [ + { + "id": "1crzez-1crx3s-4a2t", + "value": "complextest1" + } + ], + "physical-location-type": [ + { + "id": "1crzt7-1crx3s-4ged", + "value": "nj-lab" + } + ], + "postal-code": [ + { + "id": "1cs1sb-1crx3s-4kcl", + "value": "07748" + } + ], + "region": [ + { + "id": "1cs2kr-1crx3s-4lxh", + "value": "Northeast" + } + ], + "resource-version": [ + { + "id": "215v63-1crx3s-glh", + "value": "1531233769164" + } + ], + "source-of-truth": [ + { + "id": "1crv2j-1crx3s-6epx", + "value": "rx2202" + } + ], + "state": [ + { + "id": "1cs1e3-1crx3s-4jk5", + "value": "NJ" + } + ], + "street1": [ + { + "id": "1cs07f-1crx3s-4h6t", + "value": "200 Laurel Av" + } + ], + "street2": [ + { + "id": "1cs0ln-1crx3s-4hz9", + "value": "C3-3W03" + } + ] + } + } + ] + } + +Optional Query Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~ + +depth +^^^^^ + +You can pass the depth query parameter to specify how many levels of +children/grandchildren to return. The default depth is 1. + +.. code:: + + PUT /aai/v$/query?format={format}&depth=0 + +nodesOnly +^^^^^^^^^ + +You can pass the nodesOnly query parameter to have the output only +contain the object properties with no relationships. + +.. code:: + + PUT /aai/v$/query?format={format}&nodesOnly=true + +subgraph +^^^^^^^^ + +You can pass a subgraph query parameter that determines the behavior +of the output. Using subgraph=prune returns all of the objects from +the query and only the edges between those objects. Using +subgraph=star returns all of the objects from the query plus all of +the objects they relate to. + +The default is subgraph=star + +.. code:: + + PUT /aai/v$/query?format={format}&subgraph={subgraph} + +HTTP Headers +~~~~~~~~~~~~ + ++--------------------------+--------------------------------------------------------------------------------------+ +| X-FromAppID={client ID}| Unique application identifier. | ++--------------------------+--------------------------------------------------------------------------------------+ +| X-TransactionID={UUDID} | must be a UUID and unique to each transaction within the context of an X-FromAppID. | ++--------------------------+--------------------------------------------------------------------------------------+ +| Content-Type={format} | format of the request. Should be application/json or application/xml. | ++--------------------------+--------------------------------------------------------------------------------------+ +| Accept={format} | format of the response. Should be application/json or application/xml. | ++--------------------------+--------------------------------------------------------------------------------------+ + +Request Payload +~~~~~~~~~~~~~~~ + +Typically the query payload will include both a "start" and a "query" +portion. The "start" can indicate one or more starting nodes in the +graph. If multiple nodes are specified, the result will contain the +query results for all of the start nodes. The "query" indicates the +name of the query to be run and also takes query parameters depending +on the query. Please reference the queries on the AAI wiki for +specific saved queries and how they should be usServer Timeout A +Server timeout is implemented for these APIs to make sure the server +did not continue processing the request long after a client times out +on their side. An error code ERR.5.4.7406 will be returned when this +limit is hit. The default value for Traversal API is 60 secs. The +clients should set their timeouts accordingly. + +List of Queries and Payloads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For a full list of available custom queries, please refer to our +`Custom Queries <customQueries.html>`_ document + diff --git a/docs/AAI REST API Documentation/customQueries.rst b/docs/AAI REST API Documentation/customQueries.rst new file mode 100644 index 00000000..87c88ed9 --- /dev/null +++ b/docs/AAI REST API Documentation/customQueries.rst @@ -0,0 +1,15 @@ +.. contents:: + :depth: 3 +.. +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +==================== + AAI Custom Queries +==================== + +Overview +======== + diff --git a/docs/index.rst b/docs/index.rst index c312695d..18fccb05 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,5 +15,5 @@ The key AAI repos for running the AAI REST APIs: platform/index.rst release-notes.rst - AAI REST API Documentation/AAIRESTAPI_AMSTERDAM + AAI REST API Documentation/AAIRESTAPI_CASABLANCA |