docs: Clarify how to use a client with InfluxDB 1.8 (#77)

Author: bednar

CHANGELOG.md

@@ -3,9 +3,12 @@
 ### Features
 1. [#70](https://github.com/influxdata/influxdb-client-csharp/pull/70): Optimized mapping of measurements into `PointData`
 
-### Bugs
+### Bug Fixes
 1. [#69](https://github.com/influxdata/influxdb-client-csharp/pull/69): Write buffer uses correct flush interval and batch size under heavy load
 
+### Documentation
+1. [#77](https://github.com/influxdata/influxdb-client-csharp/pull/77): Clarify how to use a client with InfluxDB 1.8
+
 ### Dependencies
 1. [#74](https://github.com/influxdata/influxdb-client-csharp/pull/74): update CsvHelper to [15.0.4,16.0)
 
@@ -15,7 +18,7 @@
 1. [#61](https://github.com/influxdata/influxdb-client-csharp/issues/61): Set User-Agent to influxdb-client-csharp/VERSION for all requests
 1. [#64](https://github.com/influxdata/influxdb-client-csharp/issues/64): Add authentication with Username and Password for Client.Legacy
 
-### Bugs
+### Bug Fixes
 1. [#63](https://github.com/influxdata/influxdb-client-csharp/pull/63): Correctly parse CSV where multiple results include multiple tables
 
 ## 1.5.0 [2020-02-14]
@@ -35,7 +38,7 @@
 ### CI
 1. [#54](https://github.com/influxdata/influxdb-client-csharp/pull/54): Added beta release to continuous integration
 
-### Bugs
+### Bug Fixes
 1. [#56](https://github.com/influxdata/influxdb-client-csharp/issues/56): WriteApi is disposed after a buffer is fully processed
 
 ## 1.3.0 [2019-12-06]
@@ -47,7 +50,7 @@
 ### API
 1. [#46](https://github.com/influxdata/influxdb-client-csharp/pull/46): Updated swagger to latest version
 
-### Bugs
+### Bug Fixes
 1. [#45](https://github.com/influxdata/influxdb-client-csharp/issues/45): Assemblies are strong-named
 2. [#48](https://github.com/influxdata/influxdb-client-csharp/pull/48): Packing library icon into a package
 
@@ -71,7 +74,7 @@
 ### API
 1. [#36](https://github.com/influxdata/influxdb-client-csharp/issues/36): Updated swagger to latest version
 
-### Bugs
+### Bug Fixes
 1. [#31](https://github.com/influxdata/influxdb-client-csharp/issues/31): Drop NaN and infinity values from fields when writing to InfluxDB
 1. [#39](https://github.com/influxdata/influxdb-client-csharp/pull/39): FluxCSVParser uses a CultureInfo for parsing string to double
 
@@ -80,7 +83,7 @@
 ### Features
 1. [#29](https://github.com/influxdata/influxdb-client-csharp/issues/29): Added support for gzip compression of query response and write body 
 
-### Bugs
+### Bug Fixes
 1. [#27](https://github.com/influxdata/influxdb-client-csharp/issues/27): The org parameter takes either the ID or Name interchangeably
 
 ### API
@@ -92,7 +95,7 @@
 1. [#18](https://github.com/influxdata/influxdb-client-csharp/issues/18): Auto-configure client from configuration file
 1. [#20](https://github.com/influxdata/influxdb-client-csharp/issues/19): Possibility to specify default tags
 
-### Bugs
+### Bug Fixes
 1. [#24](https://github.com/influxdata/influxdb-client-csharp/issues/24): The data point without field should be ignored
 
 ## 1.0.0.M1

Client.Test/InfluxDbClientFactoryTest.cs

@@ -144,6 +144,26 @@ public void LoadFromConfiguration()
             Assert.AreEqual("California Miner", defaultTags["customer"]);
             Assert.AreEqual("${SensorVersion}", defaultTags["version"]);
         }
+        
+        [Test]
+        public void V1Configuration()
+        {
+            var client = InfluxDBClientFactory.CreateV1("http://localhost:8086", "my-username", "my-password".ToCharArray(), "database", "week");
+
+            var options = GetDeclaredField<InfluxDBClientOptions>(client.GetType(), client, "_options");
+            Assert.AreEqual("http://localhost:8086", options.Url);
+            Assert.AreEqual("-", options.Org);
+            Assert.AreEqual("database/week", options.Bucket);
+            Assert.AreEqual("my-username:my-password".ToCharArray(), options.Token);
+            
+            client = InfluxDBClientFactory.CreateV1("http://localhost:8086", null, null, "database", null);
+
+            options = GetDeclaredField<InfluxDBClientOptions>(client.GetType(), client, "_options");
+            Assert.AreEqual("http://localhost:8086", options.Url);
+            Assert.AreEqual("-", options.Org);
+            Assert.AreEqual("database/", options.Bucket);
+            Assert.AreEqual(":".ToCharArray(), options.Token);
+        }
 
         private static T GetDeclaredField<T>(IReflect type, object instance, string fieldName)
         {

Client/InfluxDBClientFactory.cs

@@ -19,7 +19,7 @@ public static InfluxDBClient Create()
 
             return Create(options);
         }
-        
+
         /// <summary>
         /// Create a instance of the InfluxDB 2.0 client. The url could be a connection string with various configurations.
         /// <para>
@@ -73,6 +73,31 @@ public static InfluxDBClient Create(string url, char[] token)
             return Create(options);
         }
 
+        /// <summary>
+        /// Create a instance of the InfluxDB 2.0 client to connect into InfluxDB 1.8.
+        /// </summary>
+        /// <param name="url">the url to connect to the InfluxDB 1.8</param>
+        /// <param name="username">authorization username</param>
+        /// <param name="password">authorization password</param>
+        /// <param name="database">database name</param>
+        /// <param name="retentionPolicy">retention policy</param>
+        /// <returns>client</returns>
+        public static InfluxDBClient CreateV1(string url, string username, char[] password, string database,
+            string retentionPolicy)
+        {
+            Arguments.CheckNonEmptyString(database, nameof(database));
+
+            var options = InfluxDBClientOptions.Builder
+                .CreateNew()
+                .Url(url)
+                .Org("-")
+                .AuthenticateToken($"{username}:{new string(password)}".ToCharArray())
+                .Bucket($"{database}/{retentionPolicy}")
+                .Build();
+
+            return Create(options);
+        }
+
         /// <summary>
         /// Create a instance of the InfluxDB 2.0 client.
         /// </summary>
@@ -94,7 +119,8 @@ public static InfluxDBClient Create(InfluxDBClientOptions options)
         /// <param name="org">the name of an organization</param>
         /// <param name="bucket">the name of a bucket</param>
         /// <returns>Created default user, bucket, org.</returns>
-        public static async Task<OnboardingResponse> Onboarding(string url, string username, string password, string org,
+        public static async Task<OnboardingResponse> Onboarding(string url, string username, string password,
+            string org,
             string bucket)
         {
             Arguments.CheckNonEmptyString(url, nameof(url));

Examples/InfluxDB18Example.cs

@@ -0,0 +1,46 @@
+using System;
+using System.Threading.Tasks;
+using InfluxDB.Client;
+using InfluxDB.Client.Writes;
+
+namespace Examples
+{
+    public class InfluxDB18Example
+    {
+        // change name of method to Main
+        public static async Task MainDisabled(string[] args)
+        {
+            const string database = "telegraf";
+            const string retentionPolicy = "autogen";
+            
+            var client = InfluxDBClientFactory.CreateV1("http://localhost:8086",
+                "username",
+                "password".ToCharArray(),
+                database,
+                retentionPolicy);
+
+            Console.WriteLine("*** Write Points ***");
+
+            using (var writeApi = client.GetWriteApi())
+            {
+                var point = PointData.Measurement("mem")
+                    .Tag("host", "host1")
+                    .Field("used_percent", 28.43234543);
+
+                writeApi.WritePoint(point);
+            }
+            
+            Console.WriteLine("*** Query Points ***");
+
+            var query = $"from(bucket: \"{database}/{retentionPolicy}\") |> range(start: -1h)";
+            var fluxTables = await client.GetQueryApi().QueryAsync(query);
+            var fluxRecords = fluxTables[0].Records;
+            fluxRecords.ForEach(record =>
+            {
+                Console.WriteLine($"{record.GetTime()} {record.GetMeasurement()}: {record.GetField()} {record.GetValue()}");
+            });
+            
+            client.Dispose();
+        }
+    }
+}

README.md

@@ -10,7 +10,7 @@
 
 This repository contains the reference C# client for the InfluxDB 2.0.
 
-#### Note: Use this client library with InfluxDB 2.x and InfluxDB 1.8+. For connecting to InfluxDB 1.7 or earlier instances, use the [influxdb-csharp](https://github.com/influxdata/influxdb-csharp) client library.
+#### Note: Use this client library with InfluxDB 2.x and InfluxDB 1.8+ ([see details](#influxdb-18-api-compatibility)). For connecting to InfluxDB 1.7 or earlier instances, use the [influxdb-csharp](https://github.com/influxdata/influxdb-csharp) client library.
 
 - [Features](#features)
 - [Documentation](#documentation)
@@ -213,6 +213,21 @@ namespace Examples
 }
 ```
 
+### InfluxDB 1.8 API compatibility
+
+[InfluxDB 1.8.0 introduced forward compatibility APIs](https://docs.influxdata.com/influxdb/latest/tools/api/#influxdb-2-0-api-compatibility-endpoints) for InfluxDB 2.0. This allow you to easily move from InfluxDB 1.x to InfluxDB 2.0 Cloud or open source.
+
+The following forward compatible APIs are available:
+
+| API | Endpoint | Description |
+|:----------|:----------|:----------|
+| [QueryApi.cs](Client/QueryApi.cs) | [/api/v2/query](https://docs.influxdata.com/influxdb/latest/tools/api/#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and [Flux](https://docs.influxdata.com/flux/latest/) _(endpoint should be enabled by [`flux-enabled` option](https://docs.influxdata.com/influxdb/latest/administration/config/#flux-enabled-false))_ |
+| [WriteApi.cs](Client/WriteApi.cs) | [/api/v2/write](https://docs.influxdata.com/influxdb/latest/tools/api/#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API |
+| [HealthAsync](Client/InfluxDBClient.cs#L362) | [/health](https://docs.influxdata.com/influxdb/latest/tools/api/#health-http-endpoint) | Check the health of your InfluxDB instance |    
+
+For detail info see [InfluxDB 1.8 example](Examples/InfluxDB18Example.cs).
+
+
 ### Flux queries in InfluxDB 1.7+
 
 The following example demonstrates querying using the Flux language.