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 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.).
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).
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
40 Deprecation Warnings and History
41 ================================
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)
50 Clients can call the REST API with any valid path ending in /relationship-list to retrieve just the relationship-list for that object.
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
58 Custom Queries for replacing named queries are now available for clients to switch to.
63 - A new API called recents API is now available mostly intended for DCAE use.
65 - A new and improved bulk api interface is also available now.
67 - More details on the above APIs can be found in wiki pages referenced
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
77 - The deletion rules are now applied to all the nodes that will be
78 deleted by the delete request.
80 For example, if the graph is:
86 If nodeA is parent of nodeB and nodeB is parent of nodeC
88 +------+---------------------+
89 |nodeA | CASCADE_TO_CHILDREN |
90 +------+---------------------+
91 |nodeB | CASCADE_TO_CHILDREN |
92 +------+---------------------+
93 |nodeC | ERROR_IF_IN_EDGES |
94 +------+---------------------+
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.
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.
105 - To handle a risk identified by Fortify scans, a maxOccurs of 5000
106 was added to the XSD.
111 - DELETE request will generate a DMAAP event for each node deleted
112 (not just the for which the DELETE request was made)
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.
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.
132 "relationship-list": {
135 "related-link": "/aai/v12/cloud-infrastructure/complexes/complex/6d8f945d-8bd2-4fa2-ad37-36b21fc8fb23-PS2418",
136 "related-to": "complex",
137 "relationship-data": [
139 "relationship-key": "complex.physical-location-id",
140 "relationship-value": "6d8f945d-8bd2-4fa2-ad37-36b21fc8fb23-PS2418"
143 "relationship-label": "locatedIn"
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
158 - The edge tag query will be retired.
160 Notable attribute and/or valid value changes (generally also impacts
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.
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
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
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
186 - Normal impacts due to renaming or adding attributes, splitting
187 objects, etc. Please see swagger documentation for objects of
190 - In v11, clients that require lineage, children, or relationship
191 information need to subscribe to a different DMaaP topic than the
196 - The related-link will be a URI and thus not contain
197 https://{serverroot} (impacts events)
199 - The related-link will be used on a PUT as the "first choice" to
200 identify the related resource. The relationship-data structure, which
201 contains the unordered set of keys, is still an acceptable way to
202 relate two objects but, *if both the relationship-data and the
203 related-link are passed, and they don't agree, the related-link will
204 be used without warning that the data is inconsistent*.
206 - The relationship-data will be ignored on PUT.
211 In the future, the hope is that individual node definitions will be
212 separately versioned from API behavior and from one another (e.g.,
213 vserver hasn't changed in many releases and so doesn't need to have
214 its "definition" version updated).
216 Because relationships are starting to become more complex, it may be
217 necessary for AAI to expose to clients the exact relationship between
218 two nodes. This will likely be done with a relationship-type
219 attribute of relationships in the relationship-list.
221 To support the concept of events getting generated on specific changed
222 items, AAI will be migrating towards a model of asking clients to do
223 the most granular PUTs possible rather than leveraging the nested
224 elements of a tree structure.
226 The vce, port-group, cvlan-tag, newvce, vpe, oam-network, and
227 dvs-switch objects will eventually be deprecated in favor of
228 generic-vnf, l3-network, ctag-assignment, segmentation-assignment, and
231 L3-network will eventually be replaced by virtual-network.
233 How to Use this Document
234 ========================
236 The only attributes in our objects that are declared required are
237 those which we know will be present at the creation of each object and
238 which are needed to support the construction of the AAI Graph. This
239 does not imply that one of AAI's clients doesn't need data.
241 When you click on the API documentation, you will see the Summary of
242 APIs broken down by namespace (e.g., cloud-infrastructure, business,
243 network, service-design-and-creation). You can search for **Tag:**
244 (matching the explicit case) to move from namespace to namespace through
247 Search for **Paths** to skip past the Summary section where there will
248 be more detail about each API. Query parameters are provided here, as
249 well as links to our error codes.
251 Search for **Schema definitions** to see the definitions of the
252 payloads. In your browser URL, you can type /#/definitions/node-name at
253 the end of the html address to skip directly to a payload definition.
255 Note that the schema definitions now contain information about the
256 delete scope of a node, edges, and some related node information.
257 Given this information can now be generated, it is no longer repeated
260 Once AAI has a model and configured it, the AAI development server can
261 be used to generate sample XML and JSON payloads, according to the
262 Accept header passed in the request. This is done by calling the
263 "plural" version of an API followed by the word example (e.g.,
264 /vserver/vservers/example). This returns a GET result array with one
265 entry. That single entry can be sent in a PUT request with actual data
266 (the resource-id does not need to be in the PUT payload as it is on the
269 Finally, custom queries that are not simple GETs of a resource must be
270 identified to AAI as separate user stories. This includes searching
271 for a resource with other attributes on the same resource, as well as
272 searching for resources based on their relationship with other
281 Cloud Infrastructure Domain
282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
284 The Cloud Infrastructure domain (cloud-infrastructure) represents the
285 assets managed within a cloud site. This includes the complex, the
286 physical servers, the availability zones, oam-networks, tenants, and
287 vserver-related resources (vservers, flavors, images, etc.).
289 Tenants, oam-networks, availability-zones, volume-groups, images,
290 flavors, and dvs-switches will have cloud-region as its parent node.
295 The network namespace contains virtual and physical network resources
296 as well as connection resources such as physical links, logical links,
299 The vce/port-group/cvlan-tag tree represents an immature model that
300 blended several resources together in ways that were expedient but
301 which need to be re-evaluated. A newvce object exists which was the
302 basis of the generic-vnf object. Future efforts will attempt to
303 migrate vce and vpe into generic-vnf.
308 The business namespace captures customers, service-subscriptions, and
309 service-instances. This domain is immature and will be evolving as
310 service design and creation starts to gel.
312 Customers and service-subscriptions in particular will be evolving
313 soon. Any service that is customer facing will see customer and
314 service-subscription data offboarding to BSSs. The
315 service-instance-id will be the "join point" within the BSS to
316 correlate the service-instance to the product and customer. Services
317 that are for infrastructure purposes will have a new entity, an
318 owning-entity, to replace the customer. The owning-entity will be
319 related to the SDC service models that use it.
321 Service Design and Creation
322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
324 The service design and creation namespace captures data we invented
325 based on what we thought SDC would eventually provide. The structure
326 of that data is definitely not what the current plans are for SDC
327 however we need to at least capture the spirit of what's intended and
328 communicate that across ONAP sub components that need it.
330 To date, there are only five containers:
332 1. Service-capabilities capture the pairings of service to
333 resources. At the time of construction, the only data we had to
334 denote service was the service-type from SO. The vnf-type is the
337 2. Service captures the service model instances and this will be
338 deprecated in the future as things mature
340 3. Vnf-image captures information about the resource image needed for
341 a VNF. This was created due to there being no info available on
342 the vservers that run on uCPE
344 4. Models captures model definitions (subgraph definitions using the
347 5. named-queries capture subgraph definitions that allow different
348 data to be retrieved for a given type of asset
353 All REST APIs must be called using https.
355 HTTPS Basic Authentication will be used to authenticate clients. The
356 remote user from the HTTP Servlet Request is used against an AAI
357 policy to see if the authenticated user is authorized for the resource
358 and actions being request.
360 Client should use credentials provided to their system via AAF.
365 The following will be used for logging and interface diagnostic purposes.
367 * X-FromAppId Unique Application ID assigned to the user of these APIs
368 * X-TransactionId Unique ID that identifies an API request
370 The X-FromAppId will be assigned to each application by the AAI team.
371 The X-TransactionId must be unique to each transaction within the
372 context of an X-FromAppId.
374 SO, SDN-C, and AAI have agreed to use the Java UUID class to generate
375 unique ids for X-TransactionId.
377 The Accept and Content-type header should be set to either
378 application/json or application/xml except as documented for PATCH.
380 Response Codes and Error Handling
381 ---------------------------------
383 AAI will use the following HTTP codes
391 - 204 – Success, no payload returned
396 - 405 – Method Not Allowed
397 - 409 - The request could not be completed due to a conflict with the
398 current state of the target resource. This code is used in situations
399 where the user might be able to resolve the conflict and resubmit the
400 request. If the resource version doesn’t match AAI or a required
401 resource version isn't sent but should have been
402 - 410 - You are using a version of the API that has been retired
403 - 412 – Precondition failed (If the resource version doesn’t match AAI or arequired resource version isn't sent but should have been
404 - 415 – Unsupported Media Type
405 - 500 - Internal Server Error
407 Successful PUT responses shall return the following codes:
408 * 200 (OK): used when an existing resource has been modified and
409 there is a response buffer
410 * 201 (Created): MUST be used when a new resource is created
411 * 202 (Accepted): used when AAI completed the action requested but
412 may have taken other actions as well, which are returned in the
414 * 204 (No Content): used when the existing resource has been modified
415 and there is no response buffer
417 Successful DELETE responses shall return the following codes:
418 * 200 (OK): for a successful response if the response includes an
419 entity describing the status.
420 * 204 (No Content): if the action has been enacted but the response
421 does not include an entity.
423 Successful GET responses shall return the following codes:
424 * 200 (OK): for a successful response for a resource that has been found
425 * 404 (Not Found) for a successful response retrieving a list of
426 items and there were no items found, i.e., the GET of the specific
427 plural resource was not found
428 * 404 (Not Found): when a specific resource was not found
431 * 400 Bad Request will be returned if headers are missing
432 * 404 Not Found will be returned if an unknown URL is used
434 In addition, the standard response buffer will be structured as follows unless otherwise specified.
435 There are two types of requestErrors.
437 * Service Exceptions – These exceptions occur when a service is
438 unable to process a request and retrying the request will result in
439 a consistent failure (e.g., an application provides invalid input).
440 * Policy Exceptions – These exceptions occur when a policy criteria
441 has not been met (e.g., the (N+1)th request arrives when an
442 application’s service level agreement only allows N transactions
445 Italics are specific to the error returned, and generally described in the notes
449 HTTP/1.1 405 *Method Not Allowed*
450 Content-Type: application/json
451 Content-Length: nnnnn
452 Date: *Thu, 04 Jun 2009 02:51:59 GMT*
456 “messageId”:"*POL8007*",
457 “text”:”*The resource was invoked with an unsupported operation: %1.*”,
458 “variables”: [”*PUT*”]
464 a. On the first line, substitute the appropriate status response code.
466 b. On the second line, substitute the appropriate content type.
468 c. Express the requestError structure in the required content type (e.g., either JSON or XML). AAI will use JSON.
470 d. ‘requestError’ contains either a ‘policyException’ or a ‘serviceException’ structure.
474 In 1512, AAI is introducing a response payload that is possible during a successful PUT. This payload is used to inform the client that, while AAI completed the action requested, the result could be interpreted as a warning or request for additional action, as negotiated with the client.
476 Sample response to a vserver PUT where the pserver and complex did not exist:
480 {"responseMessages": {"responseMessage": [
482 "messageId": "INF0003",
483 "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
484 "variables": {"variable": [
488 "physical-location-id=fakeccwcomplex",
489 "Added prerequisite object to db:complex",
494 "messageId": "INF0003",
495 "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
496 "variables": {"variable": [
500 "hostname=fakeccwpserver",
501 "Added prerequisite object to db:pserver",
507 Referential Integrity
508 ---------------------
510 AAI is primarily a view to the relationships between instances of
511 services, physical and virtual components, etc. It stores just the
512 details it needs to be efficient to its tasks and knows how to get
513 more details if needed.
515 As such, a transaction sent to AAI may be refused if would break
516 referential integrity. The referential integrity rules of AAI are
517 still evolving as we understand the services and customers that will
520 AAI uses a graph database on a NoSQL data store. The following are
523 * Some vertices are exposed to the outside world through APIs, others
524 are internal to how we store the data (i.e., it may look like one
525 resource to our customers but it is expressed as more than one
528 * Vertices that are internal to AAI will be deleted when the parent
529 vertex is deleted, if deletion of the parent leaves the child vertex
532 * Vertices that are exposed need to be managed using specific rules
535 * Vertices may have more than just parent/child relationships. One
536 example is a vserver, which will be owned by a tenant and used by a
540 URLs Sent To and Retrieved From A&AI
541 ------------------------------------
543 A&AI receives URLs from clients that point back to that client in
544 order to get more details about the data sent to A&AI. A&AI expects
545 the URLs sent by clients (e.g., self links) to be URL encoded
546 (UTF-8) and A&AI will store them unchanged.
548 URIs that A&AI constructs that point to A&AI resources will be
549 returned URLEncoded (UTF-8) to clients. This affects URIs in
550 relationship lists and search results. Note that A&AI used to send
551 URLs but, as reported in the 1707 impacts, these will now be URIs.
553 A&AI expects space to be %20, and not plus(+).
555 The Relationship-List
556 ---------------------
558 The REST interface does not lend itself to creating more than
559 parent-child relationships and the backend structure of AAI is a
560 graph. A goal of AAI, and shared with ONAP, is to do as little coding
561 as possible to introduce a new service into the service design and
562 creation environment.
564 To that end, we've introduced a relationship-list structure. AAI will
565 ask its clients to provide certain data in the relationship-list
568 Each relationship has a related-to attribute and a list of key/value
569 pairs. The related-to attribute identifies the node type that the
570 resource being acted on is to be related to using the data in the
571 key/value pairs. AAI will encode a set of rules for each resource
572 type to verify that only valid edges are being made. AAI will keep
573 the directionality and cardinality, and the edge attributes within its
574 own logic. In the near future, the definition of relationships, their
575 validity, and cardinality will be captured in the ONAP TOSCA models.
577 AAI also has a concept of a related-to category. To date, the only
578 category is vnf. The vnf category is used as the related-to value to
579 indicate that the relationship being establish is to a Virtual Network
580 Function of unknown type. The vnf-id happens to be unique for all
581 services across all nodes in the graph. By providing vnf.vnf-id with
582 a specific value, AAI can look at all VNFs in the graph and find the
583 appropriate vertex. Note that this only applies to PUTs.
585 Category vnf is used for node types of vce, vpe, and generic-vnf.
587 If an attempt is made to add a relationship to a node that doesn't
588 exist (e.g., from a vserver to a vnf, and the vnf doesn't exist), a
589 unique message Id (3003) will be returned with a specific error code
590 (ERR.5.4.6129). Arguments will tell the client which node type was
591 missing (e.g., vnf) and the key data for that node type (vnf.vnf-id).
593 Single relationships can be PUT to the graph in the following way:
597 https://{serverRoot}/{namespace}/{resource}/relationship-list/relationship
603 https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/pserver-123456789-01/p-interfaces/p-interface/p-interface-name-123456789-01/l-interfaces/l-interface/l-interface-name-123456789-01/relationship-list/relationship
605 with a payload containing the relationship information.
607 AAI will accept and give preference to the related-link URI
613 <relationship xmlns="http://org.onap.aai.inventory/vX">
614 <related-link>*/aai/v16/network/logical-links/logical-link/logical-link-123456789-01*</related-link>
615 <related-to>logical-link</related-to>
617 <relationship-key>logical-link.link-name</relationship-key>
618 <relationship-value>logical-link-123456789-01</relationship-value>
627 "related-link": " /aai/v16/network/logical-links/logical-link/logical-link-123456789-01",
628 "related-to": "logical-link",
629 "relationship-data": [
631 "relationship-key": "logical-link.link-name",
632 "relationship-value": " logical-link-123456789-01"
640 The util domain is where AAI locates utility functions. There is
641 currently one utility function, echo, which serves as a ping test that
642 authenticated authorized clients can call to ensure there is
643 connectivity with AAI.
645 The URL for the echo utility is:
649 https://aai.onap:8443/aai/util/echo
651 If the response is unsuccessful, an error will be returned following
654 The successful payload returns the X-FromAppId and X-TransactionId
657 Successful XML Response Payload
658 -------------------------------
665 <messageId>INF0001</messageId>
666 <text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text>
668 <variable>CCW</variable>
669 <variable>CCW33335</variable>
670 <variable>Successful health check:OK</variable>
671 <variable>0.0.0002</variable>
677 Successful JSON Response Payload
678 --------------------------------
683 "responseMessages": {
686 "messageId": "INF0001",
687 "text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)",
692 "Successful health check:OK",
701 AAI Resources CRUD APIs
702 =======================
704 The API structure is composed of:
706 * The HTTP command, which indicates the operation to perform
707 * The HTTP URI, which defines what object this operation is related to
708 * The HTTP version, which MUST be 1.1
710 Available HTTP commands are:
712 * PUT: used to create or update an object
713 * DELETE: used to delete an object or a set of objects
714 * GET : used to query an object or set of objects
715 * PATCH : used to update specific fields owned by the client doing the update
717 The HTTP URI is built according to this pattern:
721 https://{serverRoot}/{namespace}/{resource}
723 * {serverRoot} refers to the server base url: hostname+port+base path+version. Port and base path are OPTIONAL but AAI will use port 8443 and base path aai. Note that the base path may change before production, so please make this configurable. Versions will change as releases are made.
725 * {namespace} refers to the API namespace. Supported namespaces are cloud-infrastructure, business, service-design-and-creation, and network
727 * {resource} refers to how the object is identified according to the namespace specifications.
733 GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}
738 `Offered APIs <../platform/offeredapis.html>`_
743 Given AAI is largely a correlation engine among disparate inventory
744 types, AAI will for the most part accept values as they are sent,
745 without validating the format or value of the input. **It is
746 incumbent upon the source of truth to provide valid information to
749 Clients should either use the PATCH API to only change
750 the attribute values they mean to change, or do a GET prior to a PUT
751 and change only the data that they mean to affect.
753 The PUT REST APIs expect the payload passed to replace the resource in
754 AAI. **A GET before PUT is vital in our concurrency scheme. The
755 client will be returned an opaque value per entity which needs to be
756 returned back in the PUT. AAI will reject the PUT or DELETE if the
757 opaque value doesn't match what AAI has stored for that entity.**
759 If an attribute has been added to a model in vN+1, and a GET/PUT of a
760 vN resource is done, AAI should not affect the new attribute (i.e., it
761 should be left unchanged).
766 Concurrency control for AAI is in place.
768 * A client always gets a resource before updating through PUT or deleting it.
770 * All resource updates and deletions are done via the AAI REST APIs
772 * This solution will apply to PUT and DELETE operations.
774 * The resource-version attribute is now in every container
776 * The PATCH REST verb is not subject to concurrency control, because
777 it is only intended to be used by clients who are the definitive
778 source of truth for the attributes they are changing. An update
779 through the PATCH API will however reset the resource-version so
780 clients using PUT and DELETE will not risk updating with stale data.
781 If a client would like us to do concurrency control for PATCH, we
782 will need a feature request. PATCH is recommended for clients who
783 know they are the definitive source of data, as there is less risk
784 of destroying other data.
786 If you use PUT, you MUST send back the entire resource, not just the
787 pieces you know about. This is best illustrated by example. Note:
788 Specific interfaces only show you the data you are responsible for but
789 that does not mean that's all the data that the resource you GET will
790 contain. You are responsible to overlay only your changes and leave
791 everything else untouched.
793 Imagine this is the existing resource:
798 "node-id": "valueOfNodeId",
799 "node-name": "valueOfNodeName",
800 "prov-status": "NVTPROV",
801 "relationship-list": {
804 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
805 "related-to": "generic-vnf",
806 "relationship-data": [
808 "relationship-key": "generic-vnf.vnf-id",
809 "relationship-value": "generic-vnf-20160902a"
814 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
815 "related-to": "generic-vnf",
816 "relationship-data": [
818 "relationship-key": "generic-vnf.vnf-id",
819 "relationship-value": "generic-vnf-20161010"
825 "resource-version": "1474912794"
828 And you want to update the name and add a relationship to an l3-network.
830 The payload you need to send back, if you choose PUT, is this. The
831 node-name and the third relationship block is the new data, and the
832 other data and relationships previously existed and must still be PUT.
837 "node-id": "valueOfNodeId",
838 "node-name": "NEWvalueOfNodeName",
839 "prov-status": "NVTPROV",
840 "relationship-list": {
843 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
844 "related-to": "generic-vnf",
845 "relationship-data": [
847 "relationship-key": "generic-vnf.vnf-id",
848 "relationship-value": "generic-vnf-20160902a"
853 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
854 "related-to": "generic-vnf",
855 "relationship-data": [
857 "relationship-key": "generic-vnf.vnf-id",
858 "relationship-value": "generic-vnf-20161010"
863 "related-link": " /aai/v16/network/l3-networks/l3-network/network-name-for-me",
864 "related-to": "l3-network",
865 "relationship-data": [
867 "relationship-key": "l3-network.network-name",
868 "relationship-value": "network-name-for-me"
874 "resource-version": "1474912794"
877 A Warning About PUT and Lists
878 -----------------------------
880 The PUT verb is used to both create and replace a resource. A given
881 resource may have child resources (e.g., customers have service
882 subscriptions, generic-vnfs have vf-modules, tenants have vservers and
883 vservers have volumes).
885 The following convention will be followed:
887 If a resource is replaced and there are no tags for children, the
888 children that exist will be left alone.
890 If a resource is replaced and there are tags for children, the
891 children will be replaced by the list passed. If the list is empty,
892 then children will be deleted.
894 Note that the relationship list is a type of child resource. The same
895 conventions are followed. It is especially critical to ensure that
896 you do not send an incomplete relationship list and therefore remove
897 edges in the graph. See `The Relationship-List`_ for more information on
898 relationship lists. See `Concurrency Control`_ for an example of GET followed by
899 PUT containing the entire resource (i.e., overlaying your changes on
900 what already exists so that you don't wipe out other data).
905 To move towards industry standards and to make our APIs easier to use
906 by clients who own specific attributes and do not require AAI to
907 enforce concurrency control around them, the PATCH verb has been
910 .. _RFC 7386: https://tools.ietf.org/html/rfc7386
912 - RFC Algorithm implemented JSON Merge PATCH: `RFC 7386`_
914 - Clients can send a POST with "X-HTTP-Method-Override" = "PATCH" and
915 Content-Type = "application/merge-patch+json" to send a PATCH
917 - PATCH does not support XML
918 - PATCH does not require a resource version to perform these modifications
919 - Clients should only send what they wish to modify and whose value they "own"
920 - PATCH returns a 200 with no response body for success
926 PATCH https://aai.onap:8443/aai/v16/network/generic-vnfs/generic-vnf/cscf0001v
928 "vnf-id": "cscf0001v", <-- This key needs to be here but you cannot modify the key
929 "regional-resource-zone": null,
930 "ipv4-oam-address": "10.10.99.11"
933 This payload would result in the generic-vnf with the vnf-id =
934 cscf0001v having ipv4-oam-address set to "10.10.99.11" and
935 regional-resource-zone having its value removed from the database.
937 Note: PATCH is used only to update attributes on a single node that
938 already exists in AAI. That means it is not applicable to lists of
941 * You do not manage relationships with PATCH. There is a
942 relationship API for that.
944 * You cannot include child objects in a PATCH payload, i.e., you
945 cannot PATCH an l3-network's attributes as well as supply some
946 subnet children or their attributes within the same PATCH payload.
947 You can GET/overlay/PUT parent/child payloads or you can PUT or
948 PATCH each object individually with separate REST API calls.
950 Optional Query Parameters
951 -------------------------
953 A **depth** query parameter is available allowing a query to stop after it
954 has reached a certain point in the graph. This allows clients to
955 minimize the data that is returned to them and make the queries more
956 performant. A depth=0 will return information of the node referred to
957 by the URI only without any information on the children.
963 GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0
965 A **nodes-only** parameter is available allowing a query to only
966 display the properties of the nodes being queried without any
967 relationship information. This allows clients to minimize data that is
968 returned to them and make the queries more performant.
974 GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?nodes-only
976 These parameters may be used in combination with each other.
982 GET https://aai.onap:8443/aai/v14/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0&nodes-only
984 Delete Scope and Edges
985 ----------------------
987 An attempt to remove a node which would result in a delete scope being
988 violated will return error 5.4.6110.
990 The swagger documentation has been updated to show information about
991 delete scope and edges.
993 Here is a subset of the generic-vnf definition that will be used to
994 demonstrate how the delete scope and edges are documented.
996 The following table summarizes actions AAI will take upon deletion of a resource, i.e., its default delete scope:
998 +-----------------------------+--------------------------------------------------------------------+
999 | ERROR_IF_ANY_EDGES | If the resource being deleted has any edges at all |
1000 | | an error should be returned |
1001 +-----------------------------+--------------------------------------------------------------------+
1002 | ERROR_IF_ANY_IN_EDGES | If the resource being deleted has any edges that point IN towards |
1003 | | it, an error should be returned |
1004 +-----------------------------+--------------------------------------------------------------------+
1005 | THIS_NODE_ONLY | Delete the vertex being requested by first deleting its edge to |
1006 | | other vertices, but do not delete the other vertices. Note, the |
1007 | | delete will be rejected if the deletion target has DEPENDENT |
1008 | | children (e.g., tenants that have vservers) |
1009 +-----------------------------+--------------------------------------------------------------------+
1010 | CASCADE_TO_CHILDREN | Cascade the delete through vertices who have a parentOf |
1011 | | relationship to the vertex being deleted, as long as the vertex is |
1012 | | orphaned by the delete of its parent |
1013 +-----------------------------+--------------------------------------------------------------------+
1014 | ERROR_4_IN_EDGES_OR_CASCADE | Error if there are any in edges and, if not, cascade to |
1016 +-----------------------------+--------------------------------------------------------------------+
1020 * Node A is the object being defined - e.g., generic-vnf
1022 * Node B is the XXX of OUT TO XXX
1024 * Direction is always Node A OUT TO Node B. Node A has requirement
1025 satisfied by Node B and the relationship is the edgelabel
1027 * Multiplicity is listed on the OUT TO edges
1029 * The former hasDelTarget is indicated by deletion statements that
1030 make it clear what gets deleted as a side effect of deleting
1033 * The former isChild is indicated by full statements
1038 *generic-vnf: object*
1039 *General purpose VNF*
1041 *Default Delete Scope*
1045 * *OUT TO vnfc (org.onap.relationships.inventory.Uses, One2Many, delete of generic-vnf will delete vnfc)*
1046 * *IN FROM l-interface (l-interface child of generic-vnf)*
1047 * *IN FROM service-instance*
1052 A Server timeout is implemented for these APIs to make sure the server
1053 did not continue processing the request long after a client times out
1054 on their side. An error code ERR.5.4.7406 will be returned when this
1055 limit is hit. The default value for Resources API is 60 secs. The
1056 clients should set their timeouts accordingly.
1061 The Bulk API allows clients to make multiple requests in a single
1062 transaction. Please look for additional details on the following wiki
1063 page: `Bulk API <bulkApi.html>`_
1068 In working with A&AI's standard REST API, you may have noticed that
1069 certain API paths have a hierarchy to them and require a client to
1070 know multiple object keys to preform GETs. For example: the vserver
1071 object is under tenant, which is itself under cloud-region. If you
1072 wanted to look up a vserver by name, you would still need to know the
1073 tenant-id and cloud-region-id (and cloud-owner) in order to
1074 successfully perform that GET. The nodes API allows for more freedom
1075 in querying A&AI, allowing clients to circumvent the need to know
1076 every key in the hierarchy.
1078 See `Nodes API <nodesApi.html>`_ for more information.
1083 Not all queries of the graph are purely GETs of a specific resource
1084 and its related vertexes. The following capabilities are available to
1085 meet more advanced search needs. Please contact the AAI team if you
1086 need another search.
1091 The Nodes Query mechanism was implemented in support of searching the
1092 pservers which do not have the ipv4-oam-ipaddress set. It will allow
1093 nodes to be searched based on certain properties of the nodes. It will
1094 allow search based on properties being set, not set or set to specific
1097 Please reference `Nodes Query <nodesQuery.html>`_ for details on the
1098 API and test queries.
1104 The Generic Query mechanism allows to search for certain nodes of
1105 “include” node types at a specified “depth” from the from a particular
1106 start node of type “start-node-type” identified by specifying its
1111 Model Based Query and Delete
1112 ----------------------------
1114 AAI supports a search and delete capability that allows a client to
1115 retrieve or delete an instance of a service based on the model
1116 subgraph definition provided to AAI by ASDC.
1118 The instance filters must uniquely identify a service instance.
1120 The URL is as follows:
1124 https://{serverRoot}/aai/search/model[?action=DELETE]
1126 .. code-block:: json
1129 "query-parameters": {
1131 "model-invariant-id": "$modelInvariantId",
1135 "model-version-id": "$modelVersionId"
1140 "instance-filters": {
1141 "instance-filter": [
1144 "global-customer-id": "$globalCustID"
1146 "service-instance": {
1147 "resource-version": "$resourceversionID",
1148 "service-instance-id": "$serviceInstanceID"
1150 "service-subscription": {
1151 "service-type": "$serviceType"
1162 These queries provide the ability to upload a json file describing the
1163 inputs and designed output based on traversing the graph in a
1164 particular way. Existing named queries are supported but will be
1165 migrated to custom queries. **Named queries will be deprecated (no new
1166 queries, just support for existing ones) in Dublin and clients will be
1167 asked to migrate to use the custom queries instead.**
1172 This API provides AAI clients an API for complex data retrieval. To
1173 execute a custom query, a client will perform an HTTP PUT request on
1174 the query API and include a payload indicating the starting node and
1175 the query to be run. While the client is performing a PUT request,
1176 this is actually a data query and no data is created or changed.
1181 +----------+-----------------------------+--------------------------+
1182 | No. | Assumption | Approach |
1183 +==========+=============================+==========================+
1184 | 1 | Assume that client will | |
1185 | | not request large amounts | |
1186 | | of data from AAI w/out | |
1187 | | using secondary filters | |
1188 +----------+-----------------------------+--------------------------+
1193 Data has been PUT to AAI prior to the query.
1200 PUT /aai/v$/query?format={format}
1205 The format determines what information is returned from the
1206 query. Acceptable formats are: count, id, pathed, resource,
1207 resource_and_url, or simple.
1212 Provides an count of the objects returned in the query.
1216 PUT /aai/v$/query?format=count
1220 .. code-block:: json
1236 Provides an array of objects containing resource-type (AAI's node
1237 type; i.e., pnf) and a URI using the vertex ID from AAI's graph.
1241 PUT /aai/v$/query?format=id
1245 .. code-block:: json
1250 "resource-type": "complex",
1251 "resource-link": "/aai/v1/resources/id/8159312"
1254 "resource-type": "complex",
1255 "resource-link": "/aai/v1/resources/id/389256"
1263 Provides an array of objects containing resource-type (AAIs node type;
1264 i.e., pnf) and a URI using the AAI REST API pathed URIs
1268 PUT /aai/v$/query?format=pathed
1272 .. code-block:: json
1277 "resource-type": "complex",
1278 "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1281 "resource-type": "complex",
1282 "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1290 Provides each object in the results array in the same format as AAI's
1291 REST API with depth = 1 (first level children and cousin
1296 PUT /aai/v$/query?format=resource
1301 .. code-block:: json
1308 "complex-name": "complex-mccomplexface",
1310 "data-center-code": "CHG",
1311 "latitude": "30.123456",
1312 "longitude": "-78.135344",
1313 "physical-location-id": "complextest1",
1314 "physical-location-type": "lab",
1315 "postal-code": "90210",
1317 "relationship-list": {
1320 "related-link": "/aai/v1/network/zones/zone/zone1",
1321 "related-to": "zone",
1322 "related-to-property": [
1324 "property-key": "zone.zone-name",
1325 "property-value": "zone-name1"
1328 "relationship-data": [
1330 "relationship-key": "zone.zone-id",
1331 "relationship-value": "zone1"
1334 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1337 "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1338 "related-to": "cloud-region",
1339 "related-to-property": [
1341 "property-key": "cloud-region.owner-defined-type"
1344 "relationship-data": [
1346 "relationship-key": "cloud-region.cloud-owner",
1347 "relationship-value": "Cloud-Region"
1350 "relationship-key": "cloud-region.cloud-region-id",
1351 "relationship-value": "Region1"
1354 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1358 "resource-version": "1531233769164",
1360 "street1": "100 Main St",
1361 "street2": "C3-3W03"
1370 Provides each object in the results array in the same format as AAI’s
1371 REST API with depth = 1 (first level children and cousin
1372 relationships) plus the pathed url for the result object in AAI.
1376 PUT /aai/v$/query?format=resource_and_url
1380 .. code-block:: json
1387 "complex-name": "complex-mccomplexface",
1389 "data-center-code": "CHG",
1390 "latitude": "30.123456",
1391 "longitude": "-78.135344",
1392 "physical-location-id": "complextest1",
1393 "physical-location-type": "lab",
1394 "postal-code": "90210",
1396 "relationship-list": {
1399 "related-link": "/aai/v16/network/zones/zone/zone1",
1400 "related-to": "zone",
1401 "related-to-property": [
1403 "property-key": "zone.zone-name",
1404 "property-value": "zone-name1"
1407 "relationship-data": [
1409 "relationship-key": "zone.zone-id",
1410 "relationship-value": "zone1"
1413 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1416 "related-link": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1417 "related-to": "cloud-region",
1418 "related-to-property": [
1420 "property-key": "cloud-region.owner-defined-type"
1423 "relationship-data": [
1425 "relationship-key": "cloud-region.cloud-owner",
1426 "relationship-value": "Cloud-REgion"
1429 "relationship-key": "cloud-region.cloud-region-id",
1430 "relationship-value": "Region1"
1433 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1437 "resource-version": "1531233769164",
1439 "street1": "100 Main St",
1440 "street2": "C3-3W03"
1442 "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1"
1450 Provides each result object in a simplified format. The node-type,
1451 graph vertex id, pathed url, object properties, and directly related
1452 objects in the graph are all returned. Both direct parent/child
1453 objects and cousin objects are included in the related-to array.
1457 PUT /aai/v$/query?format=simple
1461 .. code-block:: json
1467 "node-type": "complex",
1470 "complex-name": "complex-mccomplexface",
1472 "data-center-code": "CHG",
1473 "latitude": "30.123456",
1474 "longitude": "-78.135344",
1475 "physical-location-id": "complextest1",
1476 "physical-location-type": "lab",
1477 "postal-code": "90210",
1479 "resource-version": "1531233769164",
1481 "street1": "100 Main St",
1482 "street2": "C3-3W03"
1487 "node-type": "zone",
1488 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1489 "url": "/aai/v16/network/zones/zone/zone1"
1493 "node-type": "cloud-region",
1494 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1495 "url": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1"
1499 "node-type": "rack",
1500 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1501 "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1/racks/rack/rackname1-1test"
1504 "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1"
1512 Provides the results using the graphson standard.
1516 PUT /aai/v$/query?format=graphson
1520 .. code-block:: json
1527 "org.onap.relationships.inventory.LocatedIn": [
1529 "id": "oeioq-oe3f4-74l-1crx3s",
1532 "aai-uuid": "9e75af3d-aa7f-4e8e-a7eb-32d8096f03cc",
1533 "contains-other-v": "NONE",
1534 "delete-other-v": "NONE",
1535 "prevent-delete": "IN",
1540 "id": "216a6j-215u1k-74l-1crx3s",
1543 "aai-uuid": "4b3693be-b399-4355-8747-4ea2bb298dff",
1544 "contains-other-v": "NONE",
1545 "delete-other-v": "NONE",
1546 "prevent-delete": "IN",
1551 "id": "215xjt-215u4o-74l-1crx3s",
1554 "aai-uuid": "958b8e10-6c42-4145-9cc1-76f50bb3e513",
1555 "contains-other-v": "IN",
1556 "delete-other-v": "IN",
1557 "prevent-delete": "NONE",
1567 "id": "1crvgr-1crx3s-6bk5",
1568 "value": 1531231973518
1571 "aai-last-mod-ts": [
1573 "id": "215vkb-1crx3s-6dxh",
1574 "value": 1531233769164
1579 "id": "215urv-1crx3s-69z9",
1585 "id": "1crxfv-1crx3s-6gat",
1586 "value": "/cloud-infrastructure/complexes/complex/complextest1"
1591 "id": "1crvuz-1crx3s-1ybp",
1592 "value": "3959ceca-3a89-4e92-a2ff-073b6f409303"
1597 "id": "1cs0zv-1crx3s-4irp",
1598 "value": "Beverley Hills"
1603 "id": "215wcr-1crx3s-4d8l",
1609 "id": "1cs26j-1crx3s-4l51",
1613 "data-center-code": [
1615 "id": "215ssr-1crx3s-4bnp",
1619 "last-mod-source-of-truth": [
1621 "id": "215vyj-1crx3s-696t",
1622 "value": "aai-AppId"
1627 "id": "1cs2yz-1crx3s-4mpx",
1628 "value": "30.123456"
1633 "id": "1cs3d7-1crx3s-4nid",
1634 "value": "-174.135344"
1637 "physical-location-id": [
1639 "id": "1crzez-1crx3s-4a2t",
1640 "value": "complextest1"
1643 "physical-location-type": [
1645 "id": "1crzt7-1crx3s-4ged",
1651 "id": "1cs1sb-1crx3s-4kcl",
1657 "id": "1cs2kr-1crx3s-4lxh",
1661 "resource-version": [
1663 "id": "215v63-1crx3s-glh",
1664 "value": "1531233769164"
1667 "source-of-truth": [
1669 "id": "1crv2j-1crx3s-6epx",
1675 "id": "1cs1e3-1crx3s-4jk5",
1681 "id": "1cs07f-1crx3s-4h6t",
1682 "value": "100 Main St"
1687 "id": "1cs0ln-1crx3s-4hz9",
1697 Optional Query Parameters
1698 ~~~~~~~~~~~~~~~~~~~~~~~~~
1703 You can pass the depth query parameter to specify how many levels of
1704 children/grandchildren to return. The default depth is 1.
1708 PUT /aai/v$/query?format={format}&depth=0
1713 You can pass the nodesOnly query parameter to have the output only
1714 contain the object properties with no relationships.
1718 PUT /aai/v$/query?format={format}&nodesOnly=true
1723 You can pass a subgraph query parameter that determines the behavior
1724 of the output. Using subgraph=prune returns all of the objects from
1725 the query and only the edges between those objects. Using
1726 subgraph=star returns all of the objects from the query plus all of
1727 the objects they relate to.
1729 The default is subgraph=star
1733 PUT /aai/v$/query?format={format}&subgraph={subgraph}
1738 +--------------------------+--------------------------------------------------------------------------------------+
1739 | X-FromAppID={client ID}| Unique application identifier. |
1740 +--------------------------+--------------------------------------------------------------------------------------+
1741 | X-TransactionID={UUDID} | must be a UUID and unique to each transaction within the context of an X-FromAppID. |
1742 +--------------------------+--------------------------------------------------------------------------------------+
1743 | Content-Type={format} | format of the request. Should be application/json or application/xml. |
1744 +--------------------------+--------------------------------------------------------------------------------------+
1745 | Accept={format} | format of the response. Should be application/json or application/xml. |
1746 +--------------------------+--------------------------------------------------------------------------------------+
1751 Typically the query payload will include both a "start" and a "query"
1752 portion. The "start" can indicate one or more starting nodes in the
1753 graph. If multiple nodes are specified, the result will contain the
1754 query results for all of the start nodes. The "query" indicates the
1755 name of the query to be run and also takes query parameters depending
1756 on the query. Please reference the queries on the AAI wiki for
1757 specific saved queries and how they should be usServer Timeout A
1758 Server timeout is implemented for these APIs to make sure the server
1759 did not continue processing the request long after a client times out
1760 on their side. An error code ERR.5.4.7406 will be returned when this
1761 limit is hit. The default value for Traversal API is 60 secs. The
1762 clients should set their timeouts accordingly.
1764 List of Queries and Payloads
1765 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1767 For a full list of available custom queries, please refer to our
1768 `Custom Queries <customQueries.html>`_ document
1773 The Recents API allows a client to get the list of objects that has
1774 been created or updated recently, up to a maximum of 1 week
1777 `Recents API <recentsApi.html>`_