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