diff options
| -rw-r--r-- | docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst b/docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst new file mode 100644 index 00000000..9cff428b --- /dev/null +++ b/docs/AAI REST API Documentation/AAIRESTAPI_AMSTERDAM.rst @@ -0,0 +1,642 @@ +.. contents:: + :depth: 3 +.. + +AAI REST API + +| Copyright © 2017 AT&T Intellectual Property. +| All rights reserved. +| Licensed under the Creative Commons License, Attribution 4.0 Intl. + (the "License"); you may not use this documentation except in + compliance with the License. +| You may obtain a copy of the License at +| https://creativecommons.org/licenses/by/4.0/ +| Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing + permissions and limitations under the License. +| ECOMP and OpenECOMP are trademarks and service marks of AT&T + Intellectual Property. + +\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +Overview +======== + +The AAI REST API provides access to the AAI active inventory graph. The +API is largely configured off of models and configuration files. Each +vertex in the graph has an API that can be called separately or, if part +of a tree structure, as a nested element with one or more generations +(parent, grandparent, etc.). + +The edges of the graph are provisioned using a relationship list +construct. For PUT methods, a relationship contains the vertex type or +category (related-to) and a list of relationship data which captures the +key pieces of data required to uniquely identify the resource. On a GET +method, the above information and a URL are returned. The URL can be +used to GET all the details of that object. The URL returned is suitable +for retrying failed commands but should not be expected to be cacheable +for very long periods (e.g., the version of the URL may get deprecated +when the release changes). + +Concurrency control for AAI is in place. The assumptions made for the +implementation are as follows: + +- A client always gets a resource before updating through PUT or + deleting it. + +- All resource updates and deletions are done via the AAI REST APIs + +- This solution will apply to PUT and DELETE operations. + +- The resource-version attribute is now in every container + +- The update API is not subject to concurrency control because it is + only intended to be used by clients who are the definitive source of + truth for the attributes they are changing. An update through the + update API will however reset the resource-version so clients using + PUT and DELETE will not risk updating with stale data. + +- The PATCH REST verb is not subject to concurrency control because it + is only intended to be used by clients who are the definitive source + of truth for the attributes they are changing. An update through the + update API will however reset the resource-version so clients using + PUT and DELETE will not risk updating with stale data. + +How to Use this Document +======================== + +When you click on the API documentation, you will see the Summary of +APIs broken down by namespace (e.g., cloud-infrastructure, business, +network, service-design-and-creation). You can search for **Tag:** +(matching the explicit case) to move from namespace to namespace through +the Summary. + +Search for **Paths** to skip past the Summary section where there will +be more detail about each API. Query parameters are provided here, as +well as links to our error codes. + +Search for **Schema definitions** to see the definitions of the +payloads. In your browser URL, you can type /#/definitions/node-name at +the end of the html address to skip directly to a payload definition. + +Note that the schema definitions now contain information about the +delete scope of a node (also referenced in this document) and some +related node information (also reference in this document as Edges). + +Once AAI has a model and configured it, the AAI development server can +be used to generate sample XML and JSON payloads, according to the +Accept header passed in the request. This is done by calling the +"plural" version of an API followed by the word example (e.g., +/vserver/vservers/example). This returns a GET result array with one +entry. That single entry can be sent in a PUT request with actual data +(the resource-id does not need to be in the PUT payload as it is on the +URL). + +Document Conventions +==================== + +Information that is largely guidance or aspirational will be show in +gray italicized text. This information should not be relied upon or +referenced at this point except with the understanding that it WILL +change. + +**Bold blue text** will be used to cover communication to our clients +that may not be enforced by AAI. The sources of truth (our clients) +populate AAI and are expected to send the correct information, having +applied business rules that live in the client systems. + +Deprecation Warnings and History +================================ + +V11 + +API retirements: + +- The actions/update API will be retired. Clients must switch to PATCH. + There is one grandfathered usage for vpe update flows which will be + retired in v11. + +- The edge tag query will be retired. + +Notable attribute and/or valid value changes (generally also impacts +events): + +- The persona-model-id and persona-version will be replaced with + model-invariant-id (same value as persona-model-id) and + model-version-id (the UUID of the specific version of a model). + Persona-model-customization-id will be replaced by + model-customization-id. + +- The operational-state attribute will be replaced by + operational-status and the only valid values will be in-service-path + and out-of-service-path + +- The vpn-binding object will be split in two to reflect more than one + route-target per binding. The route-target will be a child of + vpn-binding and some attributes will move from vpn-binding to + route-target. + +- The following license related attributes will be removed from + generic-vnf: license-key, entitlement-assignment-group-uuid, + entitlement-resource-uuid, license-assignment-group-uuid, and + license-key-uuid due to the introduction of the entitlement and + license children. + +Event Specific: + +- Normal impacts due to renaming or adding attributes, splitting + objects, etc. Please see swagger documentation for objects of + interest. + +- In v11, clients that require lineage, children, or relationship + information need to subscribe to a different DMaaP topic than the + current one. + +Relationship List + +- The related-link will be a URI and thus not contain + https://{serverroot} (impacts events) + +- Thhe related-link will be used on a PUT as the "first choice" to + identify the related resource. The relationship-data structure, which + contains the unordered set of keys, is still an acceptable way to + relate two objects but, *if both the relationship-data and the + related-link are passed, and they don't agree, the related-link will + be used without warning that the data is inconsistent*. + +- The relationship-data will be ignored on PUT. + +AAI API Definition +================== + +The API structure is composed of: + +- The HTTP command, which indicates the operation to perform + +- The HTTP URI, which defines what object this operation is related to + +- The HTTP version, which MUST be 1.1 + +Available HTTP commands are: + +- PUT: used to create or update an object + +- DELETE: used to delete an object or a set of objects + +- GET : used to query an object or set of objects + +- PATCH : used to update specific fields owned by the client doing the + update + +The HTTP URI is built according to this pattern: + +https://{serverRoot}/{namespace}/{resource} + +- (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. The Amsterdam release version will be v11. + +- {namespace} refers to the API namespace. Supported namespaces are + cloud-infrastructure, business, service-design-and-creation, and + network + +- {resource} refers to how the object is identified according to the + namespace specifications. + +Example + +GET https://{hostname}:8443/aai +/v11/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id} + +The GET requests support a depth query parameter allowing a query to +stop after it has reached a certain point in the graph. This allows +clients to minimize the data that is returned to them. A depth=0 returns +the resource itself and none of its children. + +Data Assumptions +---------------- + +Given AAI is largely a correlation engine among disparate inventory +types, AAI will accept values as they are sent, without validating the +format or value of the input. It is incumbent upon the source of truth +to provide valid information to AAI. + +Clients should do a GET prior to a PUT and change only the data that +they mean to affect. The REST APIs expect the payload passed to replace +the resource in AAI. **This is vital in our concurrency scheme. The +client will be returned an opaque value per entity which needs to be +returned back in the PUT. AAI will reject the PUT or DELETE if the +opaque value doesn't match what AAI has stored for that entity.** + +If a leaf has been added to a model in vN+1, and a GET/PUT of a vN +resource is done, AAI should not affect the new leaf (i.e., it should be +left unchanged). + +PUT and Lists +------------- + +The PUT verb is used to both create and replace a resource. A given +resource may have child resources (e.g., customers have service +subscriptions; tenants have vservers and vservers have volumes). + +The following convention will be followed: + +If a resource is replaced and there are no tags for children, the +children that exist will be left alone. + +If a resource is replaced and there are tags for children, the children +will be replaced by the list passed. If the list is empty, then children +will be deleted. + +Note that the relationship list is a type of child resource. The same +conventions are followed. It is especially critical to ensure that you +do not send an incomplete relationship list and therefore remove edges +in the graph. See section 5.10 for more information on relationship +lists. + +PATCH +----- + +To move towards industry standards and to make our APIs easier to use by +clients who own specific attributes and do not require AAI to enforce +concurrency control around them, the PATCH verb has been introduced. + +- RFC Algorithm implemented JSON Merge PATCH + `tools.ietf.org/html/rfc7386 <https://tools.ietf.org/html/rfc7386>`__ + +- *HTTP Verb = PATCH* + +- PATCH requires a Content-Type of "application/merge-patch+json" in + your HTTP headers. + +- PATCH does not support XML + +- PATCH does not require a resource version to preform these + modifications + +- Clients should only send what they wish to modify and whose value + they "own" + +Example: + +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>`__ + + { + + "vnf-id": "cscf0001v", This key needs to be here but you cannot +modify the key + + "regional-resource-zone": null, + + "ipv4-oam-address": "1.2.3.4" + +} + +This payload would result in the generic-vnf with the vnf-id = cscf0001v +having ipv4-oam-address set to "1.2.3.4" and regional-resource-zone +having its value removed from the database. + +Referential Integrity +--------------------- + +AAI is primarily a view to the relationships between customers, +products, services, physical and virtual components, etc. It stores just +the details it needs to be efficient to its tasks and knows how to get +more details if needed. + +As such, a transaction sent to AAI may be refused if would break +referential integrity. The referential integrity rules of AAI are still +evolving as we understand the services and customers that will use us. + +AAI uses a graph database on a NoSQL data store. The following are true +for AAI: + +- Some vertices are exposed to the outside world through APIs, others + are internal to how we store the data (i.e., it may look like one + resource to our customers but it is expressed as more than one vertex + in our graph) + +- Vertices that are internal to AAI will be deleted when the parent + vertex is deleted, if deletion of the parent leaves the child vertex + orphaned + +- Vertices that are exposed need to be managed using specific rules for + each vertex. + +- Vertices may have more than just parent/child relationships. One + example is a vserver, which will be owned by a tenant and used by a + VNF. + +Delete Rules +------------ + +The following options are available as actions to be take upon deletion +of a resource: + +- ERROR\_IF\_ANY\_EDGES – If the resource being deleted has any edges + at all, an error should be returned + +- ERROR\_IF\_ANY\_IN\_EDGES – if the resource being deleted has any + edges that point IN towards it, an error should be returned + +- THIS\_NODE\_ONLY – delete the vertex being requested by first + deleting its edge to other vertices, but do not delete the other + vertices. Note, the delete will be rejected if the deletion target + has DEPENDENT children (e.g., tenants that have vservers) + +- CASCADE\_TO\_CHILDREN – cascade the delete through vertices who have + a parentOf relationship to the vertex being deleted, as long as the + vertex is orphaned by the delete of its parent + +- ERROR\_4\_IN\_EDGES\_OR\_CASCADE – error if there are any in edges + and, if not, cascade to children + +Security +-------- + +All REST APIs must be called using https. + +The current release is configured to support BasicAuth. 2-way SSL using +client certificates should be configured for production deployments or +as needed. + +Headers +------- + +The following will be used for logging and interface diagnostic +purposes. + +- X-FromAppId Unique Application ID assigned to the user of these APIs + +- X-TransactionId Unique ID that identifies an API request + +The X-FromAppId will be assigned to each application by the AAI team. +The X-TransactionId must be unique to each transaction within the +context of an X-FromAppId. + +OpenECOMP components that call AAI use the Java UUID class to generate +unique ids for X-TransactionId. + +The Accept header should be set to either application/json or +application/xml. + ++-------------------------------+---------------+ +| Client | X-FromAppId | ++===============================+===============+ +| Policy | Policy | ++-------------------------------+---------------+ +| Master Service Orchestrator | MSO | ++-------------------------------+---------------+ +| SDN Controller | SDNC | ++-------------------------------+---------------+ +| Application Controller | APPC | ++-------------------------------+---------------+ + +Response Codes and Error Handling +--------------------------------- + +HTTP response codes and error codes are described in the API +documentation. + +URLs Sent To and Retrieved From AAI +----------------------------------- + +AAI receives URLs from clients that point back to that client in order +to get more details about the data sent to AAI. AAI expects the URLs +sent by clients (e.g., self links) to be URL encoded (UTF-8) and AAI +will store them unchanged. + +URLs that AAI constructs that point to AAI resources will be returned +URLEncoded (UTF-8) to clients. This affects URLs in relationship lists +and search results. + +AAI expects space to be %20, and not plus(+). + +The Relationship-List +--------------------- + +The REST interface does not lend itself to creating more than +parent-child relationships and the backend structure of AAI is a graph. +A goal of AAI is to do as little coding as possible to introduce a new +service into the service design and creation environment. + +To that end, we've introduced a relationship-list structure. AAI will +ask its clients to provide certain data in the relationship-list +structure. + +Each relationship has a related-to attribute and a list of key/value +pairs. The related-to attribute identifies the node type that the +resource being acted on is to be related to using the data in the +key/value pairs. AAI will encode a set of rules for each resource type +to verify that only valid edges are being made. AAI will keep the name +of the edge itself, the directionality and cardinality, and the edge +attributes within its own logic. + +If an attempt is made to add a relationship to a node that doesn't exist +(e.g., from a vserver to a vnf, and the vnf doesn't exist), a unique +message Id (3003) will be returned with a specific error code +(ERR.5.4.6129). Arguments will tell the client which node type was +missing (e.g., generic-vnf) and the key data for that node type +(generic-vnf.vnf-id). + +Single relationships can be PUT to the graph in the following way: + +https://{serverRoot}/{namespace}/{resource} +/relationship-list/relationship + +or + +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 + +with a payload containing the relationship information. + +XML: + +<relationship xmlns="http://org.openecomp.aai.inventory/v11"> + +<related-to>logical-link</related-to> + +<relationship-data> + + <relationship-key>logical-link.link-name</relationship-key> + + <relationship-value>logical-link-123456789-01</relationship-value> + +</relationship-data> + +</relationship> + +JSON: + +"related-to": "logical-link", + +"relationship-data": [ + +{ + + "relationship-key": "logical-link.link-name", + + "relationship-value": " logical-link-123456789-01" + +} + +] + +} + +Edges +===== + +The following are the properties used for edge definitions. T is true, F +is false + +- From and To are the node types for the ends of the edges. + +- EdgeLabel is the name of the label within the graph. + +- Direction shows the direction of the edge. + +- Multiplicity shows the multiplicity rule between two nodes. This + helps govern what AAI does when modifying relationships between edges + using the relationship REST APIs + +- ParentOf indicates whether From is a parent of To. + +- UsesResource specifies whether the From node uses resources of the To + node, to be able to view the data in the context of "what uses what". + +- hasDelTarget specifies whether to try to delete the To node when the + From node is deleted. + +- SVC-INFRA (deprecated) + +The configuration for different edges supported by the AAI model are +defined in the DbEdgeRules.java class. + +Indexed Attributes +=================== + +AAI supports query parameters on its indexed attributes. + +As an example, if you wanted to GET a tenant by tenant-name, you would +do something like + +/aai/vX/cloud-infrastructure/cloud-regions/cloud-region/cloud\_owner\_1/cloud-region\_1/tenants/tenant?tenant-name=value + +The properties that are indexed are defined in the aai-schema. + +Namespaces +========== + +Util Domain +----------- + +The util domain is where AAI locates utility functions. There is +currently one utility function, echo, which serves as a ping test that +authenticated authorized clients can call to ensure there is +connectivity with AAI. + +The URL for the echo utility is: + +https://load-balanced-address:8443/aai/util/echo + +If the response is unsuccessful, an error will be returned following the +standard format. + +The successful payload returns the X-FromAppId and X-TransactionId sent +by the client. + +Successful XML Response Payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +<Info> + +<responseMessages> + +<responseMessage> + +<messageId>INF0001</messageId> + +<text>Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)</text> + +<variables> + +<variable>XYZ</variable> + +<variable>XYZ123</variable> + +<variable>Successful health check:OK</variable> + +<variable>0.0.0002</variable> + +</variables> + +</responseMessage> + +</responseMessages> + +</Info> + +Successful JSON Response Payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +{"responseMessages": {"responseMessage": [{ + +"messageId": "INF0001", + +"text": "Success X-FromAppId=%1 X-TransactionId=%2 (msg=%3) (rc=%4)", + +"variables": {"variable": [ + +"XYZ", + +"XYZ123", + +"Successful health check:OK", + +"0.0.0002" + +]} + +}]}} + +Cloud Infrastructure Domain +--------------------------- + +The Cloud Infrastructure domain (cloud-infrastructure) represents the +assets managed within a cloud infrastructure site. This includes the +physical servers, tenants, vservers and cloud-region. + +Network Domain +-------------- + +The network namespace contains virtual and physical network resources as +well as connection resources such as physical links, logical links, etc. + +Business Domain +--------------- + +The business namespace captures customers, service subscriptions, and +service instances. This domain is immature and will be evolving as +service design and creation starts to gel. + +Service Design and Creation +--------------------------- + +The service design and creation namespace captures data we invented +based on what we thought SDC would eventually provide. + +To date, there are only five containers: + +1. Service-capabilities capture the pairings of service to resources. + +2. Service captures the service model instances and this will be + deprecated in the future as things mature + +3. Models captures model definitions (subgraph definitions using the AAI + widgets) + +4. named-queries capture subgraph definitions that allow different data + to be retrieved for a given type of asset |