Update the README.md documentation.

[aai/search-data-service.git] / BULK.md

diff --git a/BULK.md b/BULK.md
new file mode 100644 (file)
index 0000000..534bbd0
--- /dev/null
+++ b/BULK.md
@@ -0,0 +1,142 @@
+# Bulk Operations\r
+\r
+## Overview\r
+\r
+Bulk operations allow the client to bundle a number of actions into a single REST request.\r
+\r
+It is important to note that the individual operations bundled into a bulk request are considered by the Search Service to be completely independent operations.  This has a few consequences:\r
+\r
+* No guarantees are made with respect to the order in which the individual operations will be processed by the document store.\r
+\r
+* There is no implied transactionality between the operations.  The operations may succeed or fail independently of one another, and it is entirely possible to get back a result set indicating a mix of success and failure results for the individual operations.\r
+\r
+## Syntax\r
+\r
+The request payload of a bulk operation must be structured in the following manner (we will flesh out this pseudo-json with a concrete example further down):\r
+\r
+    [\r
+        { <operation> : { <meta-data>, <document>  } },\r
+                            .\r
+                            .\r
+        { <operation> : { <meta-data>, <document>  } }\r
+    ]\r
+    \r
+**Operation**\r
+The following table describes the operations which are supported as part of a _Bulk_ request:\r
+\r
+| Operation | Behaviour                                      | Expected Meta Data     | Expected Payload  |\r
+| --------- | ---------------------------------------------- | ---------------------- | ----------------- |\r
+| create    | Insert a new document into the document store. | document url           | document contents |   \r
+| update    | Update an existing document.                   | document url, etag     | document contents |\r
+| delete    | Remove a document from the document store.     | document url, etag     | none              |  \r
+           \r
+**Meta-Data**\r
+Depending on the operation being requested, certain additional meta-data is required for the _Search Date Service_ to be able to carry out the operation.  These are described in the _operations_ table above.\r
+\r
+**Document**\r
+For those operations which involve creating or updating a _Document_, the contents of the document must be provided.\r
+\r
+_Example - Simple Bulk Request including all supported operations:_\r
+\r
+Request Payload:\r
+\r
+       [\r
+         {\r
+           "create": {\r
+             "metaData": {\r
+               "url": "/indexes/my-index/documents/"\r
+             },\r
+             "document": {\r
+               "field1": "value1",\r
+               "field2": "value2"\r
+             }\r
+           }\r
+         },\r
+         {\r
+           "update": {\r
+             "metaData": {\r
+               "url": "/indexes/my-other-index/documents/3",\r
+               "etag": "5"\r
+             },\r
+             "document": {\r
+               "field1": "some-value"\r
+             }\r
+           }\r
+         },\r
+         {\r
+           "delete": {\r
+             "metaData": {\r
+               "url": "/indexes/my-index/documents/7"\r
+             }\r
+           }\r
+         }\r
+       ]\r
+\r
+Response Payload:\r
+\r
+       { \r
+           "total_operations": 3, \r
+           "total_success": 2, \r
+           "total_fails": 1, \r
+           "results": [\r
+               {\r
+                   "operation": "create", \r
+                   "url": "/services/search-data-service/v1/indexes/my-index/documents/1", \r
+                   "etag": "1", \r
+                   "status-code": "409", \r
+                   "status-message": "[default][1]: document already exists"\r
+               }, \r
+               {\r
+                   "operation": "update", \r
+                   "url": "/services/search-data-service/v1/indexes/my-other-index/documents/3", \r
+                   "etag": 6, \r
+                   "status-code": "200", "status-message": "OK"\r
+               }, \r
+               {\r
+                   "operation": "delete", \r
+                   "url": "/services/search-data-service/v1/indexes/my-index/documents/7", \r
+                   "status-code": "200", "status-message": "OK"\r
+               }\r
+           ]\r
+       }\r
+       \r
+## API\r
+\r
+**Submit A Bulk Operation**\r
+---\r
+**URL**\r
+\r
+    https://{host}:9509/services/search-data-service/v1/search/bulk/\r
+\r
+**Method** \r
+\r
+    POST\r
+\r
+**URL Params**\r
+\r
+    None\r
+\r
+**Request Header**\r
+\r
+    Accept          = application/json\r
+    X-TransactionId = Unique id set by client (for logging purposes)\r
+    X-FromAppId     = Application identifier (for logging purposes)\r
+    Content-Type    = application/json\r
+    \r
+**Request Payload**\r
+\r
+    Set of bulk operations to be executed (see Syntax Section) \r
+\r
+**Success Response**\r
+\r
+    Code:      207 (Multi-Staltus)\r
+    Header(s): None\r
+    Body:      JSON format result set which includes individual status codes for each requested operation.  \r
+    \r
+**Error Response**\r
+\r
+    400 - Bad Request\r
+    403 - Unauthorized\r
+    500 - Internal Error\r
+\r
+---\r