5 | Copyright © 2017 AT&T Intellectual Property.
7 | Licensed under the Creative Commons License, Attribution 4.0 Intl.
8 (the "License"); you may not use this documentation except in
9 compliance with the License.
10 | You may obtain a copy of the License at
11 | https://creativecommons.org/licenses/by/4.0/
12 | Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
15 implied. See the License for the specific language governing
16 permissions and limitations under the License.
17 | ECOMP and OpenECOMP are trademarks and service marks of AT&T
18 Intellectual Property.
20 \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
28 The AAI REST API provides access to the AAI active inventory graph. The
29 API is largely configured off of models and configuration files. Each
30 vertex in the graph has an API that can be called separately or, if part
31 of a tree structure, as a nested element with one or more generations
32 (parent, grandparent, etc.).
34 The edges of the graph are provisioned using a relationship list
35 construct. For PUT methods, a relationship contains the vertex type or
36 category (related-to) and a list of relationship data which captures the
37 key pieces of data required to uniquely identify the resource. On a GET
38 method, the above information and a URL are returned. The URL can be
39 used to GET all the details of that object. The URL returned is suitable
40 for retrying failed commands but should not be expected to be cacheable
41 for very long periods (e.g., the version of the URL may get deprecated
42 when the release changes).
44 Concurrency control for AAI is in place. The assumptions made for the
45 implementation are as follows:
47 - A client always gets a resource before updating through PUT or
50 - All resource updates and deletions are done via the AAI REST APIs
52 - This solution will apply to PUT and DELETE operations.
54 - The resource-version attribute is now in every container
56 - The update API is not subject to concurrency control because it is
57 only intended to be used by clients who are the definitive source of
58 truth for the attributes they are changing. An update through the
59 update API will however reset the resource-version so clients using
60 PUT and DELETE will not risk updating with stale data.
62 - The PATCH REST verb is not subject to concurrency control because it
63 is only intended to be used by clients who are the definitive source
64 of truth for the attributes they are changing. An update through the
65 update API will however reset the resource-version so clients using
66 PUT and DELETE will not risk updating with stale data.
68 How to Use this Document
69 ========================
71 When you click on the API documentation, you will see the Summary of
72 APIs broken down by namespace (e.g., cloud-infrastructure, business,
73 network, service-design-and-creation). You can search for **Tag:**
74 (matching the explicit case) to move from namespace to namespace through
77 Search for **Paths** to skip past the Summary section where there will
78 be more detail about each API. Query parameters are provided here, as
79 well as links to our error codes.
81 Search for **Schema definitions** to see the definitions of the
82 payloads. In your browser URL, you can type /#/definitions/node-name at
83 the end of the html address to skip directly to a payload definition.
85 Note that the schema definitions now contain information about the
86 delete scope of a node (also referenced in this document) and some
87 related node information (also reference in this document as Edges).
89 Once AAI has a model and configured it, the AAI development server can
90 be used to generate sample XML and JSON payloads, according to the
91 Accept header passed in the request. This is done by calling the
92 "plural" version of an API followed by the word example (e.g.,
93 /vserver/vservers/example). This returns a GET result array with one
94 entry. That single entry can be sent in a PUT request with actual data
95 (the resource-id does not need to be in the PUT payload as it is on the
101 Information that is largely guidance or aspirational will be show in
102 gray italicized text. This information should not be relied upon or
103 referenced at this point except with the understanding that it WILL
106 **Bold blue text** will be used to cover communication to our clients
107 that may not be enforced by AAI. The sources of truth (our clients)
108 populate AAI and are expected to send the correct information, having
109 applied business rules that live in the client systems.
111 Deprecation Warnings and History
112 ================================
118 - The actions/update API will be retired. Clients must switch to PATCH.
119 There is one grandfathered usage for vpe update flows which will be
122 - The edge tag query will be retired.
124 Notable attribute and/or valid value changes (generally also impacts
127 - The persona-model-id and persona-version will be replaced with
128 model-invariant-id (same value as persona-model-id) and
129 model-version-id (the UUID of the specific version of a model).
130 Persona-model-customization-id will be replaced by
131 model-customization-id.
133 - The operational-state attribute will be replaced by
134 operational-status and the only valid values will be in-service-path
135 and out-of-service-path
137 - The vpn-binding object will be split in two to reflect more than one
138 route-target per binding. The route-target will be a child of
139 vpn-binding and some attributes will move from vpn-binding to
142 - The following license related attributes will be removed from
143 generic-vnf: license-key, entitlement-assignment-group-uuid,
144 entitlement-resource-uuid, license-assignment-group-uuid, and
145 license-key-uuid due to the introduction of the entitlement and
150 - Normal impacts due to renaming or adding attributes, splitting
151 objects, etc. Please see swagger documentation for objects of
154 - In v11, clients that require lineage, children, or relationship
155 information need to subscribe to a different DMaaP topic than the
160 - The related-link will be a URI and thus not contain
161 https://{serverroot} (impacts events)
163 - Thhe related-link will be used on a PUT as the "first choice" to
164 identify the related resource. The relationship-data structure, which
165 contains the unordered set of keys, is still an acceptable way to
166 relate two objects but, *if both the relationship-data and the
167 related-link are passed, and they don't agree, the related-link will
168 be used without warning that the data is inconsistent*.
170 - The relationship-data will be ignored on PUT.
175 The API structure is composed of:
177 - The HTTP command, which indicates the operation to perform
179 - The HTTP URI, which defines what object this operation is related to
181 - The HTTP version, which MUST be 1.1
183 Available HTTP commands are:
185 - PUT: used to create or update an object
187 - DELETE: used to delete an object or a set of objects
189 - GET : used to query an object or set of objects
191 - PATCH : used to update specific fields owned by the client doing the
194 The HTTP URI is built according to this pattern:
196 https://{serverRoot}/{namespace}/{resource}
198 - (serverRoot} refers to the server base url: hostname+port+base
199 path+version. Port and base path are OPTIONAL but AAI will use port
200 8443 and base path aai. The Amsterdam release version will be v11.
202 - {namespace} refers to the API namespace. Supported namespaces are
203 cloud-infrastructure, business, service-design-and-creation, and
206 - {resource} refers to how the object is identified according to the
207 namespace specifications.
211 GET https://{hostname}:8443/aai
212 /v11/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}
214 The GET requests support a depth query parameter allowing a query to
215 stop after it has reached a certain point in the graph. This allows
216 clients to minimize the data that is returned to them. A depth=0 returns
217 the resource itself and none of its children.
222 Given AAI is largely a correlation engine among disparate inventory
223 types, AAI will accept values as they are sent, without validating the
224 format or value of the input. It is incumbent upon the source of truth
225 to provide valid information to AAI.
227 Clients should do a GET prior to a PUT and change only the data that
228 they mean to affect. The REST APIs expect the payload passed to replace
229 the resource in AAI. **This is vital in our concurrency scheme. The
230 client will be returned an opaque value per entity which needs to be
231 returned back in the PUT. AAI will reject the PUT or DELETE if the
232 opaque value doesn't match what AAI has stored for that entity.**
234 If a leaf has been added to a model in vN+1, and a GET/PUT of a vN
235 resource is done, AAI should not affect the new leaf (i.e., it should be
241 The PUT verb is used to both create and replace a resource. A given
242 resource may have child resources (e.g., customers have service
243 subscriptions; tenants have vservers and vservers have volumes).
245 The following convention will be followed:
247 If a resource is replaced and there are no tags for children, the
248 children that exist will be left alone.
250 If a resource is replaced and there are tags for children, the children
251 will be replaced by the list passed. If the list is empty, then children
254 Note that the relationship list is a type of child resource. The same
255 conventions are followed. It is especially critical to ensure that you
256 do not send an incomplete relationship list and therefore remove edges
257 in the graph. See section 5.10 for more information on relationship
263 To move towards industry standards and to make our APIs easier to use by
264 clients who own specific attributes and do not require AAI to enforce
265 concurrency control around them, the PATCH verb has been introduced.
267 - RFC Algorithm implemented JSON Merge PATCH
268 `tools.ietf.org/html/rfc7386 <https://tools.ietf.org/html/rfc7386>`__
270 - *HTTP Verb = PATCH*
272 - PATCH requires a Content-Type of "application/merge-patch+json" in
275 - PATCH does not support XML
277 - PATCH does not require a resource version to preform these
280 - Clients should only send what they wish to modify and whose value
285 PATCH \ `https://<hostname>:8443/aai/v11/network/generic-vnfs/generic-vnf/cscf0001v <https://aai-int1.test.att.com:8443/aai/v7/network/generic-vnfs/generic-vnf/cscf0001v>`__
289 "vnf-id": "cscf0001v", This key needs to be here but you cannot
292 "regional-resource-zone": null,
294 "ipv4-oam-address": "1.2.3.4"
298 This payload would result in the generic-vnf with the vnf-id = cscf0001v
299 having ipv4-oam-address set to "1.2.3.4" and regional-resource-zone
300 having its value removed from the database.
302 Referential Integrity
303 ---------------------
305 AAI is primarily a view to the relationships between customers,
306 products, services, physical and virtual components, etc. It stores just
307 the details it needs to be efficient to its tasks and knows how to get
308 more details if needed.
310 As such, a transaction sent to AAI may be refused if would break
311 referential integrity. The referential integrity rules of AAI are still
312 evolving as we understand the services and customers that will use us.
314 AAI uses a graph database on a NoSQL data store. The following are true
317 - Some vertices are exposed to the outside world through APIs, others
318 are internal to how we store the data (i.e., it may look like one
319 resource to our customers but it is expressed as more than one vertex
322 - Vertices that are internal to AAI will be deleted when the parent
323 vertex is deleted, if deletion of the parent leaves the child vertex
326 - Vertices that are exposed need to be managed using specific rules for
329 - Vertices may have more than just parent/child relationships. One
330 example is a vserver, which will be owned by a tenant and used by a
336 The following options are available as actions to be take upon deletion
339 - ERROR\_IF\_ANY\_EDGES – If the resource being deleted has any edges
340 at all, an error should be returned
342 - ERROR\_IF\_ANY\_IN\_EDGES – if the resource being deleted has any
343 edges that point IN towards it, an error should be returned
345 - THIS\_NODE\_ONLY – delete the vertex being requested by first
346 deleting its edge to other vertices, but do not delete the other
347 vertices. Note, the delete will be rejected if the deletion target
348 has DEPENDENT children (e.g., tenants that have vservers)
350 - CASCADE\_TO\_CHILDREN – cascade the delete through vertices who have
351 a parentOf relationship to the vertex being deleted, as long as the
352 vertex is orphaned by the delete of its parent
354 - ERROR\_4\_IN\_EDGES\_OR\_CASCADE – error if there are any in edges
355 and, if not, cascade to children
360 All REST APIs must be called using https.
362 The current release is configured to support BasicAuth. 2-way SSL using
363 client certificates should be configured for production deployments or
369 The following will be used for logging and interface diagnostic
372 - X-FromAppId Unique Application ID assigned to the user of these APIs
374 - X-TransactionId Unique ID that identifies an API request
376 The X-FromAppId will be assigned to each application by the AAI team.
377 The X-TransactionId must be unique to each transaction within the
378 context of an X-FromAppId.
380 OpenECOMP components that call AAI use the Java UUID class to generate
381 unique ids for X-TransactionId.
383 The Accept header should be set to either application/json or
386 +-------------------------------+---------------+
387 | Client | X-FromAppId |
388 +===============================+===============+
390 +-------------------------------+---------------+
391 | Master Service Orchestrator | MSO |
392 +-------------------------------+---------------+
393 | SDN Controller | SDNC |
394 +-------------------------------+---------------+
395 | Application Controller | APPC |
396 +-------------------------------+---------------+
398 Response Codes and Error Handling
399 ---------------------------------
401 HTTP response codes and error codes are described in the API
404 URLs Sent To and Retrieved From AAI
405 -----------------------------------
407 AAI receives URLs from clients that point back to that client in order
408 to get more details about the data sent to AAI. AAI expects the URLs
409 sent by clients (e.g., self links) to be URL encoded (UTF-8) and AAI
410 will store them unchanged.
412 URLs that AAI constructs that point to AAI resources will be returned
413 URLEncoded (UTF-8) to clients. This affects URLs in relationship lists
416 AAI expects space to be %20, and not plus(+).
418 The Relationship-List
419 ---------------------
421 The REST interface does not lend itself to creating more than
422 parent-child relationships and the backend structure of AAI is a graph.
423 A goal of AAI is to do as little coding as possible to introduce a new
424 service into the service design and creation environment.
426 To that end, we've introduced a relationship-list structure. AAI will
427 ask its clients to provide certain data in the relationship-list
430 Each relationship has a related-to attribute and a list of key/value
431 pairs. The related-to attribute identifies the node type that the
432 resource being acted on is to be related to using the data in the
433 key/value pairs. AAI will encode a set of rules for each resource type
434 to verify that only valid edges are being made. AAI will keep the name
435 of the edge itself, the directionality and cardinality, and the edge
436 attributes within its own logic.
438 If an attempt is made to add a relationship to a node that doesn't exist
439 (e.g., from a vserver to a vnf, and the vnf doesn't exist), a unique
440 message Id (3003) will be returned with a specific error code
441 (ERR.5.4.6129). Arguments will tell the client which node type was
442 missing (e.g., generic-vnf) and the key data for that node type
443 (generic-vnf.vnf-id).
445 Single relationships can be PUT to the graph in the following way:
447 https://{serverRoot}/{namespace}/{resource}
448 /relationship-list/relationship
452 https://{hostname}:8443/aai/v11/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
454 with a payload containing the relationship information.
458 <relationship xmlns="http://org.openecomp.aai.inventory/v11">
460 <related-to>logical-link</related-to>
464 <relationship-key>logical-link.link-name</relationship-key>
466 <relationship-value>logical-link-123456789-01</relationship-value>
474 "related-to": "logical-link",
476 "relationship-data": [
480 "relationship-key": "logical-link.link-name",
482 "relationship-value": " logical-link-123456789-01"
493 The following are the properties used for edge definitions. T is true, F
496 - From and To are the node types for the ends of the edges.
498 - EdgeLabel is the name of the label within the graph.
500 - Direction shows the direction of the edge.
502 - Multiplicity shows the multiplicity rule between two nodes. This
503 helps govern what AAI does when modifying relationships between edges
504 using the relationship REST APIs
506 - ParentOf indicates whether From is a parent of To.
508 - UsesResource specifies whether the From node uses resources of the To
509 node, to be able to view the data in the context of "what uses what".
511 - hasDelTarget specifies whether to try to delete the To node when the
512 From node is deleted.
514 - SVC-INFRA (deprecated)
516 The configuration for different edges supported by the AAI model are
517 defined in the DbEdgeRules.java class.
522 AAI supports query parameters on its indexed attributes.
524 As an example, if you wanted to GET a tenant by tenant-name, you would
527 /aai/vX/cloud-infrastructure/cloud-regions/cloud-region/cloud\_owner\_1/cloud-region\_1/tenants/tenant?tenant-name=value
529 The properties that are indexed are defined in the aai-schema.
537 The util domain is where AAI locates utility functions. There is
538 currently one utility function, echo, which serves as a ping test that
539 authenticated authorized clients can call to ensure there is
540 connectivity with AAI.
542 The URL for the echo utility is:
544 https://load-balanced-address:8443/aai/util/echo
546 If the response is unsuccessful, an error will be returned following the
549 The successful payload returns the X-FromAppId and X-TransactionId sent
552 Successful XML Response Payload
553 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
561 <messageId>INF0001</messageId>
563 <text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text>
567 <variable>XYZ</variable>
569 <variable>XYZ123</variable>
571 <variable>Successful health check:OK</variable>
573 <variable>0.0.0002</variable>
583 Successful JSON Response Payload
584 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
586 {"responseMessages": {"responseMessage": [{
588 "messageId": "INF0001",
590 "text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)",
592 "variables": {"variable": [
598 "Successful health check:OK",
606 Cloud Infrastructure Domain
607 ---------------------------
609 The Cloud Infrastructure domain (cloud-infrastructure) represents the
610 assets managed within a cloud infrastructure site. This includes the
611 physical servers, tenants, vservers and cloud-region.
616 The network namespace contains virtual and physical network resources as
617 well as connection resources such as physical links, logical links, etc.
622 The business namespace captures customers, service subscriptions, and
623 service instances. This domain is immature and will be evolving as
624 service design and creation starts to gel.
626 Service Design and Creation
627 ---------------------------
629 The service design and creation namespace captures data we invented
630 based on what we thought SDC would eventually provide.
632 To date, there are only five containers:
634 1. Service-capabilities capture the pairings of service to resources.
636 2. Service captures the service model instances and this will be
637 deprecated in the future as things mature
639 3. Models captures model definitions (subgraph definitions using the AAI
642 4. named-queries capture subgraph definitions that allow different data
643 to be retrieved for a given type of asset