--- /dev/null
+# Documents\r
+\r
+## Overview\r
+_Documents_ represent the _things_ that we want to store in the _Search Data Service_ and are themselves, basically, a set of fields containing the data that we want to persist.\r
+\r
+\r
+## Syntax\r
+_Document_ contents are specified as a simple JSON object. The structure of the _Document_ JSON should match the schema provided to the _Search Data Service_ when the _Index_ was created.\r
+\r
+For a discussion of how to specify the _Document Structure_, refer to [Index API](./INDEXES.md). \r
+\r
+**Example - Simple Document **\r
+\r
+ {\r
+ "FirstName": "Bob",\r
+ "LastName": "Smith",\r
+ "Age": 43\r
+ }\r
+\r
+**Example - Document With Nested Fields **\r
+\r
+ {\r
+ "FirstName": "Sherlock",\r
+ "LastName": "Holmes",\r
+ "Address": {\r
+ "Street": "222B Baker",\r
+ "City": "London",\r
+ "Country": "England"\r
+ }\r
+ }\r
+ \r
+## API\r
+\r
+### Create Document\r
+Persists a _Document_ in an _Index_ in the _Search Data Service_.\r
+\r
+Note, that there are two variants of document creation: with and without supplying an id to associate with the document.\r
+\r
+**Create Document (No Id Specified)**\r
+\r
+If no _Id_ is provided by the client, then a unique identifier will be generated by the _Search Data Service_.\r
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/\r
+\r
+**Method** \r
+\r
+ POST\r
+\r
+**URL Params**\r
+\r
+ index - The name of the _Index_ to persist the _Document_ in.\r
+\r
+**Request Payload**\r
+\r
+ Document contents expressed as a JSON object. (see **Syntax**) \r
+\r
+**Success Response**\r
+\r
+ Code: 201\r
+ Header(s): ETag = ETag for the document instance that was just created.\r
+ Body: URL identifying the document that was just created. \r
+ Example:\r
+ {"url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"}\r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 403 - Unauthorized\r
+ 500 - Internal Error\r
+\r
+---\r
+\r
+**Create Document (Client Supplied Id)**\r
+\r
+If the client supplies an identifier for its document then that is what will be used for the document id.\r
+\r
+_NOTE: If a document id is supplied then it is the responsibility of the client to ensure uniqueness._ \r
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
+\r
+**Method** \r
+\r
+ PUT\r
+\r
+**URL Params**\r
+\r
+ index - The name of the _Index_ to persist the Document in.\r
+ id - The identifier to associate with this Document.\r
+\r
+**Request Payload**\r
+\r
+ Document contents expressed as a JSON object. (see **Syntax**) \r
+\r
+**Success Response**\r
+\r
+ Code: 201\r
+ Header(s): ETag = ETag for the document instance that was just created.\r
+ Body: URL identifying the document that was just created. \r
+ Example:\r
+ {"url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"}\r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 403 - Unauthorized\r
+ 409 - Conflict -- Will occur if a document with that Id already exists\r
+ 500 - Internal Error\r
+\r
+---\r
+\r
+\r
+### Retrieve Document\r
+Perform a straight look up of a particular _Document_ by specifying its unique identifier.\r
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
+\r
+**Method** \r
+\r
+ GET\r
+\r
+**URL Params**\r
+\r
+ index - The name of the _Index_ to persist the Document in.\r
+ id - The identifier to associate with this Document.\r
+\r
+**Request Payload**\r
+\r
+ NONE \r
+\r
+**Success Response**\r
+\r
+ Code: 200\r
+ Header(s): ETag = ETag indicating the current version of the document.\r
+ Body: Document contents expressed as a JSON object. \r
+ Example:\r
+ {\r
+ "url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"\r
+ "content": {\r
+ "firstName": "Bob",\r
+ "lastName": "Smith",\r
+ "age": 43\r
+ } \r
+ }\r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 404 - Not Found\r
+ 500 - Internal Error\r
+\r
+---\r
+\r
+### Update Document\r
+Replace the contents of a document which already exists in the _Search Data Service_.\r
+\r
+**Optimistic Locking On Update**\r
+\r
+The _Search Data Service_ employs an optimistic locking mechanism on _Document_ updates which works as follows:\r
+\r
+The ETag response header field is set in the response for each document create or update to indicate the most recent version of the document in the document store.\r
+\r
+When performing a _Document_ update, this value must be supplied in the _If-Match_ field in the request header. Failure to supply this value, or failure to provide a value which matches the version in the document store will result in a request failure with a 412 (Precondition Failed) error.\r
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
+\r
+**Method** \r
+\r
+ PUT\r
+\r
+**URL Params**\r
+\r
+ index - The name of the _Index_ to persist the Document in.\r
+ id - The identifier to associate with this Document.\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
+ If-Match = The ETag value for the document to be updated.\r
+\r
+**Request Payload**\r
+\r
+ Document contents expressed as a JSON object. (see Syntax Section) \r
+\r
+**Success Response**\r
+\r
+ Code: 200\r
+ Header(s): ETag = ETag indicating the current version of the document.\r
+ Body: URL identifying the document that was just created. \r
+ Example:\r
+ {"url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"}\r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 403 - Unauthorized\r
+ 404 - Not Found\r
+ 412 - Precondition Failed -- Supplied ETag does not match the version in the document store.\r
+ 500 - Internal Error\r
+\r
+---\r
+\r
+### Delete Document\r
+Remove an existing _Index_ from the _Search Data Service_. \r
+Note that this results in the removal of all _Documents_ that are stored in the _Index_ at the time that the DELETE operation occurs.\r
+\r
+**Optimistic Locking On Update**\r
+\r
+As for _Document_ updates, the ETag value must be supplied in the _If-Match_ field in the request header. \r
+\r
+Failure to supply this value, or failure to provide a value which matches the version in the document store will result in a request failure with a 412 (Precondition Failed) error.\r
+\r
+---\r
+**URL**\r
+\r
+ https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
+\r
+**Method** \r
+\r
+ DELETE\r
+\r
+**URL Params**\r
+\r
+ index - The name of the _Index_ to persist the Document in.\r
+ id - The identifier to associate with this Document.\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
+ If-Match = The ETag value for the document to be deleted.\r
+ \r
+**Request Payload**\r
+\r
+ NONE \r
+\r
+**Success Response**\r
+\r
+ Code: 200\r
+ Header(s): None.\r
+ Body: None. \r
+ \r
+**Error Response**\r
+\r
+ 400 - Bad Request\r
+ 403 - Unauthorized\r
+ 404 - Not Found\r
+ 412 - Precondition Failed -- Supplied ETag does not match the version in the document store.\r
+ 500 - Internal Error\r
+\r
+---\r
Code Review / aai / search-data-service.git / blobdiff