diff --git a/guides/using-json-rest-requests.md b/guides/using-json-rest-requests.md new file mode 100644 index 0000000000..0eceee34f8 --- /dev/null +++ b/guides/using-json-rest-requests.md @@ -0,0 +1,135 @@ +# Using Raw JSON REST Requests +OpenSearch exposes a REST API that you can use to interact with OpenSearch. The OpenSearch .NET client provides a low-level API that allows you to send raw JSON requests to OpenSearch. This API is useful if you want to use a feature that is not yet supported by the OpenSearch .NET client, but it supported by the OpenSearch REST API. + +## Setup +Let's start by creating an index and adding some documents to it: + +```csharp +using OpenSearch.Client; +using OpenSearch.Net; + +var node = new Uri("https://localhost:9200"); +var config = new ConnectionSettings(node) + .ThrowExceptions() + .ServerCertificateValidationCallback(CertificateValidations.AllowAll) + .BasicAuthentication("admin", "admin"); +var client = new OpenSearchClient(config); + +class Movie +{ + public string Title { get; set; } + public string Director { get; set; } + public int Year { get; set; } + public override string ToString() + { + return $"{nameof(Title)}: {Title}, {nameof(Director)}: {Director}, {nameof(Year)}: {Year}"; + } +} + +private class CreatePitParams : RequestParameters +{ + public override HttpMethod DefaultHttpMethod => HttpMethod.POST; + public override bool SupportsBody => false; + + public string KeepAlive + { + get => Q("keep_alive"); + set => Q("keep_alive", value); + } +} + +var index = "movies"; + +await client.IndexManyAsync( + Enumerable.Range(0, 5) + .Select(i => new Movie + { + Title = $"The Dark Knight {i}", + Director = "Christopher Nolan", + Year = 2008 + i + }) + .Concat(new[] + { + new Movie + { + Title = "The Godfather", + Director = "Francis Ford Coppola", + Year = 1972 + }, + new Movie + { + Title = "The Shawshank Redemption", + Director = "Frank Darabont", + Year = 1994 + } + }), index); + +await client.Indices.RefreshAsync(index); +Console.WriteLine($"Indexed {await client.CountAsync(index)} movies"); // Indexed 7 movies +``` + +## Executing Raw JSON REST Requests +The OpenSearch .NET 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 currently implemented in the client. In this case, you can use the low-level API to send raw JSON requests to OpenSearch. + + +## GET A Document +The following example returns a document via `GET /movies/_search` with a request body that specifies a query to match documents with a title of `The Dark Knight 1`. + +```csharp +var getResponse = await client.LowLevel.DoRequestAsync(HttpMethod.GET, "/movies/_search", new CancellationToken(), PostData.Serializable( + new + { + query = new + { + match = new + { + title = "The Dark Knight 1" + } + } + })); +Console.WriteLine(getResponse.Body["hits"]["hits"][0]["_source"]["title"].ToString()); // The Dark Knight 1 +``` + +## POST A Document +The following example creates a document via `POST /movies/_doc` with a request body that specifies the document to create. + +```csharp +var postResponse = await client.LowLevel.DoRequestAsync(HttpMethod.POST, "/movies/_doc", new CancellationToken(), PostData.Serializable( + new + { + title = "The Dark Knight 6", + director = "Christopher Nolan", + year = 2012 + })); +Console.WriteLine(postResponse.Body["result"].ToString()); // created +``` + +# PUT A Document +The following example creates a document via `PUT /movies/_doc/{id}` with a request body that specifies the document to create. + +```csharp +var putResponse = await client.LowLevel.DoRequestAsync(HttpMethod.PUT, "/movies/_doc/6", new CancellationToken(), PostData.Serializable( + new + { + title = "The Dark Knight 6", + director = "Christopher Nolan", + year = 2023 + })); +Console.WriteLine(putResponse.Body["result"].ToString()); // created +``` + +# DELETE A Document +The following example deletes a document via `DELETE /movies/_doc/{id}`. + +```csharp +var deleteResponse = await client.LowLevel.DoRequestAsync(HttpMethod.DELETE, "/movies/_doc/6", new CancellationToken()); +Console.WriteLine(deleteResponse.Body["result"].ToString()); // deleted +``` + + +## Cleanup +Let's delete all resources created in this guide: + +```csharp +await client.Indices.DeleteAsync(index); +``` \ No newline at end of file