Skip to content

Commit

Permalink
Add higher-level HTTP DSL methods (opensearch-project#447)
Browse files Browse the repository at this point in the history
* Lay foundations

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Implement generation

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Run generator

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Update samples

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Update guide

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Add changelog entry

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* PR comments

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Fix naming tests

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Why is the ordering of these statements load-bearing???

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

---------

Signed-off-by: Thomas Farr <tsfarr@amazon.com>
  • Loading branch information
Xtansia committed Nov 30, 2023
1 parent 85451de commit 9054705
Show file tree
Hide file tree
Showing 50 changed files with 1,669 additions and 318 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
6 changes: 5 additions & 1 deletion USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
4 changes: 2 additions & 2 deletions guides/document_lifecycle.md → guides/document-lifecycle.md
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -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);
```
```
81 changes: 52 additions & 29 deletions guides/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,47 @@
- [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` 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>("/");

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");

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));

Console.WriteLine($"Create Index: {createIndex.Success && (bool)createIndex.Body.acknowledged}");
```

### POST
Expand All @@ -45,25 +59,26 @@ 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));

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");

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 = @"
Expand All @@ -75,11 +90,11 @@ 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));
```

### 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(@"
Expand All @@ -91,11 +106,11 @@ 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));
```

### 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
Expand All @@ -109,12 +124,12 @@ 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));
```

### 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[]
Expand All @@ -125,5 +140,13 @@ 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));
```

## 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.
76 changes: 76 additions & 0 deletions samples/Samples/RawJson/RawJsonHighLevelSample.cs
Original file line number Diff line number Diff line change
@@ -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}");
}
}
76 changes: 76 additions & 0 deletions samples/Samples/RawJson/RawJsonLowLevelSample.cs
Original file line number Diff line number Diff line change
@@ -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}");
}
}
Loading

0 comments on commit 9054705

Please sign in to comment.