Add higher-level HTTP DSL methods

CHANGELOG.md

@@ -10,6 +10,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added support for point-in-time search and associated APIs ([#405](https://github.com/opensearch-project/opensearch-net/pull/405))
 - Added support for the component template APIs ([#411](https://github.com/opensearch-project/opensearch-net/pull/411))
 - Added support for the composable index template APIs ([#437](https://github.com/opensearch-project/opensearch-net/pull/437))
+- Added high-level DSL for raw HTTP methods ([#447](https://github.com/opensearch-project/opensearch-net/pull/447))
 
 ### Removed
 - Removed the `Features` API which is not supported by OpenSearch from the low-level client ([#331](https://github.com/opensearch-project/opensearch-net/pull/331))

USER_GUIDE.md

@@ -309,4 +309,8 @@ Note the main difference here is that we are instantiating an `OpenSearchLowLeve
 
 ## Advanced Features
 
-- [Making Raw JSON Requests](guides/json.md)
+- [Bulk Requests](guides/bulk.md)
+- [Document Lifecycle](guides/document-lifecycle.md)
+- [Index Template](guides/index-template.md)
+- [Making Raw JSON REST Requests](guides/json.md)
+- [Search](guides/search.md)

guides/document_lifecycle.md → guides/document-lifecycle.md

@@ -1,5 +1,5 @@
 # Document Lifecycle
-This guide covers OpenSearch Ruby Client API actions for Document Lifecycle. You'll learn how to create, read, update, and delete documents in your OpenSearch cluster. Whether you're new to OpenSearch or an experienced user, this guide provides the information you need to manage your document lifecycle effectively.
+This guide covers OpenSearch .NET Client API actions for Document Lifecycle. You'll learn how to create, read, update, and delete documents in your OpenSearch cluster. Whether you're new to OpenSearch or an experienced user, this guide provides the information you need to manage your document lifecycle effectively.
 
 ## Setup
 Assuming you have OpenSearch running locally on port 9200, you can create a client instance with the following code:
@@ -238,4 +238,4 @@ To clean up the resources created in this guide, delete the `movies` index:
 ```csharp
 var deleteIndexResponse = client.Indices.Delete("movies");
 Debug.Assert(deleteIndexResponse.IsValid, deleteIndexResponse.DebugInformation);
-```
+```

guides/json.md

@@ -4,33 +4,53 @@
     - [PUT](#put)
     - [POST](#post)
     - [DELETE](#delete)
-  - [Using Different Types Of PostData](#using-different-types-of-postdata)
-    - [PostData.String](#postdatastring)
-    - [PostData.Bytes](#postdatabytes)
-    - [PostData.Serializable](#postdataserializable)
-    - [PostData.MultiJson](#postdatamultijson)
+  - [Request Bodies](#request-bodies)
+    - [String](#string)
+    - [Bytes](#bytes)
+    - [Serializable](#serializable)
+    - [Multi Json](#multi-json)
+  - [Response Bodies](#response-bodies)
 
 # Making Raw JSON REST Requests
-The OpenSearch client implements many high-level REST DSLs that invoke OpenSearch APIs. However you may find yourself in a situation that requires you to invoke an API that is not supported by the client. You can use `client.LowLevel.DoRequest` to do so. See [samples/Samples/RawJson/RawJsonSample.cs](../samples/Samples/RawJson/RawJsonSample.cs) for a complete working sample.
+The OpenSearch client implements many high-level REST DSLs that invoke OpenSearch APIs. However you may find yourself in a situation that requires you to invoke an API that is not supported by the client. You can use the methods defined within `client.Http` or `client.LowLevel.Http` to do so. See [samples/Samples/RawJson/RawJsonHighLevelSample.cs](../samples/Samples/RawJson/RawJsonHighLevelSample.cs) and [samples/Samples/RawJson/RawJsonLowLevelSample.cs](../samples/Samples/RawJson/RawJsonLowLevelSample.cs) for complete working samples. 
+
+Older versions of the client that do not support the `client.Http` namespace can use the `client.LowLevel.DoRequest` method instead.
 
 ## HTTP Methods
 
 ### GET
 The following example returns the server version information via `GET /`.
 
 ```csharp
-var info = await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.GET, "/", CancellationToken.None);
+var info = await client.Http.GetAsync<DynamicResponse>("/");
+// OR
+var info = await client.LowLevel.Http.GetAsync<DynamicResponse>("/");
+
 Console.WriteLine($"Welcome to {info.Body.version.distribution} {info.Body.version.number}!");
 ```
 
+### HEAD
+The following example checks if an index exists via `HEAD /movies`.
+
+```csharp
+var indexExists = await client.Http.HeadAsync<VoidResponse>("/movies");
+// OR
+var indexExists = await client.LowLevel.Http.HeadAsync<VoidResponse>("/movies");
+
+Console.WriteLine($"Index Exists: {indexExists.HttpStatusCode == 200}");
+```
+
 ### PUT
 The following example creates an index.
 
 ```csharp
 var indexBody = new { settings = new { index = new { number_of_shards = 4 } } };
 
-var createIndex = await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.Serializable(indexBody));
-Debug.Assert(createIndex.Success && (bool)createIndex.Body.acknowledged, createIndex.DebugInformation);
+var createIndex = await client.Http.PutAsync<DynamicResponse>("/movies", d => d.SerializableBody(indexBody));
+// OR
+var createIndex = await client.LowLevel.Http.PutAsync<DynamicResponse>("/movies", PostData.Serializable(indexBody));
+
+Console.WriteLine($"Create Index: {createIndex.Success && (bool)createIndex.Body.acknowledged}");
 ```
 
 ### POST
@@ -45,25 +65,30 @@ var query = new
 	query = new { multi_match = new { query = q, fields = new[] { "title^2", "director" } } }
 };
 
-var search = await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.POST, $"/{indexName}/_search", CancellationToken.None, PostData.Serializable(query));
-Debug.Assert(search.Success, search.DebugInformation);
+var search = await client.Http.PostAsync<DynamicResponse>("/movies/_search", d => d.SerializableBody(query));
+// OR
+var search = await client.LowLevel.Http.PostAsync<DynamicResponse>("/movies/_search", PostData.Serializable(query));
 
-foreach (var hit in search.Body.hits.hits) Console.WriteLine(hit["_source"]["title"]);
+foreach (var hit in search.Body.hits.hits) Console.WriteLine($"Search Hit: {hit["_source"]["title"]}");
 ```
 
 ### DELETE
 The following example deletes an index.
 
 ```csharp
-var deleteDocument = await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.DELETE, $"/{indexName}/_doc/{id}", CancellationToken.None);
-Debug.Assert(deleteDocument.Success, deleteDocument.DebugInformation);
+var deleteIndex = await client.Http.DeleteAsync<DynamicResponse>("/movies");
+// OR
+var deleteIndex = await client.LowLevel.Http.DeleteAsync<DynamicResponse>("/movies");
+
+Console.WriteLine($"Delete Index: {deleteIndex.Success && (bool)deleteIndex.Body.acknowledged}");
 ```
 
-## Using Different Types Of PostData
-The OpenSearch .NET client provides a `PostData` class that is used to provide the request body for a request. The `PostData` class has several static methods that can be used to create a `PostData` object from different types of data.
+## Request Bodies
+For the methods that take a request body (PUT/POST/PATCH) it is possible use several different types to specify the body. The high-level methods provided in `OpenSearch.Client` provide overloaded fluent-methods for setting the body. While the lower level methods in `OpenSearch.Net` accept instances of `PostData`.  
+The `PostData` class has several static methods that can be used to create a `PostData` object from different types of data.
 
-### PostData.String
-The following example shows how to use the `PostData.String` method to create a `PostData` object from a string.
+### String
+The following example shows how to pass a string as a request body:
 
 ```csharp
 string indexBody = @"
@@ -75,11 +100,13 @@ string indexBody = @"
     }
 }}";
 
-await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.String(indexBody));
+await client.Http.PutAsync<DynamicResponse>("/movies", d => d.Body(indexBody));
+// OR
+await client.LowLevel.Http.PutAsync<DynamicResponse>("/movies", PostData.String(indexBody));
 ```
 
-### PostData.Bytes
-The following example shows how to use the `PostData.Bytes` method to create a `PostData` object from a byte array.
+### Bytes
+The following example shows how to pass a byte array as a request body:
 
 ```csharp
 byte[] indexBody = Encoding.UTF8.GetBytes(@"
@@ -91,11 +118,13 @@ byte[] indexBody = Encoding.UTF8.GetBytes(@"
     }
 }}");
 
-await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.Bytes(indexBody));
+await client.Http.PutAsync<DynamicResponse>("/movies", d => d.Body(indexBody));
+// OR
+await client.LowLevel.Http.PutAsync<DynamicResponse>("/movies", PostData.Bytes(indexBody));
 ```
 
-### PostData.Serializable
-The following example shows how to use the `PostData.Serializable` method to create a `PostData` object from a serializable object.
+### Serializable
+The following example shows how to pass an object that will be serialized to JSON as a request body:
 
 ```csharp
 var indexBody = new
@@ -109,12 +138,14 @@ var indexBody = new
     }
 };
 
-await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.PUT, "/movies", CancellationToken.None, PostData.Serializable(indexBody));
+await client.Http.PutAsync<DynamicResponse>("/movies", d => d.SerializableBody(indexBody));
+// OR
+await client.LowLevel.Http.PutAsync<DynamicResponse>("/movies", PostData.Serializable(indexBody));
 ```
 
-### PostData.MultiJson
-The following example shows how to use the `PostData.MultiJson` method to create a `PostData` object from a collection of serializable objects. 
-The `PostData.MultiJson` method is useful when you want to send multiple documents in a bulk request.
+### Multi JSON
+The following example shows how to pass a collection of objects (or strings) that will be serialized to JSON and then newline-delimited as a request body.
+This formatting is primarily used when you want to make a bulk request.
 
 ```csharp
 var bulkBody = new object[]
@@ -125,5 +156,15 @@ var bulkBody = new object[]
     new { title = "The Godfather: Part II", director = "Francis Ford Coppola", year = 1974 }
 };
 
-await client.LowLevel.DoRequestAsync<DynamicResponse>(HttpMethod.POST, "/_bulk", CancellationToken.None, PostData.MultiJson(bulkBody));
+await client.Http.PostAsync<DynamicResponse>("/_bulk", d => d.MultiJsonBody(indexBody));
+// OR
+await client.LowLevel.Http.PostAsync<DynamicResponse>("/_bulk", PostData.MultiJson(indexBody));
 ```
+
+## Response Bodies
+There are a handful of response type implementations that can be used to retrieve the response body. These are specified as the generic argument to the request methods. The content of the body will then be available via the `Body` property of the response object. The following response types are available:
+
+- `VoidResponse`: The response body will not be read. Useful when you only care about the response status code, such as a `HEAD` request to check an index exists.
+- `StringResponse`: The response body will be read into a string.
+- `BytesResponse`: The response body will be read into a byte array.
+- `DynamicResponse`: The response body will be deserialized as JSON into a dynamic object.

samples/Samples/RawJson/RawJsonHighLevelSample.cs

@@ -0,0 +1,76 @@
+/* SPDX-License-Identifier: Apache-2.0
+*
+* The OpenSearch Contributors require contributions made to
+* this file be licensed under the Apache-2.0 license or a
+* compatible open source license.
+*/
+
+using System.Diagnostics;
+using OpenSearch.Client;
+using OpenSearch.Net;
+
+namespace Samples.RawJson;
+
+public class RawJsonHighLevelSample : Sample
+{
+	public RawJsonHighLevelSample() : base("raw-json-high-level", "A sample demonstrating how to use the high-level client to perform raw JSON requests") { }
+
+    protected override async Task Run(IOpenSearchClient client)
+    {
+        var info = await client.Http.GetAsync<DynamicResponse>("/");
+		Debug.Assert(info.Success, info.DebugInformation);
+        Console.WriteLine($"Welcome to {info.Body.version.distribution} {info.Body.version.number}!");
+
+		const string indexName = "movies";
+
+		// Check if the index already exists
+
+		var indexExists = await client.Http.HeadAsync<DynamicResponse>($"/{indexName}");
+		Debug.Assert(indexExists.HttpStatusCode == 404, indexExists.DebugInformation);
+		Console.WriteLine($"Index Exists: {indexExists.HttpStatusCode == 200}");
+
+		// Create an index
+
+		var indexBody = new { settings = new { index = new { number_of_shards = 4 } } };
+
+        var createIndex = await client.Http.PutAsync<DynamicResponse>($"/{indexName}", d => d.SerializableBody(indexBody));
+		Debug.Assert(createIndex.Success && (bool)createIndex.Body.acknowledged, createIndex.DebugInformation);
+		Console.WriteLine($"Create Index: {createIndex.Success && (bool)createIndex.Body.acknowledged}");
+
+		// Add a document to the index
+		var document = new { title = "Moneyball", director = "Bennett Miller", year = 2011 };
+
+		const string id = "1";
+
+		var addDocument = await client.Http.PutAsync<DynamicResponse>(
+			$"/{indexName}/_doc/{id}",
+			d => d
+				.SerializableBody(document)
+				.QueryString(qs => qs.Add("refresh", true)));
+		Debug.Assert(addDocument.Success, addDocument.DebugInformation);
+
+        // Search for a document
+        const string q = "miller";
+
+		var query = new
+		{
+			size = 5,
+			query = new { multi_match = new { query = q, fields = new[] { "title^2", "director" } } }
+		};
+
+        var search = await client.Http.PostAsync<DynamicResponse>($"/{indexName}/_search", d => d.SerializableBody(query));
+		Debug.Assert(search.Success, search.DebugInformation);
+
+		foreach (var hit in search.Body.hits.hits) Console.WriteLine($"Search Hit: {hit["_source"]["title"]}");
+
+		// Delete the document
+		var deleteDocument = await client.Http.DeleteAsync<DynamicResponse>($"/{indexName}/_doc/{id}");
+		Debug.Assert(deleteDocument.Success, deleteDocument.DebugInformation);
+		Console.WriteLine($"Delete Document: {deleteDocument.Success}");
+
+		// Delete the index
+        var deleteIndex = await client.Http.DeleteAsync<DynamicResponse>($"/{indexName}");
+		Debug.Assert(deleteIndex.Success && (bool)deleteIndex.Body.acknowledged, deleteIndex.DebugInformation);
+		Console.WriteLine($"Delete Index: {deleteIndex.Success && (bool)deleteIndex.Body.acknowledged}");
+    }
+}

samples/Samples/RawJson/RawJsonLowLevelSample.cs

@@ -0,0 +1,76 @@
+/* SPDX-License-Identifier: Apache-2.0
+*
+* The OpenSearch Contributors require contributions made to
+* this file be licensed under the Apache-2.0 license or a
+* compatible open source license.
+*/
+
+using System.Diagnostics;
+using OpenSearch.Client;
+using OpenSearch.Net;
+using OpenSearch.Net.Specification.HttpApi;
+
+namespace Samples.RawJson;
+
+public class RawJsonLowLevelSample : Sample
+{
+	public RawJsonLowLevelSample() : base("raw-json-low-level", "A sample demonstrating how to use the low-level client to perform raw JSON requests") { }
+
+    protected override async Task Run(IOpenSearchClient client)
+    {
+        var info = await client.LowLevel.Http.GetAsync<DynamicResponse>("/");
+		Debug.Assert(info.Success, info.DebugInformation);
+        Console.WriteLine($"Welcome to {info.Body.version.distribution} {info.Body.version.number}!");
+
+		const string indexName = "movies";
+
+		// Check if the index already exists
+
+		var indexExists = await client.LowLevel.Http.HeadAsync<DynamicResponse>($"/{indexName}");
+		Debug.Assert(indexExists.HttpStatusCode == 404, indexExists.DebugInformation);
+		Console.WriteLine($"Index Exists: {indexExists.HttpStatusCode == 200}");
+
+		// Create an index
+
+		var indexBody = new { settings = new { index = new { number_of_shards = 4 } } };
+
+        var createIndex = await client.LowLevel.Http.PutAsync<DynamicResponse>($"/{indexName}", PostData.Serializable(indexBody));
+		Debug.Assert(createIndex.Success && (bool)createIndex.Body.acknowledged, createIndex.DebugInformation);
+		Console.WriteLine($"Create Index: {createIndex.Success && (bool)createIndex.Body.acknowledged}");
+
+		// Add a document to the index
+		var document = new { title = "Moneyball", director = "Bennett Miller", year = 2011};
+
+		const string id = "1";
+
+		var addDocument = await client.LowLevel.Http.PutAsync<DynamicResponse>(
+			$"/{indexName}/_doc/{id}",
+			PostData.Serializable(document),
+			new HttpPutRequestParameters{ QueryString = {{"refresh", true}} });
+		Debug.Assert(addDocument.Success, addDocument.DebugInformation);
+
+        // Search for a document
+        const string q = "miller";
+
+		var query = new
+		{
+			size = 5,
+			query = new { multi_match = new { query = q, fields = new[] { "title^2", "director" } } }
+		};
+
+        var search = await client.LowLevel.Http.PostAsync<DynamicResponse>($"/{indexName}/_search", PostData.Serializable(query));
+		Debug.Assert(search.Success, search.DebugInformation);
+
+		foreach (var hit in search.Body.hits.hits) Console.WriteLine($"Search Hit: {hit["_source"]["title"]}");
+
+		// Delete the document
+		var deleteDocument = await client.LowLevel.Http.DeleteAsync<DynamicResponse>($"/{indexName}/_doc/{id}");
+		Debug.Assert(deleteDocument.Success, deleteDocument.DebugInformation);
+		Console.WriteLine($"Delete Document: {deleteDocument.Success}");
+
+		// Delete the index
+        var deleteIndex = await client.LowLevel.Http.DeleteAsync<DynamicResponse>($"/{indexName}");
+		Debug.Assert(deleteIndex.Success && (bool)deleteIndex.Body.acknowledged, deleteIndex.DebugInformation);
+		Console.WriteLine($"Delete Index: {deleteIndex.Success && (bool)deleteIndex.Body.acknowledged}");
+    }
+}