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 the protocol prefixed
198 - The related-link will be used on a PUT as the "first choice" to
199 identify the related resource. The relationship-data structure, which
200 contains the unordered set of keys, is still an acceptable way to
201 relate two objects but, *if both the relationship-data and the
202 related-link are passed, and they don't agree, the related-link will
203 be used without warning that the data is inconsistent*.
205 - The relationship-data will be ignored on PUT.
210 In the future, the hope is that individual node definitions will be
211 separately versioned from API behavior and from one another (e.g.,
212 vserver hasn't changed in many releases and so doesn't need to have
213 its "definition" version updated).
215 Because relationships are starting to become more complex, it may be
216 necessary for AAI to expose to clients the exact relationship between
217 two nodes. This will likely be done with a relationship-type
218 attribute of relationships in the relationship-list.
220 To support the concept of events getting generated on specific changed
221 items, AAI will be migrating towards a model of asking clients to do
222 the most granular PUTs possible rather than leveraging the nested
223 elements of a tree structure.
225 The vce, port-group, cvlan-tag, newvce, vpe, oam-network, and
226 dvs-switch objects will eventually be deprecated in favor of
227 generic-vnf, l3-network, ctag-assignment, segmentation-assignment, and
230 L3-network will eventually be replaced by virtual-network.
232 How to Use this Document
233 ========================
235 The only attributes in our objects that are declared required are
236 those which we know will be present at the creation of each object and
237 which are needed to support the construction of the AAI Graph. This
238 does not imply that one of AAI's clients doesn't need data.
240 When you click on the API documentation, you will see the Summary of
241 APIs broken down by namespace (e.g., cloud-infrastructure, business,
242 network, service-design-and-creation). You can search for **Tag:**
243 (matching the explicit case) to move from namespace to namespace through
246 Search for **Paths** to skip past the Summary section where there will
247 be more detail about each API. Query parameters are provided here, as
248 well as links to our error codes.
250 Search for **Schema definitions** to see the definitions of the
251 payloads. In your browser URL, you can type /#/definitions/node-name at
252 the end of the html address to skip directly to a payload definition.
254 Note that the schema definitions now contain information about the
255 delete scope of a node, edges, and some related node information.
256 Given this information can now be generated, it is no longer repeated
259 Once AAI has a model and configured it, the AAI development server can
260 be used to generate sample XML and JSON payloads, according to the
261 Accept header passed in the request. This is done by calling the
262 "plural" version of an API followed by the word example (e.g.,
263 /vserver/vservers/example). This returns a GET result array with one
264 entry. That single entry can be sent in a PUT request with actual data
265 (the resource-id does not need to be in the PUT payload as it is on the
268 Finally, custom queries that are not simple GETs of a resource must be
269 identified to AAI as separate user stories. This includes searching
270 for a resource with other attributes on the same resource, as well as
271 searching for resources based on their relationship with other
280 Cloud Infrastructure Domain
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
283 The Cloud Infrastructure domain (cloud-infrastructure) represents the
284 assets managed within a cloud site. This includes the complex, the
285 physical servers, the availability zones, oam-networks, tenants, and
286 vserver-related resources (vservers, flavors, images, etc.).
288 Tenants, oam-networks, availability-zones, volume-groups, images,
289 flavors, and dvs-switches will have cloud-region as its parent node.
294 The network namespace contains virtual and physical network resources
295 as well as connection resources such as physical links, logical links,
298 The vce/port-group/cvlan-tag tree represents an immature model that
299 blended several resources together in ways that were expedient but
300 which need to be re-evaluated. A newvce object exists which was the
301 basis of the generic-vnf object. Future efforts will attempt to
302 migrate vce and vpe into generic-vnf.
307 The business namespace captures customers, service-subscriptions, and
308 service-instances. This domain is immature and will be evolving as
309 service design and creation starts to gel.
311 Customers and service-subscriptions in particular will be evolving
312 soon. Any service that is customer facing will see customer and
313 service-subscription data offboarding to BSSs. The
314 service-instance-id will be the "join point" within the BSS to
315 correlate the service-instance to the product and customer. Services
316 that are for infrastructure purposes will have a new entity, an
317 owning-entity, to replace the customer. The owning-entity will be
318 related to the SDC service models that use it.
320 Service Design and Creation
321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
323 The service design and creation namespace captures data we invented
324 based on what we thought SDC would eventually provide. The structure
325 of that data is definitely not what the current plans are for SDC
326 however we need to at least capture the spirit of what's intended and
327 communicate that across ONAP sub components that need it.
329 To date, there are only five containers:
331 1. Service-capabilities capture the pairings of service to
332 resources. At the time of construction, the only data we had to
333 denote service was the service-type from SO. The vnf-type is the
336 2. Service captures the service model instances and this will be
337 deprecated in the future as things mature
339 3. Vnf-image captures information about the resource image needed for
340 a VNF. This was created due to there being no info available on
341 the vservers that run on uCPE
343 4. Models captures model definitions (subgraph definitions using the
346 5. named-queries capture subgraph definitions that allow different
347 data to be retrieved for a given type of asset
352 All REST APIs must be called using https.
354 HTTPS Basic Authentication will be used to authenticate clients. The
355 remote user from the HTTP Servlet Request is used against an AAI
356 policy to see if the authenticated user is authorized for the resource
357 and actions being request.
359 Client should use credentials provided to their system via AAF.
364 The following will be used for logging and interface diagnostic purposes.
366 * X-FromAppId Unique Application ID assigned to the user of these APIs
367 * X-TransactionId Unique ID that identifies an API request
369 The X-FromAppId will be assigned to each application by the AAI team.
370 The X-TransactionId must be unique to each transaction within the
371 context of an X-FromAppId.
373 SO, SDN-C, and AAI have agreed to use the Java UUID class to generate
374 unique ids for X-TransactionId.
376 The Accept and Content-type header should be set to either
377 application/json or application/xml except as documented for PATCH.
379 Response Codes and Error Handling
380 ---------------------------------
382 AAI will use the following HTTP codes
390 - 204 – Success, no payload returned
395 - 405 – Method Not Allowed
396 - 409 - The request could not be completed due to a conflict with the
397 current state of the target resource. This code is used in situations
398 where the user might be able to resolve the conflict and resubmit the
399 request. If the resource version doesn’t match AAI or a required
400 resource version isn't sent but should have been
401 - 410 - You are using a version of the API that has been retired
402 - 412 – Precondition failed (If the resource version doesn’t match AAI or arequired resource version isn't sent but should have been
403 - 415 – Unsupported Media Type
404 - 500 - Internal Server Error
406 Successful PUT responses shall return the following codes:
407 * 200 (OK): used when an existing resource has been modified and
408 there is a response buffer
409 * 201 (Created): MUST be used when a new resource is created
410 * 202 (Accepted): used when AAI completed the action requested but
411 may have taken other actions as well, which are returned in the
413 * 204 (No Content): used when the existing resource has been modified
414 and there is no response buffer
416 Successful DELETE responses shall return the following codes:
417 * 200 (OK): for a successful response if the response includes an
418 entity describing the status.
419 * 204 (No Content): if the action has been enacted but the response
420 does not include an entity.
422 Successful GET responses shall return the following codes:
423 * 200 (OK): for a successful response for a resource that has been found
424 * 404 (Not Found) for a successful response retrieving a list of
425 items and there were no items found, i.e., the GET of the specific
426 plural resource was not found
427 * 404 (Not Found): when a specific resource was not found
430 * 400 Bad Request will be returned if headers are missing
431 * 404 Not Found will be returned if an unknown URL is used
433 In addition, the standard response buffer will be structured as follows unless otherwise specified.
434 There are two types of requestErrors.
436 * Service Exceptions – These exceptions occur when a service is
437 unable to process a request and retrying the request will result in
438 a consistent failure (e.g., an application provides invalid input).
439 * Policy Exceptions – These exceptions occur when a policy criteria
440 has not been met (e.g., the (N+1)th request arrives when an
441 application’s service level agreement only allows N transactions
444 Italics are specific to the error returned, and generally described in the notes
448 HTTP/1.1 405 *Method Not Allowed*
449 Content-Type: application/json
450 Content-Length: nnnnn
451 Date: *Thu, 04 Jun 2009 02:51:59 GMT*
455 “messageId”:"*POL8007*",
456 “text”:”*The resource was invoked with an unsupported operation: %1.*”,
457 “variables”: [”*PUT*”]
463 a. On the first line, substitute the appropriate status response code.
465 b. On the second line, substitute the appropriate content type.
467 c. Express the requestError structure in the required content type (e.g., either JSON or XML). AAI will use JSON.
469 d. ‘requestError’ contains either a ‘policyException’ or a ‘serviceException’ structure.
473 In 1512, AAI is introducing a response payload that is possible during a successful PUT. This payload is used to inform the client that, while AAI completed the action requested, the result could be interpreted as a warning or request for additional action, as negotiated with the client.
475 Sample response to a vserver PUT where the pserver and complex did not exist:
479 {"responseMessages": {"responseMessage": [
481 "messageId": "INF0003",
482 "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
483 "variables": {"variable": [
487 "physical-location-id=fakeccwcomplex",
488 "Added prerequisite object to db:complex",
493 "messageId": "INF0003",
494 "text": "Success with additional info performing %1 on %2. Added %3 with key %4 (msg=%5) (rc=%6)",
495 "variables": {"variable": [
499 "hostname=fakeccwpserver",
500 "Added prerequisite object to db:pserver",
506 Referential Integrity
507 ---------------------
509 AAI is primarily a view to the relationships between instances of
510 services, physical and virtual components, etc. It stores just the
511 details it needs to be efficient to its tasks and knows how to get
512 more details if needed.
514 As such, a transaction sent to AAI may be refused if would break
515 referential integrity. The referential integrity rules of AAI are
516 still evolving as we understand the services and customers that will
519 AAI uses a graph database on a NoSQL data store. The following are
522 * Some vertices are exposed to the outside world through APIs, others
523 are internal to how we store the data (i.e., it may look like one
524 resource to our customers but it is expressed as more than one
527 * Vertices that are internal to AAI will be deleted when the parent
528 vertex is deleted, if deletion of the parent leaves the child vertex
531 * Vertices that are exposed need to be managed using specific rules
534 * Vertices may have more than just parent/child relationships. One
535 example is a vserver, which will be owned by a tenant and used by a
539 URLs Sent To and Retrieved From A&AI
540 ------------------------------------
542 A&AI receives URLs from clients that point back to that client in
543 order to get more details about the data sent to A&AI. A&AI expects
544 the URLs sent by clients (e.g., self links) to be URL encoded
545 (UTF-8) and A&AI will store them unchanged.
547 URIs that A&AI constructs that point to A&AI resources will be
548 returned URLEncoded (UTF-8) to clients. This affects URIs in
549 relationship lists and search results. Note that A&AI used to send
550 URLs but, as reported in the 1707 impacts, these will now be URIs.
552 A&AI expects space to be %20, and not plus(+).
554 The Relationship-List
555 ---------------------
557 The REST interface does not lend itself to creating more than
558 parent-child relationships and the backend structure of AAI is a
559 graph. A goal of AAI, and shared with ONAP, is to do as little coding
560 as possible to introduce a new service into the service design and
561 creation environment.
563 To that end, we've introduced a relationship-list structure. AAI will
564 ask its clients to provide certain data in the relationship-list
567 Each relationship has a related-to attribute and a list of key/value
568 pairs. The related-to attribute identifies the node type that the
569 resource being acted on is to be related to using the data in the
570 key/value pairs. AAI will encode a set of rules for each resource
571 type to verify that only valid edges are being made. AAI will keep
572 the directionality and cardinality, and the edge attributes within its
573 own logic. In the near future, the definition of relationships, their
574 validity, and cardinality will be captured in the ONAP TOSCA models.
576 AAI also has a concept of a related-to category. To date, the only
577 category is vnf. The vnf category is used as the related-to value to
578 indicate that the relationship being establish is to a Virtual Network
579 Function of unknown type. The vnf-id happens to be unique for all
580 services across all nodes in the graph. By providing vnf.vnf-id with
581 a specific value, AAI can look at all VNFs in the graph and find the
582 appropriate vertex. Note that this only applies to PUTs.
584 Category vnf is used for node types of vce, vpe, and generic-vnf.
586 If an attempt is made to add a relationship to a node that doesn't
587 exist (e.g., from a vserver to a vnf, and the vnf doesn't exist), a
588 unique message Id (3003) will be returned with a specific error code
589 (ERR.5.4.6129). Arguments will tell the client which node type was
590 missing (e.g., vnf) and the key data for that node type (vnf.vnf-id).
592 Single relationships can be PUT to the graph in the following way:
596 https://{serverRoot}/{namespace}/{resource}/relationship-list/relationship
602 https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/pserver-123456789-01/p-interfaces/p-interface/p-interface-name-123456789-01/l-interfaces/l-interface/l-interface-name-123456789-01/relationship-list/relationship
604 with a payload containing the relationship information.
606 AAI will accept and give preference to the related-link URI
612 <relationship xmlns="http://org.onap.aai.inventory/vX">
613 <related-link>*/aai/v16/network/logical-links/logical-link/logical-link-123456789-01*</related-link>
614 <related-to>logical-link</related-to>
616 <relationship-key>logical-link.link-name</relationship-key>
617 <relationship-value>logical-link-123456789-01</relationship-value>
626 "related-link": " /aai/v16/network/logical-links/logical-link/logical-link-123456789-01",
627 "related-to": "logical-link",
628 "relationship-data": [
630 "relationship-key": "logical-link.link-name",
631 "relationship-value": " logical-link-123456789-01"
639 The util domain is where AAI locates utility functions. There is
640 currently one utility function, echo, which serves as a ping test that
641 authenticated authorized clients can call to ensure there is
642 connectivity with AAI.
644 The URL for the echo utility is:
648 https://aai.onap:8443/aai/util/echo
650 If the response is unsuccessful, an error will be returned following
653 The successful payload returns the X-FromAppId and X-TransactionId
656 Successful XML Response Payload
657 -------------------------------
664 <messageId>INF0001</messageId>
665 <text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text>
667 <variable>CCW</variable>
668 <variable>CCW33335</variable>
669 <variable>Successful health check:OK</variable>
670 <variable>0.0.0002</variable>
676 Successful JSON Response Payload
677 --------------------------------
682 "responseMessages": {
685 "messageId": "INF0001",
686 "text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)",
691 "Successful health check:OK",
700 AAI Resources CRUD APIs
701 =======================
703 The API structure is composed of:
705 * The HTTP command, which indicates the operation to perform
706 * The HTTP URI, which defines what object this operation is related to
707 * The HTTP version, which MUST be 1.1
709 Available HTTP commands are:
711 * PUT: used to create or update an object
712 * DELETE: used to delete an object or a set of objects
713 * GET : used to query an object or set of objects
714 * PATCH : used to update specific fields owned by the client doing the update
716 The HTTP URI is built according to this pattern:
720 https://{serverRoot}/{namespace}/{resource}
722 * {serverRoot} refers to the server base url: hostname+port+base path+version. Port and base path are OPTIONAL but AAI will use port 8443 and base path aai. Note that the base path may change before production, so please make this configurable. Versions will change as releases are made.
724 * {namespace} refers to the API namespace. Supported namespaces are cloud-infrastructure, business, service-design-and-creation, and network
726 * {resource} refers to how the object is identified according to the namespace specifications.
732 GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}
737 Given AAI is largely a correlation engine among disparate inventory
738 types, AAI will for the most part accept values as they are sent,
739 without validating the format or value of the input. **It is
740 incumbent upon the source of truth to provide valid information to
743 Clients should either use the PATCH API to only change
744 the attribute values they mean to change, or do a GET prior to a PUT
745 and change only the data that they mean to affect.
747 The PUT REST APIs expect the payload passed to replace the resource in
748 AAI. **A GET before PUT is vital in our concurrency scheme. The
749 client will be returned an opaque value per entity which needs to be
750 returned back in the PUT. AAI will reject the PUT or DELETE if the
751 opaque value doesn't match what AAI has stored for that entity.**
753 If an attribute has been added to a model in vN+1, and a GET/PUT of a
754 vN resource is done, AAI should not affect the new attribute (i.e., it
755 should be left unchanged).
760 Concurrency control for AAI is in place.
762 * A client always gets a resource before updating through PUT or deleting it.
764 * All resource updates and deletions are done via the AAI REST APIs
766 * This solution will apply to PUT and DELETE operations.
768 * The resource-version attribute is now in every container
770 * The PATCH REST verb is not subject to concurrency control, because
771 it is only intended to be used by clients who are the definitive
772 source of truth for the attributes they are changing. An update
773 through the PATCH API will however reset the resource-version so
774 clients using PUT and DELETE will not risk updating with stale data.
775 If a client would like us to do concurrency control for PATCH, we
776 will need a feature request. PATCH is recommended for clients who
777 know they are the definitive source of data, as there is less risk
778 of destroying other data.
780 If you use PUT, you MUST send back the entire resource, not just the
781 pieces you know about. This is best illustrated by example. Note:
782 Specific interfaces only show you the data you are responsible for but
783 that does not mean that's all the data that the resource you GET will
784 contain. You are responsible to overlay only your changes and leave
785 everything else untouched.
787 Imagine this is the existing resource:
792 "node-id": "valueOfNodeId",
793 "node-name": "valueOfNodeName",
794 "prov-status": "NVTPROV",
795 "relationship-list": {
798 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
799 "related-to": "generic-vnf",
800 "relationship-data": [
802 "relationship-key": "generic-vnf.vnf-id",
803 "relationship-value": "generic-vnf-20160902a"
808 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
809 "related-to": "generic-vnf",
810 "relationship-data": [
812 "relationship-key": "generic-vnf.vnf-id",
813 "relationship-value": "generic-vnf-20161010"
819 "resource-version": "1474912794"
822 And you want to update the name and add a relationship to an l3-network.
824 The payload you need to send back, if you choose PUT, is this. The
825 node-name and the third relationship block is the new data, and the
826 other data and relationships previously existed and must still be PUT.
831 "node-id": "valueOfNodeId",
832 "node-name": "NEWvalueOfNodeName",
833 "prov-status": "NVTPROV",
834 "relationship-list": {
837 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20160902a",
838 "related-to": "generic-vnf",
839 "relationship-data": [
841 "relationship-key": "generic-vnf.vnf-id",
842 "relationship-value": "generic-vnf-20160902a"
847 "related-link": " /aai/v16/network/generic-vnfs/generic-vnf/generic-vnf-20161010",
848 "related-to": "generic-vnf",
849 "relationship-data": [
851 "relationship-key": "generic-vnf.vnf-id",
852 "relationship-value": "generic-vnf-20161010"
857 "related-link": " /aai/v16/network/l3-networks/l3-network/network-name-for-me",
858 "related-to": "l3-network",
859 "relationship-data": [
861 "relationship-key": "l3-network.network-name",
862 "relationship-value": "network-name-for-me"
868 "resource-version": "1474912794"
871 A Warning About PUT and Lists
872 -----------------------------
874 The PUT verb is used to both create and replace a resource. A given
875 resource may have child resources (e.g., customers have service
876 subscriptions, generic-vnfs have vf-modules, tenants have vservers and
877 vservers have volumes).
879 The following convention will be followed:
881 If a resource is replaced and there are no tags for children, the
882 children that exist will be left alone.
884 If a resource is replaced and there are tags for children, the
885 children will be replaced by the list passed. If the list is empty,
886 then children will be deleted.
888 Note that the relationship list is a type of child resource. The same
889 conventions are followed. It is especially critical to ensure that
890 you do not send an incomplete relationship list and therefore remove
891 edges in the graph. See `The Relationship-List`_ for more information on
892 relationship lists. See `Concurrency Control`_ for an example of GET followed by
893 PUT containing the entire resource (i.e., overlaying your changes on
894 what already exists so that you don't wipe out other data).
899 To move towards industry standards and to make our APIs easier to use
900 by clients who own specific attributes and do not require AAI to
901 enforce concurrency control around them, the PATCH verb has been
904 .. _RFC 7386: https://tools.ietf.org/html/rfc7386
906 - RFC Algorithm implemented JSON Merge PATCH: `RFC 7386`_
908 - Clients can send a POST with "X-HTTP-Method-Override" = "PATCH" and
909 Content-Type = "application/merge-patch+json" to send a PATCH
911 - PATCH does not support XML
912 - PATCH does not require a resource version to perform these modifications
913 - Clients should only send what they wish to modify and whose value they "own"
914 - PATCH returns a 200 with no response body for success
920 PATCH https://aai.onap:8443/aai/v16/network/generic-vnfs/generic-vnf/cscf0001v
922 "vnf-id": "cscf0001v", <-- This key needs to be here but you cannot modify the key
923 "regional-resource-zone": null,
924 "ipv4-oam-address": "10.10.99.11"
927 This payload would result in the generic-vnf with the vnf-id =
928 cscf0001v having ipv4-oam-address set to "10.10.99.11" and
929 regional-resource-zone having its value removed from the database.
931 Note: PATCH is used only to update attributes on a single node that
932 already exists in AAI. That means it is not applicable to lists of
935 * You do not manage relationships with PATCH. There is a
936 relationship API for that.
938 * You cannot include child objects in a PATCH payload, i.e., you
939 cannot PATCH an l3-network's attributes as well as supply some
940 subnet children or their attributes within the same PATCH payload.
941 You can GET/overlay/PUT parent/child payloads or you can PUT or
942 PATCH each object individually with separate REST API calls.
944 Optional Query Parameters
945 -------------------------
947 A **depth** query parameter is available allowing a query to stop after it
948 has reached a certain point in the graph. This allows clients to
949 minimize the data that is returned to them and make the queries more
950 performant. A depth=0 will return information of the node referred to
951 by the URI only without any information on the children.
957 GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0
959 A **nodes-only** parameter is available allowing a query to only
960 display the properties of the nodes being queried without any
961 relationship information. This allows clients to minimize data that is
962 returned to them and make the queries more performant.
968 GET https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?nodes-only
970 These parameters may be used in combination with each other.
976 GET https://aai.onap:8443/aai/v14/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}?depth=0&nodes-only
978 Delete Scope and Edges
979 ----------------------
981 An attempt to remove a node which would result in a delete scope being
982 violated will return error 5.4.6110.
984 The swagger documentation has been updated to show information about
985 delete scope and edges.
987 Here is a subset of the generic-vnf definition that will be used to
988 demonstrate how the delete scope and edges are documented.
990 The following table summarizes actions AAI will take upon deletion of a resource, i.e., its default delete scope:
992 +-----------------------------+--------------------------------------------------------------------+
993 | ERROR_IF_ANY_EDGES | If the resource being deleted has any edges at all |
994 | | an error should be returned |
995 +-----------------------------+--------------------------------------------------------------------+
996 | ERROR_IF_ANY_IN_EDGES | If the resource being deleted has any edges that point IN towards |
997 | | it, an error should be returned |
998 +-----------------------------+--------------------------------------------------------------------+
999 | THIS_NODE_ONLY | Delete the vertex being requested by first deleting its edge to |
1000 | | other vertices, but do not delete the other vertices. Note, the |
1001 | | delete will be rejected if the deletion target has DEPENDENT |
1002 | | children (e.g., tenants that have vservers) |
1003 +-----------------------------+--------------------------------------------------------------------+
1004 | CASCADE_TO_CHILDREN | Cascade the delete through vertices who have a parentOf |
1005 | | relationship to the vertex being deleted, as long as the vertex is |
1006 | | orphaned by the delete of its parent |
1007 +-----------------------------+--------------------------------------------------------------------+
1008 | ERROR_4_IN_EDGES_OR_CASCADE | Error if there are any in edges and, if not, cascade to |
1010 +-----------------------------+--------------------------------------------------------------------+
1014 * Node A is the object being defined - e.g., generic-vnf
1016 * Node B is the XXX of OUT TO XXX
1018 * Direction is always Node A OUT TO Node B. Node A has requirement
1019 satisfied by Node B and the relationship is the edgelabel
1021 * Multiplicity is listed on the OUT TO edges
1023 * The former hasDelTarget is indicated by deletion statements that
1024 make it clear what gets deleted as a side effect of deleting
1027 * The former isChild is indicated by full statements
1032 *generic-vnf: object*
1033 *General purpose VNF*
1035 *Default Delete Scope*
1039 * *OUT TO vnfc (org.onap.relationships.inventory.Uses, One2Many, delete of generic-vnf will delete vnfc)*
1040 * *IN FROM l-interface (l-interface child of generic-vnf)*
1041 * *IN FROM service-instance*
1046 A Server timeout is implemented for these APIs to make sure the server
1047 did not continue processing the request long after a client times out
1048 on their side. An error code ERR.5.4.7406 will be returned when this
1049 limit is hit. The default value for Resources API is 60 secs. The
1050 clients should set their timeouts accordingly.
1055 The Bulk API allows clients to make multiple requests in a single
1056 transaction. Please look for additional details on the Bulk API link
1057 in the table on contents.
1062 In working with A&AI's standard REST API, you may have noticed that
1063 certain API paths have a hierarchy to them and require a client to
1064 know multiple object keys to preform GETs. For example: the vserver
1065 object is under tenant, which is itself under cloud-region. If you
1066 wanted to look up a vserver by name, you would still need to know the
1067 tenant-id and cloud-region-id (and cloud-owner) in order to
1068 successfully perform that GET. The nodes API allows for more freedom
1069 in querying A&AI, allowing clients to circumvent the need to know
1070 every key in the hierarchy.
1072 See Nodes API in the table of contents for more information.
1077 Not all queries of the graph are purely GETs of a specific resource
1078 and its related vertexes. The following capabilities are available to
1079 meet more advanced search needs. Please contact the AAI team if you
1080 need another search.
1085 The Nodes Query mechanism was implemented in support of searching the
1086 pservers which do not have the ipv4-oam-ipaddress set. It will allow
1087 nodes to be searched based on certain properties of the nodes. It will
1088 allow search based on properties being set, not set or set to specific
1091 Please reference Nodes Query in the table of contents for details on the
1092 API and test queries.
1098 The Generic Query mechanism allows to search for certain nodes of
1099 “include” node types at a specified “depth” from the from a particular
1100 start node of type “start-node-type” identified by specifying its
1105 Model Based Query and Delete
1106 ----------------------------
1108 AAI supports a search and delete capability that allows a client to
1109 retrieve or delete an instance of a service based on the model
1110 subgraph definition provided to AAI by ASDC.
1112 The instance filters must uniquely identify a service instance.
1114 The URL is as follows:
1118 https://{serverRoot}/aai/search/model[?action=DELETE]
1120 .. code-block:: json
1123 "query-parameters": {
1125 "model-invariant-id": "$modelInvariantId",
1129 "model-version-id": "$modelVersionId"
1134 "instance-filters": {
1135 "instance-filter": [
1138 "global-customer-id": "$globalCustID"
1140 "service-instance": {
1141 "resource-version": "$resourceversionID",
1142 "service-instance-id": "$serviceInstanceID"
1144 "service-subscription": {
1145 "service-type": "$serviceType"
1156 These queries provide the ability to upload a json file describing the
1157 inputs and designed output based on traversing the graph in a
1158 particular way. Existing named queries are supported but will be
1159 migrated to custom queries. **Named queries will be deprecated (no new
1160 queries, just support for existing ones) in Dublin and clients will be
1161 asked to migrate to use the custom queries instead.**
1166 This API provides AAI clients an API for complex data retrieval. To
1167 execute a custom query, a client will perform an HTTP PUT request on
1168 the query API and include a payload indicating the starting node and
1169 the query to be run. While the client is performing a PUT request,
1170 this is actually a data query and no data is created or changed.
1175 +----------+-----------------------------+--------------------------+
1176 | No. | Assumption | Approach |
1177 +==========+=============================+==========================+
1178 | 1 | Assume that client will | |
1179 | | not request large amounts | |
1180 | | of data from AAI w/out | |
1181 | | using secondary filters | |
1182 +----------+-----------------------------+--------------------------+
1187 Data has been PUT to AAI prior to the query.
1194 PUT /aai/v$/query?format={format}
1199 The format determines what information is returned from the
1200 query. Acceptable formats are: count, id, pathed, resource,
1201 resource_and_url, or simple.
1206 Provides an count of the objects returned in the query.
1210 PUT /aai/v$/query?format=count
1214 .. code-block:: json
1230 Provides an array of objects containing resource-type (AAI's node
1231 type; i.e., pnf) and a URI using the vertex ID from AAI's graph.
1235 PUT /aai/v$/query?format=id
1239 .. code-block:: json
1244 "resource-type": "complex",
1245 "resource-link": "/aai/v1/resources/id/8159312"
1248 "resource-type": "complex",
1249 "resource-link": "/aai/v1/resources/id/389256"
1257 Provides an array of objects containing resource-type (AAIs node type;
1258 i.e., pnf) and a URI using the AAI REST API pathed URIs
1262 PUT /aai/v$/query?format=pathed
1266 .. code-block:: json
1271 "resource-type": "complex",
1272 "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1275 "resource-type": "complex",
1276 "resource-link": "/aai/v1/cloud-infrastructure/complexes/complex/complex1"
1284 Provides each object in the results array in the same format as AAI's
1285 REST API with depth = 1 (first level children and cousin
1290 PUT /aai/v$/query?format=resource
1295 .. code-block:: json
1302 "complex-name": "complex-mccomplexface",
1304 "data-center-code": "CHG",
1305 "latitude": "30.123456",
1306 "longitude": "-78.135344",
1307 "physical-location-id": "complextest1",
1308 "physical-location-type": "lab",
1309 "postal-code": "90210",
1311 "relationship-list": {
1314 "related-link": "/aai/v1/network/zones/zone/zone1",
1315 "related-to": "zone",
1316 "related-to-property": [
1318 "property-key": "zone.zone-name",
1319 "property-value": "zone-name1"
1322 "relationship-data": [
1324 "relationship-key": "zone.zone-id",
1325 "relationship-value": "zone1"
1328 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1331 "related-link": "/aai/v1/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1332 "related-to": "cloud-region",
1333 "related-to-property": [
1335 "property-key": "cloud-region.owner-defined-type"
1338 "relationship-data": [
1340 "relationship-key": "cloud-region.cloud-owner",
1341 "relationship-value": "Cloud-Region"
1344 "relationship-key": "cloud-region.cloud-region-id",
1345 "relationship-value": "Region1"
1348 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1352 "resource-version": "1531233769164",
1354 "street1": "100 Main St",
1355 "street2": "C3-3W03"
1364 Provides each object in the results array in the same format as AAI’s
1365 REST API with depth = 1 (first level children and cousin
1366 relationships) plus the pathed url for the result object in AAI.
1370 PUT /aai/v$/query?format=resource_and_url
1374 .. code-block:: json
1381 "complex-name": "complex-mccomplexface",
1383 "data-center-code": "CHG",
1384 "latitude": "30.123456",
1385 "longitude": "-78.135344",
1386 "physical-location-id": "complextest1",
1387 "physical-location-type": "lab",
1388 "postal-code": "90210",
1390 "relationship-list": {
1393 "related-link": "/aai/v16/network/zones/zone/zone1",
1394 "related-to": "zone",
1395 "related-to-property": [
1397 "property-key": "zone.zone-name",
1398 "property-value": "zone-name1"
1401 "relationship-data": [
1403 "relationship-key": "zone.zone-id",
1404 "relationship-value": "zone1"
1407 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1410 "related-link": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1",
1411 "related-to": "cloud-region",
1412 "related-to-property": [
1414 "property-key": "cloud-region.owner-defined-type"
1417 "relationship-data": [
1419 "relationship-key": "cloud-region.cloud-owner",
1420 "relationship-value": "Cloud-REgion"
1423 "relationship-key": "cloud-region.cloud-region-id",
1424 "relationship-value": "Region1"
1427 "relationship-label": "org.onap.relationships.inventory.LocatedIn"
1431 "resource-version": "1531233769164",
1433 "street1": "100 Main St",
1434 "street2": "C3-3W03"
1436 "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1"
1444 Provides each result object in a simplified format. The node-type,
1445 graph vertex id, pathed url, object properties, and directly related
1446 objects in the graph are all returned. Both direct parent/child
1447 objects and cousin objects are included in the related-to array.
1451 PUT /aai/v$/query?format=simple
1455 .. code-block:: json
1461 "node-type": "complex",
1464 "complex-name": "complex-mccomplexface",
1466 "data-center-code": "CHG",
1467 "latitude": "30.123456",
1468 "longitude": "-78.135344",
1469 "physical-location-id": "complextest1",
1470 "physical-location-type": "lab",
1471 "postal-code": "90210",
1473 "resource-version": "1531233769164",
1475 "street1": "100 Main St",
1476 "street2": "C3-3W03"
1481 "node-type": "zone",
1482 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1483 "url": "/aai/v16/network/zones/zone/zone1"
1487 "node-type": "cloud-region",
1488 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1489 "url": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloud-Region/Region1"
1493 "node-type": "rack",
1494 "relationship-label": "org.onap.relationships.inventory.LocatedIn",
1495 "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1/racks/rack/rackname1-1test"
1498 "url": "/aai/v16/cloud-infrastructure/complexes/complex/complextest1"
1506 Provides the results using the graphson standard.
1510 PUT /aai/v$/query?format=graphson
1514 .. code-block:: json
1521 "org.onap.relationships.inventory.LocatedIn": [
1523 "id": "oeioq-oe3f4-74l-1crx3s",
1526 "aai-uuid": "9e75af3d-aa7f-4e8e-a7eb-32d8096f03cc",
1527 "contains-other-v": "NONE",
1528 "delete-other-v": "NONE",
1529 "prevent-delete": "IN",
1534 "id": "216a6j-215u1k-74l-1crx3s",
1537 "aai-uuid": "4b3693be-b399-4355-8747-4ea2bb298dff",
1538 "contains-other-v": "NONE",
1539 "delete-other-v": "NONE",
1540 "prevent-delete": "IN",
1545 "id": "215xjt-215u4o-74l-1crx3s",
1548 "aai-uuid": "958b8e10-6c42-4145-9cc1-76f50bb3e513",
1549 "contains-other-v": "IN",
1550 "delete-other-v": "IN",
1551 "prevent-delete": "NONE",
1561 "id": "1crvgr-1crx3s-6bk5",
1562 "value": 1531231973518
1565 "aai-last-mod-ts": [
1567 "id": "215vkb-1crx3s-6dxh",
1568 "value": 1531233769164
1573 "id": "215urv-1crx3s-69z9",
1579 "id": "1crxfv-1crx3s-6gat",
1580 "value": "/cloud-infrastructure/complexes/complex/complextest1"
1585 "id": "1crvuz-1crx3s-1ybp",
1586 "value": "3959ceca-3a89-4e92-a2ff-073b6f409303"
1591 "id": "1cs0zv-1crx3s-4irp",
1592 "value": "Beverley Hills"
1597 "id": "215wcr-1crx3s-4d8l",
1603 "id": "1cs26j-1crx3s-4l51",
1607 "data-center-code": [
1609 "id": "215ssr-1crx3s-4bnp",
1613 "last-mod-source-of-truth": [
1615 "id": "215vyj-1crx3s-696t",
1616 "value": "aai-AppId"
1621 "id": "1cs2yz-1crx3s-4mpx",
1622 "value": "30.123456"
1627 "id": "1cs3d7-1crx3s-4nid",
1628 "value": "-174.135344"
1631 "physical-location-id": [
1633 "id": "1crzez-1crx3s-4a2t",
1634 "value": "complextest1"
1637 "physical-location-type": [
1639 "id": "1crzt7-1crx3s-4ged",
1645 "id": "1cs1sb-1crx3s-4kcl",
1651 "id": "1cs2kr-1crx3s-4lxh",
1655 "resource-version": [
1657 "id": "215v63-1crx3s-glh",
1658 "value": "1531233769164"
1661 "source-of-truth": [
1663 "id": "1crv2j-1crx3s-6epx",
1669 "id": "1cs1e3-1crx3s-4jk5",
1675 "id": "1cs07f-1crx3s-4h6t",
1676 "value": "100 Main St"
1681 "id": "1cs0ln-1crx3s-4hz9",
1691 Optional Query Parameters
1692 ~~~~~~~~~~~~~~~~~~~~~~~~~
1697 You can pass the depth query parameter to specify how many levels of
1698 children/grandchildren to return. The default depth is 1.
1702 PUT /aai/v$/query?format={format}&depth=0
1707 You can pass the nodesOnly query parameter to have the output only
1708 contain the object properties with no relationships.
1712 PUT /aai/v$/query?format={format}&nodesOnly=true
1717 You can pass a subgraph query parameter that determines the behavior
1718 of the output. Using subgraph=prune returns all of the objects from
1719 the query and only the edges between those objects. Using
1720 subgraph=star returns all of the objects from the query plus all of
1721 the objects they relate to.
1723 The default is subgraph=star
1727 PUT /aai/v$/query?format={format}&subgraph={subgraph}
1732 +--------------------------+--------------------------------------------------------------------------------------+
1733 | X-FromAppID={client ID}| Unique application identifier. |
1734 +--------------------------+--------------------------------------------------------------------------------------+
1735 | X-TransactionID={UUDID} | must be a UUID and unique to each transaction within the context of an X-FromAppID. |
1736 +--------------------------+--------------------------------------------------------------------------------------+
1737 | Content-Type={format} | format of the request. Should be application/json or application/xml. |
1738 +--------------------------+--------------------------------------------------------------------------------------+
1739 | Accept={format} | format of the response. Should be application/json or application/xml. |
1740 +--------------------------+--------------------------------------------------------------------------------------+
1745 Typically the query payload will include both a "start" and a "query"
1746 portion. The "start" can indicate one or more starting nodes in the
1747 graph. If multiple nodes are specified, the result will contain the
1748 query results for all of the start nodes. The "query" indicates the
1749 name of the query to be run and also takes query parameters depending
1750 on the query. Please reference the queries on the AAI wiki for
1751 specific saved queries and how they should be usServer Timeout A
1752 Server timeout is implemented for these APIs to make sure the server
1753 did not continue processing the request long after a client times out
1754 on their side. An error code ERR.5.4.7406 will be returned when this
1755 limit is hit. The default value for Traversal API is 60 secs. The
1756 clients should set their timeouts accordingly.
1758 List of Queries and Payloads
1759 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1761 For a full list of available custom queries, please refer to our Custom Queries in the Table of Contents
1766 The Recents API allows a client to get the list of objects that has
1767 been created or updated recently, up to a maximum of 1 week
1768 back. Please see the link in the table of contents.