DOCUMENTS.md

   1 # Documents\r
   2 \r
   3 ## Overview\r
   4 _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
   5 \r
   6 \r
   7 ## Syntax\r
   8 _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
   9 \r
  10 For a discussion of how to specify the _Document Structure_, refer to [Index API](./INDEXES.md). \r
  11 \r
  12 **Example - Simple Document **\r
  13 \r
  14     {\r
  15        "FirstName": "Bob",\r
  16        "LastName": "Smith",\r
  17        "Age": 43\r
  18     }\r
  19 \r
  20 **Example - Document With Nested Fields **\r
  21 \r
  22     {\r
  23         "FirstName": "Sherlock",\r
  24         "LastName": "Holmes",\r
  25         "Address": {\r
  26                 "Street": "222B Baker",\r
  27                 "City": "London",\r
  28                 "Country": "England"\r
  29         }\r
  30     }\r
  31     \r
  32 ## API\r
  33 \r
  34 ### Create Document\r
  35 Persists a _Document_ in an _Index_ in the _Search Data Service_.\r
  36 \r
  37 Note, that there are two variants of document creation: with and without supplying an id to associate with the document.\r
  38 \r
  39 **Create Document (No Id Specified)**\r
  40 \r
  41 If no _Id_ is provided by the client, then a unique identifier will be generated by the _Search Data Service_.\r
  42 \r
  43 ---\r
  44 **URL**\r
  45 \r
  46     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/\r
  47 \r
  48 **Method** \r
  49 \r
  50     POST\r
  51 \r
  52 **URL Params**\r
  53 \r
  54     index - The name of the _Index_ to persist the _Document_ in.\r
  55 \r
  56 **Request Header**\r
  57 \r
  58     X-Create-Index  = true = Allow index to be implicitly created if it does not already exist in the document store.\r
  59     \r
  60 **Request Payload**\r
  61 \r
  62     Document contents expressed as a JSON object. (see **Syntax**) \r
  63 \r
  64 **Success Response**\r
  65 \r
  66     Code:      201\r
  67     Header(s): ETag = ETag for the document instance that was just created.\r
  68     Body:      URL identifying the document that was just created.  \r
  69                Example:\r
  70                      {"url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"}\r
  71     \r
  72 **Error Response**\r
  73 \r
  74     400 - Bad Request\r
  75     403 - Unauthorized\r
  76     500 - Internal Error\r
  77 \r
  78 ---\r
  79 \r
  80 **Create Document (Client Supplied Id)**\r
  81 \r
  82 If the client supplies an identifier for its document then that is what will be used for the document id.\r
  83 \r
  84 _NOTE: If a document id is supplied then it is the responsibility of the client to ensure uniqueness._  \r
  85 \r
  86 ---\r
  87 **URL**\r
  88 \r
  89     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
  90 \r
  91 **Method** \r
  92 \r
  93     PUT\r
  94 \r
  95 **URL Params**\r
  96 \r
  97     index - The name of the _Index_ to persist the Document in.\r
  98     id    - The identifier to associate with this Document.\r
  99 \r
 100 **Request Header**\r
 101 \r
 102     X-Create-Index  = true = Allow index to be implicitly created if it does not already exist in the document store.\r
 103     \r
 104 **Request Payload**\r
 105 \r
 106     Document contents expressed as a JSON object. (see **Syntax**) \r
 107 \r
 108 **Success Response**\r
 109 \r
 110     Code:      201\r
 111     Header(s): ETag = ETag for the document instance that was just created.\r
 112     Body:      URL identifying the document that was just created.  \r
 113                Example:\r
 114                      {"url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"}\r
 115     \r
 116 **Error Response**\r
 117 \r
 118     400 - Bad Request\r
 119     403 - Unauthorized\r
 120     409 - Conflict -- Will occur if a document with that Id already exists\r
 121     500 - Internal Error\r
 122 \r
 123 ---\r
 124 \r
 125 \r
 126 ### Retrieve Document\r
 127 Perform a straight look up of a particular _Document_ by specifying its unique identifier.\r
 128 \r
 129 ---\r
 130 **URL**\r
 131 \r
 132     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
 133 \r
 134 **Method** \r
 135 \r
 136     GET\r
 137 \r
 138 **URL Params**\r
 139 \r
 140     index - The name of the _Index_ to persist the Document in.\r
 141     id    - The identifier to associate with this Document.\r
 142 \r
 143 **Request Payload**\r
 144 \r
 145     NONE \r
 146 \r
 147 **Success Response**\r
 148 \r
 149     Code:      200\r
 150     Header(s): ETag = ETag indicating the current version of the document.\r
 151     Body:      Document contents expressed as a JSON object.  \r
 152                Example:\r
 153                      {\r
 154                          "url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"\r
 155                          "content": {\r
 156                              "firstName": "Bob",\r
 157                              "lastName": "Smith",\r
 158                              "age": 43\r
 159                          }    \r
 160                      }\r
 161     \r
 162 **Error Response**\r
 163 \r
 164     400 - Bad Request\r
 165     404 - Not Found\r
 166     500 - Internal Error\r
 167 \r
 168 ---\r
 169 \r
 170 ### Update Document\r
 171 Replace the contents of a document which already exists in the _Search Data Service_.\r
 172 \r
 173 **Optimistic Locking On Update**\r
 174 \r
 175 The _Search Data Service_ employs an optimistic locking mechanism on _Document_ updates which works as follows:\r
 176 \r
 177 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
 178 \r
 179 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
 180 \r
 181 ---\r
 182 **URL**\r
 183 \r
 184     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
 185 \r
 186 **Method** \r
 187 \r
 188     PUT\r
 189 \r
 190 **URL Params**\r
 191 \r
 192     index - The name of the _Index_ to persist the Document in.\r
 193     id    - The identifier to associate with this Document.\r
 194 \r
 195 **Request Header**\r
 196 \r
 197     Accept          = application/json\r
 198     X-TransactionId = Unique id set by client (for logging purposes)\r
 199     X-FromAppId     = Application identifier (for logging purposes)\r
 200     X-Create-Index  = true = Allow index to be implicitly created if it does not already exist in the document store.\r
 201     Content-Type    = application/json   \r
 202     If-Match        = The ETag value for the document to be updated.\r
 203 \r
 204 **Request Payload**\r
 205 \r
 206     Document contents expressed as a JSON object. (see Syntax Section) \r
 207 \r
 208 **Success Response**\r
 209 \r
 210     Code:      200\r
 211     Header(s): ETag = ETag indicating the current version of the document.\r
 212     Body:      URL identifying the document that was just created.  \r
 213                Example:\r
 214                      {"url": "indexes/myindex/documents/AVgGq2jz4aZeqcwCmlQY"}\r
 215     \r
 216 **Error Response**\r
 217 \r
 218     400 - Bad Request\r
 219     403 - Unauthorized\r
 220     404 - Not Found\r
 221     412 - Precondition Failed -- Supplied ETag does not match the version in the document store.\r
 222     500 - Internal Error\r
 223 \r
 224 ---\r
 225 \r
 226 ### Delete Document\r
 227 Remove an existing _Index_ from the _Search Data Service_.  \r
 228 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
 229 \r
 230 **Optimistic Locking On Update**\r
 231 \r
 232 As for _Document_ updates, the ETag value must be supplied in the _If-Match_ field in the request header.  \r
 233 \r
 234 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
 235 \r
 236 ---\r
 237 **URL**\r
 238 \r
 239     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/documents/{id}\r
 240 \r
 241 **Method** \r
 242 \r
 243     DELETE\r
 244 \r
 245 **URL Params**\r
 246 \r
 247     index - The name of the _Index_ to persist the Document in.\r
 248     id    - The identifier to associate with this Document.\r
 249 \r
 250 **Request Header**\r
 251 \r
 252     Accept          = application/json\r
 253     X-TransactionId = Unique id set by client (for logging purposes)\r
 254     X-FromAppId     = Application identifier (for logging purposes)\r
 255     Content-Type    = application/json\r
 256     If-Match        = The ETag value for the document to be deleted.\r
 257     \r
 258 **Request Payload**\r
 259 \r
 260     NONE \r
 261 \r
 262 **Success Response**\r
 263 \r
 264     Code:      200\r
 265     Header(s): None.\r
 266     Body:      None.  \r
 267     \r
 268 **Error Response**\r
 269 \r
 270     400 - Bad Request\r
 271     403 - Unauthorized\r
 272     404 - Not Found\r
 273     412 - Precondition Failed -- Supplied ETag does not match the version in the document store.\r
 274     500 - Internal Error\r
 275 \r
 276 ---\r