From eaffb81066190dd54f38540435a4ffb0cc70a2f5 Mon Sep 17 00:00:00 2001
From: Florian Bernd <florian.bernd@elastic.co>
Date: Thu, 21 Nov 2024 11:07:11 +0100
Subject: [PATCH] Update documentation

---
 docs/migration-guide.asciidoc | 46 ++++++++++++++++++++++++++++------
 docs/usage/index.asciidoc     |  9 ++++---
 docs/usage/transport.asciidoc | 47 +++++++++++++++++++++++++++++++++++
 3 files changed, 90 insertions(+), 12 deletions(-)
 create mode 100644 docs/usage/transport.asciidoc

diff --git a/docs/migration-guide.asciidoc b/docs/migration-guide.asciidoc
index 21f78589c19..1d3ae76032c 100644
--- a/docs/migration-guide.asciidoc
+++ b/docs/migration-guide.asciidoc
@@ -292,13 +292,43 @@ As a last resort, the low-level client `Elastic.Transport` can be used to create
 
 [source,csharp]
 ----
+public class MyRequestParameters : RequestParameters
+{
+    public bool Pretty
+    {
+        get => Q<bool>("pretty");
+        init => Q("pretty", value);
+    }
+}
+
+// ...
+
 var body = """
-	{
-	  "name": "my-api-key",
-	  "expiration": "1d",   
-	  "...": "..."
-	}
-	""";
-
-var response = await client.Transport.RequestAsync<StringResponse>(HttpMethod.POST, "/_security/api_key", PostData.String(body));
+           {
+             "name": "my-api-key",
+             "expiration": "1d",   
+             "...": "..."
+           }
+           """;
+
+MyRequestParameters requestParameters = new()
+{
+    Pretty = true
+};
+
+var pathAndQuery = requestParameters.CreatePathWithQueryStrings("/_security/api_key",
+    client.ElasticsearchClientSettings);
+var endpointPath = new EndpointPath(Elastic.Transport.HttpMethod.POST, pathAndQuery);
+
+// Or, if the path does not contain query parameters: 
+// new EndpointPath(Elastic.Transport.HttpMethod.POST, "my_path")
+
+var response = await client.Transport
+    .RequestAsync<StringResponse>(
+        endpointPath,
+        PostData.String(body),
+        null,
+        null,
+        cancellationToken: default)
+    .ConfigureAwait(false);
 ----
\ No newline at end of file
diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc
index c6ae095064a..87edb3f8d3b 100644
--- a/docs/usage/index.asciidoc
+++ b/docs/usage/index.asciidoc
@@ -14,9 +14,10 @@ If you're new to {es}, make sure also to read {ref}/getting-started.html[Elastic
 
 NOTE: This is still a work in progress, more sections will be added in the near future.
 
-include::recommendations.asciidoc[]
+include::aggregations.asciidoc[]
+include::esql.asciidoc[]
 include::examples.asciidoc[]
-include::query.asciidoc[]
 include::mappings.asciidoc[]
-include::aggregations.asciidoc[]
-include::esql.asciidoc[]
\ No newline at end of file
+include::query.asciidoc[]
+include::recommendations.asciidoc[]
+include::transport.asciidoc[]
diff --git a/docs/usage/transport.asciidoc b/docs/usage/transport.asciidoc
new file mode 100644
index 00000000000..3e15fbd0b90
--- /dev/null
+++ b/docs/usage/transport.asciidoc
@@ -0,0 +1,47 @@
+[[transport]]
+== Transport example
+
+This page demonstrates how to use the low level transport to send requests.
+
+[source,csharp]
+----
+public class MyRequestParameters : RequestParameters
+{
+    public bool Pretty
+    {
+        get => Q<bool>("pretty");
+        init => Q("pretty", value);
+    }
+}
+
+// ...
+
+var body = """
+           {
+             "name": "my-api-key",
+             "expiration": "1d",   
+             "...": "..."
+           }
+           """;
+
+MyRequestParameters requestParameters = new()
+{
+    Pretty = true
+};
+
+var pathAndQuery = requestParameters.CreatePathWithQueryStrings("/_security/api_key",
+    client.ElasticsearchClientSettings);
+var endpointPath = new EndpointPath(Elastic.Transport.HttpMethod.POST, pathAndQuery);
+
+// Or, if the path does not contain query parameters: 
+// new EndpointPath(Elastic.Transport.HttpMethod.POST, "my_path")
+
+var response = await client.Transport
+    .RequestAsync<StringResponse>(
+        endpointPath,
+        PostData.String(body),
+        null,
+        null,
+        cancellationToken: default)
+    .ConfigureAwait(false);
+----