The API reference do not reflect the changes made between 1.0 and 1.2

[radekholy24]

Can you please take a look at this:

URL for relevant page?

https://docs.influxdata.com/influxdb/v1.2/tools/api/

What products and version are you using?

server: InfluxDB 1.2.0 from the official Docker container (Debian GNU/Linux 8, x86_64)
client: curl 7.47.0, Ubuntu 16.04.1, x86_64

Where did you look before opening the issue?

https://github.com/influxdata/influxdb/issues/ and https://github.com/influxdata/docs.influxdata.com/issues/

Description

The current documentation of the possible API responses is a bit vague. It has a form of some examples. However, these examples do not match the actual behavior of InfluxDB.

E. g.:

$ curl -XPOST 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE "mydb"'
$ curl -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'mymeas,mytag1=1 myfield=12i 1463779800000000000'
$ curl -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'mymeas,mytag1=2 myfield=11i 1463779820000000000'
$ curl -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'mymeas,mytag2=1 myfield=18i 1463779840000000000'
$ curl -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'mymeas,mytag2=3 myfield=19i 1463779860000000000'
$ #and finally:
$ curl -G 'http://localhost:8086/query?db=mydb' --data-urlencode 'q=SELECT * FROM "mymeas"'

According to the Example 1 in the /query endpoint section, the last line of the script above should produce:

{"results":[{"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2016-05-20T21:30:00Z",12,"1",null],["2016-05-20T21:30:20Z",11,"2",null],["2016-05-20T21:30:40Z",18,null,"1"],["2016-05-20T21:31:00Z",19,null,"3"]]}]}]}

However, the actual response is:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2016-05-20T21:30:00Z",12,"1",null],["2016-05-20T21:30:20Z",11,"2",null],["2016-05-20T21:30:40Z",18,null,"1"],["2016-05-20T21:31:00Z",19,null,"3"]]}]}]}

Based on the resolution of influxdata/influxdb#8004, I guess that this is not a bug in InfluxDB itself but in the example in the documentation.

Can you please clarify the documentation regarding the possible API responses (e.g. that responses from different minor versions of InfluxDB may contain some additional properties)?

[rkuchan]

@PyDeQ, thank you for finding and alerting us to this issue. The change to API responses occurred in version 1.2.0 as part of PR 7638. We overlooked that change when we released the 1.2.0 docs - sincerest apologies for the confusion that caused.

We've gone through the documentation and updated the API responses with the new format (see #1041). Again, thank you for opening this issue - we really appreciate the feedback.

[radekholy24]

Hello, thank you for the quick response. Your fix have definitely helped.

However, I hoped that my report will also result in a more detailed specification of the API responses in order to avoid similar problems in the future. I mean, it still isn't clear whether the set of the keys of the JSON response can change in the future minor releases (e.g. > 1.2 and < 2.0).

Well, from the context of this bug, it is clear... If the key set could not change, the bug would be in InfluxDB (influxdata/influxdb#8004) and not in the documentation (this issue). However, I am not the only user of InfluxDB and others probably don't read every bug report...

So, can you please add a paragraph to the API Reference that describes how can API responses differ in different minor releases? Should I file another issue in order to track this request?