aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJimmy Forsyth <jf2512@att.com>2019-02-15 11:30:33 -0500
committerJames Forsyth <jf2512@att.com>2019-02-15 16:35:10 +0000
commit9f4fd07e39abf072b8eb8c9f51644e7056722a79 (patch)
tree902fd5bc952c872c9fe5c289e3ae42aa3a15b3e6
parent6c6d4eaafaa428ac5bac544d3f427e3e372769ea (diff)
Add bulkApi documentation
Issue-ID: AAI-2157 Change-Id: Ic4e7a1b2ae56036c2ce475608b524c3329c481d4 Signed-off-by: Jimmy Forsyth <jf2512@att.com>
-rw-r--r--docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst2
-rw-r--r--docs/AAI REST API Documentation/bulkApi.rst275
2 files changed, 276 insertions, 1 deletions
diff --git a/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst b/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst
index cb23ae50..a15c8f51 100644
--- a/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst
+++ b/docs/AAI REST API Documentation/AAIRESTAPI_CASABLANCA.rst
@@ -1029,7 +1029,7 @@ Bulk APIs
The Bulk API allows clients to make multiple requests in a single
transaction. Please look for additional details on the following wiki
-page
+page: `Bulk API <bulkApi.html>`_
AAI Traversal APIs
==================
diff --git a/docs/AAI REST API Documentation/bulkApi.rst b/docs/AAI REST API Documentation/bulkApi.rst
new file mode 100644
index 00000000..c292deab
--- /dev/null
+++ b/docs/AAI REST API Documentation/bulkApi.rst
@@ -0,0 +1,275 @@
+.. contents::
+ :depth: 3
+..
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+=============
+ AAI Bulk API
+=============
+
+This page will serve as a reference for how to use the A&AI bulk API's available in 1810+.
+
+Bulk Overview
+=============
+
+To execute any of the bulk api's, a client will perform a POST on the specific bulk api and include a payload indicating the nodes to be added/updated/deleted.The version (v$ ie. v14) dictates which release's REST API version the output will be based on.
+
+Single transaction API
+======================
+
+API takes in transaction object which consists of an array of operations, the operations are executed against A&AI in a single transaction. All operations must succeed for the actions to be committed. If any of the operations fail these changes will be rolled back.
+
+API URI
+=======
+
+.. code::
+
+ URI
+ POST /aai/v$/bulk/single-transaction
+ Payload
+ Skeleton
+ {
+ "operations": [ //array of operations for this transaction
+ {
+ "action": "", //aai action to be taken, i.e put, patch, delete
+ "uri": "", //aai uri to execute action against
+ "body": {} //json object which is the body of the equivalent REST request
+ }
+ ]
+ }
+
+Response
+
+.. code::
+
+ Skeleton
+ {
+ "operation-responses": [ //result of each of the request operations
+ {
+ "action": "", //aai action that was taken
+ "uri": "", //aai uri that was executed against
+ "response-status-code": , //http status code
+ "response-body": null // response body of the of the equivalent REST request
+ }
+ ]
+ }
+
+Request-Response Examples
+=========================
+
+Example - 1 (Success)
++++++++++++++++++++++
+
+.. code::
+
+ Request
+ {
+ "operations": [
+ {
+ "action": "put",
+ "body": {
+ "fqdn": "pserver-key-fqdn",
+ "hostname": "pserver-1-key"
+ },
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-1-key"
+ },
+ {
+ "action": "patch",
+ "body": {
+ "fqdn": "patched-fqdn"
+ },
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-1-key"
+ },
+ {
+ "action": "put",
+ "body": {
+ "fqdn": "pserver-key-fqdn",
+ "hostname": "pserver-2-key"
+ },
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-2-key"
+ }
+ ]
+ }
+
+Response
+++++++++
+.. code::
+
+ {
+ "operation-responses": [
+ {
+ "action": "put",
+ "response-body": null,
+ "response-status-code": 201,
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-1-key"
+ },
+ {
+ "action": "patch",
+ "response-body": null,
+ "response-status-code": 200,
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-1-key"
+ },
+ {
+ "action": "put",
+ "response-body": null,
+ "response-status-code": 201,
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-2-key"
+ }
+ ]
+ }
+
+Example - 2 (Success)
+=====================
+Request
++++++++
+
+.. code::
+
+ {
+ "operations": [
+ {
+ "action": "put",
+ "body": {
+ "fqdn": "pserver-key-fqdn",
+ "hostname": "pserver-key"
+ },
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-key"
+ },
+ {
+ "action": "put",
+ "body": {
+ "city": "city",
+ "country": "NONE",
+ "data-center-code": "code",
+ "identity-url": "N/A",
+ "physical-location-id": "complex-key",
+ "physical-location-type": "type",
+ "postal-code": "12345",
+ "region": "Earth",
+ "state": "state",
+ "street1": "street"
+ },
+ "uri": "/cloud-infrastructure/complexes/complex/complex-key"
+ },
+ {
+ "action": "put",
+ "body": {
+ "related-link": "/aai/v13/cloud-infrastructure/pservers/pserver/pserver-key",
+ "related-to": "pserver"
+ },
+ "uri": "/cloud-infrastructure/complexes/complex/complex-key/relationship-list/relationship"
+ },
+ {
+ "action": "delete",
+ "body": {},
+ "uri": "/network/generic-vnfs/generic-vnf/gvnf-key?resource-version=0"
+ }
+ ]
+ }
+
+Response
+++++++++
+
+.. code::
+
+ {
+ "operation-responses": [
+ {
+ "action": "put",
+ "response-body": null,
+ "response-status-code": 201,
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-key"
+ },
+ {
+ "action": "put",
+ "response-body": null,
+ "response-status-code": 201,
+ "uri": "/cloud-infrastructure/complexes/complex/complex-key"
+ },
+ {
+ "action": "put",
+ "response-body": null,
+ "response-status-code": 200,
+ "uri": "/cloud-infrastructure/complexes/complex/complex-key/relationship-list/relationship"
+ },
+ {
+ "action": "delete",
+ "response-body": null,
+ "response-status-code": 204,
+ "uri": "/network/generic-vnfs/generic-vnf/gvnf-key?resource-version=0"
+ }
+ ]
+ }
+
+Example - 3 (Failure on mismatched resource version on delete)
+==============================================================
+Request
++++++++
+
+.. code::
+
+ {
+ "operations": [
+ {
+ "action": "put",
+ "body": {
+ "fqdn": "pserver-key-fqdn",
+ "hostname": "pserver-key"
+ },
+ "uri": "/cloud-infrastructure/pservers/pserver/pserver-key"
+ },
+ {
+ "action": "put",
+ "body": {
+ "city": "city",
+ "country": "NONE",
+ "data-center-code": "code",
+ "identity-url": "N/A",
+ "physical-location-id": "complex-key",
+ "physical-location-type": "type",
+ "postal-code": "12345",
+ "region": "Earth",
+ "state": "state",
+ "street1": "street"
+ },
+ "uri": "/cloud-infrastructure/complexes/complex/complex-key"
+ },
+ {
+ "action": "put",
+ "body": {
+ "related-link": "/aai/v13/cloud-infrastructure/pservers/pserver/pserver-key",
+ "related-to": "pserver"
+ },
+ "uri": "/cloud-infrastructure/complexes/complex/complex-key/relationship-list/relationship"
+ },
+ {
+ "action": "delete",
+ "body": {},
+ "uri": "/network/generic-vnfs/generic-vnf/gvnf-key?resource-version=1"
+ }
+ ]
+ }
+
+Response
+++++++++
+
+.. code::
+
+ {
+ "requestError": {
+ "serviceException": {
+ "messageId": "SVC3000",
+ "text": "Invalid input performing %1 on %2 (msg=%3) (ec=%4)",
+ "variables": [
+ "POST",
+ "/aai/v14/bulk-single-transaction-multi-operation",
+ "Invalid input performing %1 on %2:Operation 3 failed with status code (412) and msg ({\"requestError\":{\"serviceException\":{\"messageId\":\"SVC3000\",\"text\":\"Invalid input performing %1 on %2 (msg=%3) (ec=%4)\",\"variables\":[\"DELETE\",\"/network/generic-vnfs/generic-vnf/gvnf-key\",\"Precondition Failed:resource-version MISMATCH for delete of generic-vnf\",\"ERR.5.4.6131\"]}}})",
+ "ERR.5.2.3000"
+ ]
+ }
+ }
+ }
+