Adding AAI REST API document

Issue ID: AAI-218

Change-Id: Ib9fda8ae10b25bedd61e09178621a268d608f851
Signed-off-by: O'Connor, Lina (lo8949) <lo8949@att.com>

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