Merge pull request #73 from opensearch-project/document-apis

Added get document API and some reorganization

_opensearch/rest-api/document-apis/bulk.md

@@ -1,8 +1,9 @@
 ---
 layout: default
 title: Bulk
-parent: REST API reference
+parent: Document APIs
-nav_order: 5
+grand_parent: REST API reference
+nav_order: 20
 ---
 
 # Bulk
@@ -32,7 +33,7 @@ POST _bulk
 POST {index}/_bulk
 ```
 
-Specifying the index in the path means you don't need to include it in the [request body](#request-body).
+Specifying the index in the path means you don't need to include it in the [request body]({{site.url}}{{site.baseurl}}/opensearch/rest-api/document-apis/bulk/#request-body).
 
 OpenSearch also accepts PUT requests to the `_bulk` path, but we highly recommend using POST. The accepted usage of PUT---adding or replacing a single resource at a given path---doesn't make sense for bulk requests.
 {: .note }

_opensearch/rest-api/document-apis/get-documents.md

@@ -0,0 +1,77 @@
+---
+layout: default
+title: Get document
+parent: Document APIs
+grand_parent: REST API reference
+nav_order: 5
+---
+
+# Get document
+
+After adding a JSON document to your index, you can use the get document API operation to retrieve the document's information and data.
+
+## Example
+
+```json
+GET sample-index1/_doc/1
+```
+
+## Path and HTTP methods
+
+```
+GET <index>/_doc/<_id>
+HEAD <index>/_doc/<_id>
+```
+```
+GET <index>/_source/<_id>
+HEAD <index>/_source/<_id>
+```
+
+## URL parameters
+
+All get document URL parameters are optional.
+
+Parameter | Type | Description
+:--- | :--- | :---
+preference | string | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes get document operations on random shards.
+realtime | boolean | Specifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is true.
+refresh | boolean | If true, OpenSearch refreshes shards to make the operation visible to searching. Default is false.
+routing | string | A value used to route the operation to a specific shard.
+stored_fields | boolean | If true, the operation retrieves document fields stored in the index rather than the document's `_source`. Default is false.
+_source | string | Whether to include the `_source` field in the response body. Default is true.
+_source_excludes | string | A comma-separated list of source fields to exclude in the query response.
+_source_includes | string | A comma-separated list of source fields to include in the query response.
+version | integer | The version of the document to return, which must match the current version of the document.
+version_type | enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current verison). For example, to retrieve version 3 of a document, use `/_doc/1?version=3&version_type=external`.
+
+
+## Response
+```json
+{
+  "_index": "sample-index1",
+  "_type": "_doc",
+  "_id": "1",
+  "_version": 1,
+  "_seq_no": 0,
+  "_primary_term": 9,
+  "found": true,
+  "_source": {
+    "text": "This is just some sample text."
+  }
+}
+```
+
+## Response body fields
+
+Field | Description
+:--- | :---
+_index | The name of the index.
+_type | The document's type. OpenSearch only supports one type, which is `_doc`.
+_id | The document's id.
+_version | The document's version number. Updated whenever the document changes.
+_seq_no | The sequnce number assigned when the document is indexed.
+primary_term | The primary term assigned when the document is indexed.
+found | Whether the document exists.
+_routing | The shard that the document is routed to. If the document is not routed to a particular shard, this field is omitted.
+_source | Contains the document's data if `found` is true. If `_source` is set to false or `stored_fields` is set to true in the URL parameters, this field is omitted.
+_fields | Contains the document's data that's stored in the index. Only returned if both `stored_fields` and `found` are true.

_opensearch/rest-api/document-apis/index.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Document APIs
+parent: REST API reference
+has_children: true
+nav_order: 7
+---
+
+# Document APIs
+
+The document APIs allow you to handle documents relative to your index, such as adding, updating, and deleting documents.
+
+Document APIs are separated into two categories: single document operations and multi-document operations. Multi-document operations offer performance advantages over submitting many individual requests, so whenever practical, we recommend that you use multi-document operations.
+
+## Single document operations
+
+- Index
+- Get
+- Delete
+- Update
+
+## Multi-document operations
+
+- Bulk
+- Multi get
+- Delete by query
+- Update by query
+- Reindex