4 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
5 .. http://creativecommons.org/licenses/by/4.0
7 \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
16 The AAI REST API provides access to the AAI active inventory graph. The
17 API is largely configured off of models and configuration files. Each
18 vertex in the graph has an API that can be called separately or, if part
19 of a tree structure, as a nested element with one or more generations
20 (parent, grandparent, etc.).
22 The edges of the graph are provisioned using a relationship list
23 construct. For PUT methods, a relationship contains the vertex type or
24 category (related-to) and a list of relationship data which captures the
25 key pieces of data required to uniquely identify the resource. On a GET
26 method, the above information and a URL are returned. The URL can be
27 used to GET all the details of that object. The URL returned is suitable
28 for retrying failed commands but should not be expected to be cacheable
29 for very long periods (e.g., the version of the URL may get deprecated
30 when the release changes).
32 The REST API describes each API that AAI provides, independent of the
33 caller of the API, therefore there is no information to be found here
34 regarding the expectations on the callers. That information is
35 conveyed in AID documents for each client. AIDs will describe the
36 information expected from specific clients, but may not contain the
37 full payloads that would be needed on an update. Please see the
38 concurrency notes referenced below in order to do the right kind of
39 PUTs (GET, replace just what you are changing, PUT) or use the PATCH
42 Deprecation Warnings and History
43 ================================
45 AAI will maintain backwards compatibility for two prior releases.
46 This means, with the introduction of v14 AAI will support **v11**
47 (Amsterdam), **v13** (Beijing), and **v14** (Casablanca)
52 - A new API called recents API is now available mostly intended for DCAE use.
54 - A new and improved bulk api interface is also available now.
56 - More details on the above APIs can be found in wiki pages referenced
62 - To handle security vulnerabilities that were raised as part of Nexus
63 IQ scans in ONAP, the APIs are being hosted on a spring-boot with
66 - The deletion rules are now applied to all the nodes that will be
67 deleted by the delete request.
69 For example, if the graph is:
75 If nodeA is parent of nodeB and nodeB is parent of nodeC
77 +------+---------------------+
78 |nodeA | CASCADE_TO_CHILDREN |
79 +------+---------------------+
80 |nodeB | CASCADE_TO_CHILDREN |
81 +------+---------------------+
82 |nodeC | ERROR_IF_IN_EDGES |
83 +------+---------------------+
85 - If request is to delete nodeA, it would fail because nodeC has an in
86 edge from a node not being deleted in this transaction.
88 - A configurable server timeout was implemented to make sure the AAI
89 server did not continue processing the request long after a client
90 times out on their side. An error code ERR.5.4.7406 will be returned
91 when this limit is hit. A configuration for clients known to have
92 longer running queries currently overrides the default value.
94 - To handle a risk identified by Fortify scans, a maxOccurs of 5000
100 - DELETE request will generate a DMAAP event for each node deleted
101 (not just the for which the DELETE request was made)
105 Starting with Casablanca, multiple edges can exist
106 in the graph between the same 2 nodes. The REST API has been
107 enhanced via changing the relationship-list so clients can specify
108 which edge they are creating and differentiate multiple edges
109 between the same 2 nodes. Backwards compatibility with older API
110 versions that do notspecify the edge will be maintained.
112 - A new property “relationship-label” has been added that when
113 specified will be used to create any new edge. If not specified the
114 default edge label between the two nodes will be used. The
115 relationship-label will always be returned with the v12 version of
116 GETs whenever the relationship-list is returned.
121 "relationship-list": {
124 "related-link": "/aai/v12/cloud-infrastructure/complexes/complex/6d8f945d-8bd2-4fa2-ad37-36b21fc8fb23-PS2418",
125 "related-to": "complex",
126 "relationship-data": [
128 "relationship-key": "complex.physical-location-id",
129 "relationship-value": "6d8f945d-8bd2-4fa2-ad37-36b21fc8fb23-PS2418"
132 "relationship-label": "locatedIn"
143 - The actions/update API will be retired. Clients must switch to PATCH.
144 There is one grandfathered usage for vpe update flows which will be
147 - The edge tag query will be retired.
149 Notable attribute and/or valid value changes (generally also impacts
152 - The persona-model-id and persona-version will be replaced with
153 model-invariant-id (same value as persona-model-id) and
154 model-version-id (the UUID of the specific version of a model).
155 Persona-model-customization-id will be replaced by
156 model-customization-id.
158 - The operational-state attribute will be replaced by
159 operational-status and the only valid values will be in-service-path
160 and out-of-service-path
162 - The vpn-binding object will be split in two to reflect more than one
163 route-target per binding. The route-target will be a child of
164 vpn-binding and some attributes will move from vpn-binding to
167 - The following license related attributes will be removed from
168 generic-vnf: license-key, entitlement-assignment-group-uuid,
169 entitlement-resource-uuid, license-assignment-group-uuid, and
170 license-key-uuid due to the introduction of the entitlement and
175 - Normal impacts due to renaming or adding attributes, splitting
176 objects, etc. Please see swagger documentation for objects of
179 - In v11, clients that require lineage, children, or relationship
180 information need to subscribe to a different DMaaP topic than the
185 - The related-link will be a URI and thus not contain
186 https://{serverroot} (impacts events)
188 - The related-link will be used on a PUT as the "first choice" to
189 identify the related resource. The relationship-data structure, which
190 contains the unordered set of keys, is still an acceptable way to
191 relate two objects but, *if both the relationship-data and the
192 related-link are passed, and they don't agree, the related-link will
193 be used without warning that the data is inconsistent*.
195 - The relationship-data will be ignored on PUT.
200 In the future, the hope is that individual node definitions will be
201 separately versioned from API behavior and from one another (e.g.,
202 vserver hasn't changed in many releases and so doesn't need to have
203 its "definition" version updated).
205 Because relationships are starting to become more complex, it may be
206 necessary for AAI to expose to clients the exact relationship between
207 two nodes. This will likely be done with a relationship-type
208 attribute of relationships in the relationship-list.
210 To support the concept of events getting generated on specific changed
211 items, AAI will be migrating towards a model of asking clients to do
212 the most granular PUTs possible rather than leveraging the nested
213 elements of a tree structure.
215 The vce, port-group, cvlan-tag, newvce, vpe, oam-network, and
216 dvs-switch objects will eventually be deprecated in favor of
217 generic-vnf, l3-network, ctag-assignment, segmentation-assignment, and
220 L3-network will eventually be replaced by virtual-network.
222 How to Use this Document
223 ========================
225 The only attributes in our objects that are declared required are
226 those which we know will be present at the creation of each object and
227 which are needed to support the construction of the AAI Graph. This
228 does not imply that one of AAI's clients doesn't need data.
230 When you click on the API documentation, you will see the Summary of
231 APIs broken down by namespace (e.g., cloud-infrastructure, business,
232 network, service-design-and-creation). You can search for **Tag:**
233 (matching the explicit case) to move from namespace to namespace through
236 Search for **Paths** to skip past the Summary section where there will
237 be more detail about each API. Query parameters are provided here, as
238 well as links to our error codes.
240 Search for **Schema definitions** to see the definitions of the
241 payloads. In your browser URL, you can type /#/definitions/node-name at
242 the end of the html address to skip directly to a payload definition.
244 Note that the schema definitions now contain information about the
245 delete scope of a node, edges, and some related node information.
246 Given this information can now be generated, it is no longer repeated
249 Once AAI has a model and configured it, the AAI development server can
250 be used to generate sample XML and JSON payloads, according to the
251 Accept header passed in the request. This is done by calling the
252 "plural" version of an API followed by the word example (e.g.,
253 /vserver/vservers/example). This returns a GET result array with one
254 entry. That single entry can be sent in a PUT request with actual data
255 (the resource-id does not need to be in the PUT payload as it is on the
258 Finally, custom queries that are not simple GETs of a resource must be
259 identified to AAI as separate user stories. This includes searching
260 for a resource with other attributes on the same resource, as well as
261 searching for resources based on their relationship with other
270 Cloud Infrastructure Domain
271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
273 The Cloud Infrastructure domain (cloud-infrastructure) represents the
274 assets managed within a cloud site. This includes the complex, the
275 physical servers, the availability zones, oam-networks, tenants, and
276 vserver-related resources (vservers, flavors, images, etc.).
278 Tenants, oam-networks, availability-zones, volume-groups, images,
279 flavors, and dvs-switches will have cloud-region as its parent node.
284 The network namespace contains virtual and physical network resources
285 as well as connection resources such as physical links, logical links,
288 The vce/port-group/cvlan-tag tree represents an immature model that
289 blended several resources together in ways that were expedient but
290 which need to be re-evaluated. A newvce object exists which was the
291 basis of the generic-vnf object. Future efforts will attempt to
292 migrate vce and vpe into generic-vnf.
297 The business namespace captures customers, service-subscriptions, and
298 service-instances. This domain is immature and will be evolving as
299 service design and creation starts to gel.
301 Customers and service-subscriptions in particular will be evolving
302 soon. Any service that is customer facing will see customer and
303 service-subscription data offboarding to BSSs. The
304 service-instance-id will be the "join point" within the BSS to
305 correlate the service-instance to the product and customer. Services
306 that are for infrastructure purposes will have a new entity, an
307 owning-entity, to replace the customer. The owning-entity will be
308 related to the SDC service models that use it.
310 Service Design and Creation
311 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
313 The service design and creation namespace captures data we invented
314 based on what we thought SDC would eventually provide. The structure
315 of that data is definitely not what the current plans are for SDC
316 however we need to at least capture the spirit of what's intended and
317 communicate that across ONAP sub components that need it.
319 To date, there are only five containers:
321 1. Service-capabilities capture the pairings of service to
322 resources. At the time of construction, the only data we had to
323 denote service was the service-type from SO. The vnf-type is the
326 2. Service captures the service model instances and this will be
327 deprecated in the future as things mature
329 3. Vnf-image captures information about the resource image needed for
330 a VNF. This was created due to there being no info available on
331 the vservers that run on uCPE
333 4. Models captures model definitions (subgraph definitions using the
336 5. named-queries capture subgraph definitions that allow different
337 data to be retrieved for a given type of asset
342 All REST APIs must be called using https.
344 HTTPS Basic Authentication will be used to authenticate clients. The
345 remote user from the HTTP Servlet Request is used against an AAI
346 policy to see if the authenticated user is authorized for the resource
347 and actions being request.
349 Client should use credentials provided to their system via AAF.
351 The following will be used for logging and interface diagnostic purposes.
353 * X-FromAppId Unique Application ID assigned to the user of these APIs
354 * X-TransactionId Unique ID that identifies an API request
356 The X-FromAppId will be assigned to each application by the AAI team.
357 The X-TransactionId must be unique to each transaction within the
358 context of an X-FromAppId.
360 SO, SDN-C, and AAI have agreed to use the Java UUID class to generate
361 unique ids for X-TransactionId.
363 The Accept and Content-type header should be set to either
364 application/json or application/xml except as documented for PATCH.
366 Response Codes and Error Handling
367 ---------------------------------
369 AAI will use the following HTTP codes
377 - 204 – Success, no payload returned
382 - 405 – Method Not Allowed
383 - 409 - The request could not be completed due to a conflict with the
384 current state of the target resource. This code is used in situations
385 where the user might be able to resolve the conflict and resubmit the
386 request. If the resource version doesn’t match AAI or a required
387 resource version isn't sent but should have been
388 - 410 - You are using a version of the API that has been retired
389 - 412 – Precondition failed (If the resource version doesn’t match AAI or arequired resource version isn't sent but should have been
390 - 415 – Unsupported Media Type 500 - Internal Server Error
392 Successful PUT responses shall return the following codes:
393 * 200 (OK): used when an existing resource has been modified and
394 there is a response buffer
395 * 201 (Created): MUST be used when a new resource is created
396 * 202 (Accepted): used when AAI completed the action requested but
397 may have taken other actions as well, which are returned in the
399 * 204 (No Content): used when the existing resource has been modified
400 and there is no response buffer
402 Successful DELETE responses shall return the following codes:
403 * 200 (OK): for a successful response if the response includes an
404 entity describing the status.
405 * 204 (No Content): if the action has been enacted but the response
406 does not include an entity.
408 Successful GET responses shall return the following codes:
409 * 200 (OK): for a successful response for a resource that has been found
410 * 404 (Not Found) for a successful response retrieving a list of
411 items and there were no items found, i.e., the GET of the specific
412 plural resource was not found
413 * 404 (Not Found): when a specific resource was not found
416 * 400 Bad Request will be returned if headers are missing
417 * 404 Not Found will be returned if an unknown URL is used
419 In addition, the standard response buffer will be structured as follows unless otherwise specified.
420 There are two types of requestErrors.
422 * Service Exceptions – These exceptions occur when a service is
423 unable to process a request and retrying the request will result in
424 a consistent failure (e.g., an application provides invalid input).
425 * Policy Exceptions – These exceptions occur when a policy criteria
426 has not been met (e.g., the (N+1)th request arrives when an
427 application’s service level agreement only allows N transactions
430 Italics are specific to the error returned, and generally described in the notes
434 HTTP/1.1 405 *Method Not Allowed*
435 Content-Type: application/json
436 Content-Length: nnnnn
437 Date: *Thu, 04 Jun 2009 02:51:59 GMT*
441 “messageId”:"*POL8007*",
442 “text”:”*The resource was invoked with an unsupported operation: %1.*”,
443 “variables”: [”*PUT*”]
449 a. On the first line, substitute the appropriate status response code.
451 b. On the second line, substitute the appropriate content type.
453 c. Express the requestError structure in the required content type (e.g., either JSON or XML). AAI will use JSON.
455 d. ‘requestError’ contains either a ‘policyException’ or a ‘serviceException’ structure.
459 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.
461 Sample response to a vserver PUT where the pserver and complex did not exist:
465 {"responseMessages": {"responseMessage": [
467 "messageId": "INF0003",
468 "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
469 "variables": {"variable": [
473 "physical-location-id=fakeccwcomplex",
474 "Added prerequisite object to db:complex",
479 "messageId": "INF0003",
480 "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
481 "variables": {"variable": [
485 "hostname=fakeccwpserver",
486 "Added prerequisite object to db:pserver",
492 Referential Integrity
493 ---------------------
495 AAI is primarily a view to the relationships between instances of
496 services, physical and virtual components, etc. It stores just the
497 details it needs to be efficient to its tasks and knows how to get
498 more details if needed.
500 As such, a transaction sent to AAI may be refused if would break
501 referential integrity. The referential integrity rules of AAI are
502 still evolving as we understand the services and customers that will
505 AAI uses a graph database on a NoSQL data store. The following are
508 * Some vertices are exposed to the outside world through APIs, others
509 are internal to how we store the data (i.e., it may look like one
510 resource to our customers but it is expressed as more than one
513 * Vertices that are internal to AAI will be deleted when the parent
514 vertex is deleted, if deletion of the parent leaves the child vertex
517 * Vertices that are exposed need to be managed using specific rules
520 * Vertices may have more than just parent/child relationships. One
521 example is a vserver, which will be owned by a tenant and used by a
524 The Relationship-List
525 ---------------------
527 The REST interface does not lend itself to creating more than
528 parent-child relationships and the backend structure of AAI is a
529 graph. A goal of AAI, and shared with ONAP, is to do as little coding
530 as possible to introduce a new service into the service design and
531 creation environment.
533 To that end, we've introduced a relationship-list structure. AAI will
534 ask its clients to provide certain data in the relationship-list
537 Each relationship has a related-to attribute and a list of key/value
538 pairs. The related-to attribute identifies the node type that the
539 resource being acted on is to be related to using the data in the
540 key/value pairs. AAI will encode a set of rules for each resource
541 type to verify that only valid edges are being made. AAI will keep
542 the directionality and cardinality, and the edge attributes within its
543 own logic. In the near future, the definition of relationships, their
544 validity, and cardinality will be captured in the ONAP TOSCA models.
546 AAI also has a concept of a related-to category. To date, the only
547 category is vnf. The vnf category is used as the related-to value to
548 indicate that the relationship being establish is to a Virtual Network
549 Function of unknown type. The vnf-id happens to be unique for all
550 services across all nodes in the graph. By providing vnf.vnf-id with
551 a specific value, AAI can look at all VNFs in the graph and find the
552 appropriate vertex. Note that this only applies to PUTs.
554 Category vnf is used for node types of vce, vpe, and generic-vnf.
556 If an attempt is made to add a relationship to a node that doesn't
557 exist (e.g., from a vserver to a vnf, and the vnf doesn't exist), a
558 unique message Id (3003) will be returned with a specific error code
559 (ERR.5.4.6129). Arguments will tell the client which node type was
560 missing (e.g., vnf) and the key data for that node type (vnf.vnf-id).
562 Single relationships can be PUT to the graph in the following way:
566 https://{serverRoot}/{namespace}/{resource}/relationship-list/relationship
572 https://aai/v10/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
574 with a payload containing the relationship information.
576 AAI will accept and give preference to the related-link URI
582 <relationship xmlns="http://org.onap.aai.inventory/vX">
583 <related-link>*/aai/v10/network/logical-links/logical-link/logical-link-123456789-01*</related-link>
584 <related-to>logical-link</related-to>
586 <relationship-key>logical-link.link-name</relationship-key>
587 <relationship-value>logical-link-123456789-01</relationship-value>
596 "related-link": " /aai/v10/network/logical-links/logical-link/logical-link-123456789-01",
597 "related-to": "logical-link",
598 "relationship-data": [
600 "relationship-key": "logical-link.link-name",
601 "relationship-value": " logical-link-123456789-01"
609 The util domain is where AAI locates utility functions. There is
610 currently one utility function, echo, which serves as a ping test that
611 authenticated authorized clients can call to ensure there is
612 connectivity with AAI.
614 The URL for the echo utility is:
618 https://aai.onap:8443/aai/util/echo
620 If the response is unsuccessful, an error will be returned following
623 The successful payload returns the X-FromAppId and X-TransactionId
626 Successful XML Response Payload
627 -------------------------------
634 <messageId>INF0001</messageId>
635 <text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text>
637 <variable>CCW</variable>
638 <variable>CCW33335</variable>
639 <variable>Successful health check:OK</variable>
640 <variable>0.0.0002</variable>
646 Successful JSON Response Payload
647 --------------------------------
652 "responseMessages": {
655 "messageId": "INF0001",
656 "text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)",
661 "Successful health check:OK",
670 AAI Resources CRUD APIs
671 =======================
673 The API structure is composed of:
675 * The HTTP command, which indicates the operation to perform
676 * The HTTP URI, which defines what object this operation is related to
677 * The HTTP version, which MUST be 1.1
679 Available HTTP commands are:
681 * PUT: used to create or update an object
682 * DELETE: used to delete an object or a set of objects
683 * GET : used to query an object or set of objects
684 * PATCH : used to update specific fields owned by the client doing the update
686 The HTTP URI is built according to this pattern:
690 https://{serverRoot}/{namespace}/{resource}
692 * {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.
694 * {namespace} refers to the API namespace. Supported namespaces are cloud-infrastructure, business, service-design-and-creation, and network
696 * {resource} refers to how the object is identified according to the namespace specifications.
702 GET https://aai.onap:8443/aai /v11/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}
707 `Offered APIs <../platform/offeredapis.html>`_
712 Given AAI is largely a correlation engine among disparate inventory
713 types, AAI will for the most part accept values as they are sent,
714 without validating the format or value of the input. **It is
715 incumbent upon the source of truth to provide valid information to
718 Clients should either use the PATCH API (section 7.5) to only change
719 the attribute values they mean to change, or do a GET prior to a PUT
720 and change only the data that they mean to affect.
722 The PUT REST APIs expect the payload passed to replace the resource in
723 AAI. **A GET before PUT is vital in our concurrency scheme. The
724 client will be returned an opaque value per entity which needs to be
725 returned back in the PUT. AAI will reject the PUT or DELETE if the
726 opaque value doesn't match what AAI has stored for that entity.**
728 If an attribute has been added to a model in vN+1, and a GET/PUT of a
729 vN resource is done, AAI should not affect the new attribute (i.e., it
730 should be left unchanged).
735 Concurrency control for AAI is in place.
737 * A client always gets a resource before updating through PUT or deleting it.
739 * All resource updates and deletions are done via the AAI REST APIs
741 * This solution will apply to PUT and DELETE operations.
743 * The resource-version attribute is now in every container
745 * The PATCH REST verb is not subject to concurrency control, because
746 it is only intended to be used by clients who are the definitive
747 source of truth for the attributes they are changing. An update
748 through the PATCH API will however reset the resource-version so
749 clients using PUT and DELETE will not risk updating with stale data.
750 If a client would like us to do concurrency control for PATCH, we
751 will need a feature request. PATCH is recommended for clients who
752 know they are the definitive source of data, as there is less risk
753 of destroying other data.
755 If you use PUT, you MUST send back the entire resource, not just the
756 pieces you know about. This is best illustrated by example. Note:
757 Specific interfaces only show you the data you are responsible for but
758 that does not mean that's all the data that the resource you GET will
759 contain. You are responsible to overlay only your changes and leave
760 everything else untouched.
762 Imagine this is the existing resource:
767 "node-id": "valueOfNodeId",
768 "node-name": "valueOfNodeName",
769 "prov-status": "NVTPROV",
770 "relationship-list": {
773 "related-link": " /aai/v10/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
774 "related-to": "generic-vnf",
775 "relationship-data": [
777 "relationship-key": "generic-vnf.vnf-id",
778 "relationship-value": "generic-vnf-20160902a"
783 "related-link": " /aai/v10/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
784 "related-to": "generic-vnf",
785 "relationship-data": [
787 "relationship-key": "generic-vnf.vnf-id",
788 "relationship-value": "generic-vnf-20161010"
794 "resource-version": "1474912794"
797 And you want to update the name and add a relationship to an l3-network.
799 The payload you need to send back, if you choose PUT, is this. The
800 node-name and the third relationship block is the new data, and the
801 other data and relationships previously existed and must still be PUT.
806 "node-id": "valueOfNodeId",
807 "node-name": "NEWvalueOfNodeName",
808 "prov-status": "NVTPROV",
809 "relationship-list": {
812 "related-link": " /aai/v10/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
813 "related-to": "generic-vnf",
814 "relationship-data": [
816 "relationship-key": "generic-vnf.vnf-id",
817 "relationship-value": "generic-vnf-20160902a"
822 "related-link": " /aai/v10/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
823 "related-to": "generic-vnf",
824 "relationship-data": [
826 "relationship-key": "generic-vnf.vnf-id",
827 "relationship-value": "generic-vnf-20161010"
832 "related-link": " /aai/v10/network/l3-networks/l3-network/network-name-for-me",
833 "related-to": "l3-network",
834 "relationship-data": [
836 "relationship-key": "l3-network.network-name",
837 "relationship-value": "network-name-for-me"
843 "resource-version": "1474912794"
846 A Warning About PUT and Lists
847 -----------------------------
849 The PUT verb is used to both create and replace a resource. A given
850 resource may have child resources (e.g., customers have service
851 subscriptions, generic-vnfs have vf-modules, tenants have vservers and
852 vservers have volumes).
854 The following convention will be followed:
856 If a resource is replaced and there are no tags for children, the
857 children that exist will be left alone.
859 If a resource is replaced and there are tags for children, the
860 children will be replaced by the list passed. If the list is empty,
861 then children will be deleted.
863 Note that the relationship list is a type of child resource. The same
864 conventions are followed. It is especially critical to ensure that
865 you do not send an incomplete relationship list and therefore remove
866 edges in the graph. See `The Relationship-List`_ for more information on
867 relationship lists. See `Concurrency Control`_ for an example of GET followed by
868 PUT containing the entire resource (i.e., overlaying your changes on
869 what already exists so that you don't wipe out other data).
874 To move towards industry standards and to make our APIs easier to use
875 by clients who own specific attributes and do not require AAI to
876 enforce concurrency control around them, the PATCH verb has been
879 .. _RFC 7386: https://tools.ietf.org/html/rfc7386
881 - RFC Algorithm implemented JSON Merge PATCH: `RFC 7386`_
883 - Clients can send a POST with "X-HTTP-Method-Override" = "PATCH" and
884 Content-Type = "application/merge-patch+json" to send a PATCH
886 - PATCH does not support XML
887 - PATCH does not require a resource version to preform these modifications
888 - Clients should only send what they wish to modify and whose value they "own"
889 - PATCH returns a 200 with no response body for success
895 PATCH https://aai.onap:8443/aai/v10/network/generic-vnfs/generic-vnf/cscf0001v
897 "vnf-id": "cscf0001v", <-- This key needs to be here but you cannot modify the key
898 "regional-resource-zone": null,
899 "ipv4-oam-address": "10.10.99.11"
902 This payload would result in the generic-vnf with the vnf-id =
903 cscf0001v having ipv4-oam-address set to "10.10.99.11" and
904 regional-resource-zone having its value removed from the database.
906 Note: PATCH is used only to update attributes on a single node that
907 already exists in AAI. That means it is not applicable to lists of
910 * You do not manage relationships with PATCH. There is a
911 relationship API for that.
913 * You cannot include child objects in a PATCH payload, i.e., you
914 cannot PATCH an l3-network's attributes as well as supply some
915 subnet children or their attributes within the same PATCH payload.
916 You can GET/overlay/PUT parent/child payloads or you can PUT or
917 PATCH each object individually with separate REST API calls.
919 Optional Query Parameters
920 -------------------------
922 A **depth** query parameter is available allowing a query to stop after it
923 has reached a certain point in the graph. This allows clients to
924 minimize the data that is returned to them and make the queries more
925 performant. A depth=0 will return information of the node referred to
926 by the URI only without any information on the children.
932 GET https://aai.onap:8443/aai/v14/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0
934 A **nodes-only** parameter is available allowing a query to only
935 display the properties of the nodes being queried without any
936 relationship information. This allows clients to minimize data that is
937 returned to them and make the queries more performant.
943 GET https://aai.onap:8443/aai/v14/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?nodes-only
945 These parameters may be used in combination with each other.
951 GET https://aai.onap:8443/aai/v14/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0&nodes-only
953 Delete Scope and Edges
954 ----------------------
956 An attempt to remove a node which would result in a delete scope being
957 violated will return error 5.4.6110.
959 The swagger documentation has been updated to show information about
960 delete scope and edges.
962 Here is a subset of the generic-vnf definition that will be used to
963 demonstrate how the delete scope and edges are documented.
965 The following table summarizes actions AAI will take upon deletion of a resource, i.e., its default delete scope:
967 +-----------------------------+--------------------------------------------------------------------+
968 | ERROR_IF_ANY_EDGES | If the resource being deleted has any edges at all |
969 | | an error should be returned |
970 +-----------------------------+--------------------------------------------------------------------+
971 | ERROR_IF_ANY_IN_EDGES | If the resource being deleted has any edges that point IN towards |
972 | | it, an error should be returned |
973 +-----------------------------+--------------------------------------------------------------------+
974 | THIS_NODE_ONLY | Delete the vertex being requested by first deleting its edge to |
975 | | other vertices, but do not delete the other vertices. Note, the |
976 | | delete will be rejected if the deletion target has DEPENDENT |
977 | | children (e.g., tenants that have vservers) |
978 +-----------------------------+--------------------------------------------------------------------+
979 | CASCADE_TO_CHILDREN | Cascade the delete through vertices who have a parentOf |
980 | | relationship to the vertex being deleted, as long as the vertex is |
981 | | orphaned by the delete of its parent |
982 +-----------------------------+--------------------------------------------------------------------+
983 | ERROR_4_IN_EDGES_OR_CASCADE | Error if there are any in edges and, if not, cascade to |
985 +-----------------------------+--------------------------------------------------------------------+
989 * Node A is the object being defined - e.g., generic-vnf
991 * Node B is the XXX of OUT TO XXX
993 * Direction is always Node A OUT TO Node B. Node A has requirement
994 satisfied by Node B and the relationship is the edgelabel
996 * Multiplicity is listed on the OUT TO edges
998 * The former hasDelTarget is indicated by deletion statements that
999 make it clear what gets deleted as a side effect of deleting
1002 * The former isChild is indicated by full statements
1007 *generic-vnf: object*
1008 *General purpose VNF*
1010 *Default Delete Scope*
1014 * *OUT TO vnfc (org.onap.relationships.inventory.Uses, One2Many, delete of generic-vnf will delete vnfc)*
1015 * *IN FROM l-interface (l-interface child of generic-vnf)*
1016 * *IN FROM service-instance*
1021 A Server timeout is implemented for these APIs to make sure the server
1022 did not continue processing the request long after a client times out
1023 on their side. An error code ERR.5.4.7406 will be returned when this
1024 limit is hit. The default value for Resources API is 60 secs. The
1025 clients should set their timeouts accordingly.
1030 The Bulk API allows clients to make multiple requests in a single
1031 transaction. Please look for additional details on the following wiki
1037 Not all queries of the graph are purely GETs of a specific resource
1038 and its related vertexes. The following capabilities are available to
1039 meet more advanced search needs. Please contact the AAI team if you
1040 need another search.
1045 The Nodes Query mechanism was implemented in support of searching the
1046 pservers which do not have the ipv4-oam-ipaddress set. It will allow
1047 nodes to be searched based on certain properties of the nodes. It will
1048 allow search based on properties being set, not set or set to specific
1054 The Generic Query mechanism allows to search for certain nodes of
1055 “include” node types at a specified “depth” from the from a particular
1056 start node of type “start-node-type” identified by specifying its
1059 Model Based Query and Delete
1060 ----------------------------
1062 AAI supports a search and delete capability that allows a client to
1063 retrieve or delete an instance of a service based on the model
1064 subgraph definition provided to AAI by ASDC.
1066 The instance filters must uniquely identify a service instance.
1068 The URL is as follows:
1072 https://{serverRoot}/aai/search/model[?action=DELETE]
1074 .. code-block:: json
1077 "query-parameters": {
1079 "model-invariant-id": "$modelInvariantId",
1083 "model-version-id": "$modelVersionId"
1088 "instance-filters": {
1089 "instance-filter": [
1092 "global-customer-id": "$globalCustID"
1094 "service-instance": {
1095 "resource-version": "$resourceversionID",
1096 "service-instance-id": "$serviceInstanceID"
1098 "service-subscription": {
1099 "service-type": "$serviceType"
1110 These queries provide the ability to upload a json file describing the
1111 inputs and designed output based on traversing the graph in a
1112 particular way. Existing named queries are supported but will be
1113 migrated to custom queries. **Named queries will be deprecated (no new
1114 queries, just support for existing ones) in Dublin and clients will be
1115 asked to migrate to use the custom queries instead.**
1120 This API provides AAI clients an API for complex data retrieval. To
1121 execute a custom query, a client will perform an HTTP PUT request on
1122 the query API and include a payload indicating the starting node and
1123 the query to be run. While the client is performing a PUT request,
1124 this is actually a data query and no data is created or changed.
1129 +----------+-----------------------------+--------------------------+
1130 | No. | Assumption | Approach |
1131 +==========+=============================+==========================+
1132 | 1 | Assume that client will | |
1133 | | not request large amounts | |
1134 | | of data from AAI w/out | |
1135 | | using secondary filters | |
1136 +----------+-----------------------------+--------------------------+
1141 Data has been PUT to AAI prior to the query.
1148 PUT /aai/v$/query?format={format}
1153 The format determines what information is returned from the
1154 query. Acceptable formats are: count, id, pathed, resource,
1155 resource_and_url, or simple.
1160 Provides an count of the objects returned in the query.
1164 PUT /aai/v$/query?format=count
1168 .. code-block:: json
1184 Provides an array of objects containing resource-type (AAI's node
1185 type; i.e., pnf) and a URI using the vertex ID from AAI's graph.
1189 PUT /aai/v$/query?format=id
1193 .. code-block:: json
1198 "resource-type": "complex",
1199 "resource-link": "/aai/v1/resources/id/8159312"
1202 "resource-type": "complex",
1203 "resource-link": "/aai/v1/resources/id/389256"
1211 Provides an array of objects containing resource-type (AAIs node type;
1212 i.e., pnf) and a URI using the AAI REST API pathed URIs
1216 PUT /aai/v$/query?format=pathed
1220 .. code-block:: json
1225 "resource-type": "complex",
1226 "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1229 "resource-type": "complex",
1230 "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1238 Provides each object in the results array in the same format as AAI's
1239 REST API with depth = 1 (first level children and cousin
1244 PUT /aai/v$/query?format=resource
1249 .. code-block:: json
1256 "complex-name": "complex-mccomplexface",
1258 "data-center-code": "CHG",
1259 "latitude": "30.123456",
1260 "longitude": "-78.135344",
1261 "physical-location-id": "complextest1",
1262 "physical-location-type": "lab",
1263 "postal-code": "90210",
1265 "relationship-list": {
1268 "related-link": "/aai/v1/network/zones/zone/zone1",
1269 "related-to": "zone",
1270 "related-to-property": [
1272 "property-key": "zone.zone-name",
1273 "property-value": "zone-name1"
1276 "relationship-data": [
1278 "relationship-key": "zone.zone-id",
1279 "relationship-value": "zone1"
1282 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1285 "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1286 "related-to": "cloud-region",
1287 "related-to-property": [
1289 "property-key": "cloud-region.owner-defined-type"
1292 "relationship-data": [
1294 "relationship-key": "cloud-region.cloud-owner",
1295 "relationship-value": "Cloud-Region"
1298 "relationship-key": "cloud-region.cloud-region-id",
1299 "relationship-value": "Region1"
1302 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1306 "resource-version": "1531233769164",
1308 "street1": "100 Main St",
1309 "street2": "C3-3W03"
1318 Provides each object in the results array in the same format as AAI’s
1319 REST API with depth = 1 (first level children and cousin
1320 relationships) plus the pathed url for the result object in AAI.
1324 PUT /aai/v$/query?format=resource_and_url
1328 .. code-block:: json
1335 "complex-name": "complex-mccomplexface",
1337 "data-center-code": "CHG",
1338 "latitude": "30.123456",
1339 "longitude": "-78.135344",
1340 "physical-location-id": "complextest1",
1341 "physical-location-type": "lab",
1342 "postal-code": "90210",
1344 "relationship-list": {
1347 "related-link": "/aai/v1/network/zones/zone/zone1",
1348 "related-to": "zone",
1349 "related-to-property": [
1351 "property-key": "zone.zone-name",
1352 "property-value": "zone-name1"
1355 "relationship-data": [
1357 "relationship-key": "zone.zone-id",
1358 "relationship-value": "zone1"
1361 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1364 "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1365 "related-to": "cloud-region",
1366 "related-to-property": [
1368 "property-key": "cloud-region.owner-defined-type"
1371 "relationship-data": [
1373 "relationship-key": "cloud-region.cloud-owner",
1374 "relationship-value": "Cloud-REgion"
1377 "relationship-key": "cloud-region.cloud-region-id",
1378 "relationship-value": "Region1"
1381 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1385 "resource-version": "1531233769164",
1387 "street1": "100 Main St",
1388 "street2": "C3-3W03"
1390 "url": "/aai/v11/cloud-infrastructure/complexes/complex/complextest1"
1398 Provides each result object in a simplified format. The node-type,
1399 graph vertex id, pathed url, object properties, and directly related
1400 objects in the graph are all returned. Both direct parent/child
1401 objects and cousin objects are included in the related-to array.
1405 PUT /aai/v$/query?format=simple
1409 .. code-block:: json
1415 "node-type": "complex",
1418 "complex-name": "complex-mccomplexface",
1420 "data-center-code": "CHG",
1421 "latitude": "30.123456",
1422 "longitude": "-78.135344",
1423 "physical-location-id": "complextest1",
1424 "physical-location-type": "lab",
1425 "postal-code": "90210",
1427 "resource-version": "1531233769164",
1429 "street1": "100 Main St",
1430 "street2": "C3-3W03"
1435 "node-type": "zone",
1436 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1437 "url": "/aai/v1/network/zones/zone/zone1"
1441 "node-type": "cloud-region",
1442 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1443 "url": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1"
1447 "node-type": "rack",
1448 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1449 "url": "/aai/v1/cloud-infrastructure/complexes/complex/complextest1/racks/rack/rackname1-1test"
1452 "url": "/aai/v1/cloud-infrastructure/complexes/complex/complextest1"
1460 Provides the results using the graphson standard.
1464 PUT /aai/v$/query?format=graphson
1468 .. code-block:: json
1475 "org.onap.relationships.inventory.LocatedIn": [
1477 "id": "oeioq-oe3f4-74l-1crx3s",
1480 "aai-uuid": "9e75af3d-aa7f-4e8e-a7eb-32d8096f03cc",
1481 "contains-other-v": "NONE",
1482 "delete-other-v": "NONE",
1483 "prevent-delete": "IN",
1488 "id": "216a6j-215u1k-74l-1crx3s",
1491 "aai-uuid": "4b3693be-b399-4355-8747-4ea2bb298dff",
1492 "contains-other-v": "NONE",
1493 "delete-other-v": "NONE",
1494 "prevent-delete": "IN",
1499 "id": "215xjt-215u4o-74l-1crx3s",
1502 "aai-uuid": "958b8e10-6c42-4145-9cc1-76f50bb3e513",
1503 "contains-other-v": "IN",
1504 "delete-other-v": "IN",
1505 "prevent-delete": "NONE",
1515 "id": "1crvgr-1crx3s-6bk5",
1516 "value": 1531231973518
1519 "aai-last-mod-ts": [
1521 "id": "215vkb-1crx3s-6dxh",
1522 "value": 1531233769164
1527 "id": "215urv-1crx3s-69z9",
1533 "id": "1crxfv-1crx3s-6gat",
1534 "value": "/cloud-infrastructure/complexes/complex/complextest1"
1539 "id": "1crvuz-1crx3s-1ybp",
1540 "value": "3959ceca-3a89-4e92-a2ff-073b6f409303"
1545 "id": "1cs0zv-1crx3s-4irp",
1546 "value": "Beverley Hills"
1551 "id": "215wcr-1crx3s-4d8l",
1557 "id": "1cs26j-1crx3s-4l51",
1561 "data-center-code": [
1563 "id": "215ssr-1crx3s-4bnp",
1567 "last-mod-source-of-truth": [
1569 "id": "215vyj-1crx3s-696t",
1570 "value": "aai-AppId"
1575 "id": "1cs2yz-1crx3s-4mpx",
1576 "value": "30.123456"
1581 "id": "1cs3d7-1crx3s-4nid",
1582 "value": "-174.135344"
1585 "physical-location-id": [
1587 "id": "1crzez-1crx3s-4a2t",
1588 "value": "complextest1"
1591 "physical-location-type": [
1593 "id": "1crzt7-1crx3s-4ged",
1599 "id": "1cs1sb-1crx3s-4kcl",
1605 "id": "1cs2kr-1crx3s-4lxh",
1609 "resource-version": [
1611 "id": "215v63-1crx3s-glh",
1612 "value": "1531233769164"
1615 "source-of-truth": [
1617 "id": "1crv2j-1crx3s-6epx",
1623 "id": "1cs1e3-1crx3s-4jk5",
1629 "id": "1cs07f-1crx3s-4h6t",
1630 "value": "100 Main St"
1635 "id": "1cs0ln-1crx3s-4hz9",
1645 Optional Query Parameters
1646 ~~~~~~~~~~~~~~~~~~~~~~~~~
1651 You can pass the depth query parameter to specify how many levels of
1652 children/grandchildren to return. The default depth is 1.
1656 PUT /aai/v$/query?format={}&depth=0
1661 You can pass the nodesOnly query parameter to have the output only
1662 contain the object properties with no relationships.
1666 PUT /aai/v$/query?format={format}&nodesOnly=true
1671 You can pass a subgraph query parameter that determines the behavior
1672 of the output. Using subgraph=prune returns all of the objects from
1673 the query and only the edges between those objects. Using
1674 subgraph=star returns all of the objects from the query plus all of
1675 the objects they relate to.
1677 The default is subgraph=star
1681 PUT /aai/v$/query?format={format}&subgraph={subgraph}
1686 +--------------------------+--------------------------------------------------------------------------------------+
1687 | X-FromAppID={client ID}| Unique application identifier. |
1688 +--------------------------+--------------------------------------------------------------------------------------+
1689 | X-TransactionID={UUDID} | must be a UUID and unique to each transaction within the context of an X-FromAppID. |
1690 +--------------------------+--------------------------------------------------------------------------------------+
1691 | Content-Type={format} | format of the request. Should be application/json or application/xml. |
1692 +--------------------------+--------------------------------------------------------------------------------------+
1693 | Accept={format} | format of the response. Should be application/json or application/xml. |
1694 +--------------------------+--------------------------------------------------------------------------------------+
1699 Typically the query payload will include both a "start" and a "query"
1700 portion. The "start" can indicate one or more starting nodes in the
1701 graph. If multiple nodes are specified, the result will contain the
1702 query results for all of the start nodes. The "query" indicates the
1703 name of the query to be run and also takes query parameters depending
1704 on the query. Please reference the queries on the AAI wiki for
1705 specific saved queries and how they should be usServer Timeout A
1706 Server timeout is implemented for these APIs to make sure the server
1707 did not continue processing the request long after a client times out
1708 on their side. An error code ERR.5.4.7406 will be returned when this
1709 limit is hit. The default value for Traversal API is 60 secs. The
1710 clients should set their timeouts accordingly.
1712 List of Queries and Payloads
1713 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1715 For a full list of available custom queries, please refer to our
1716 `Custom Queries <customQueries.html>`_ document
1721 In working with AAI's standard REST API, you may have noticed that
1722 certain API paths have a hierarchy to them and require a client to
1723 know multiple object keys to preform GETs. The nodes API allows for
1724 more freedom in querying AAI, allowing clients to circumvent the need
1725 to know every key in the hierarchy.
1727 See `Nodes Query <nodesQuery.html>`_ for more information.