Skip to content

Commit f0245e3

Browse files
jstirnamanjstirnaman
committed
feat(api-ref): API reference for Core and Enterprise
1 parent 789c6fb commit f0245e3

File tree

10 files changed

+1687
-205
lines changed

10 files changed

+1687
-205
lines changed

‎api-docs/generate-api-docs.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ function generateHtml {
5757
# Get the first paragraph of the description for the meta description.
5858

5959
# Get the description with whitespace and newlines preserved.
60-
local description=$(yq e -r '.description // ""' $productVersion/$apiName/content/info.yml | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/"/\\"/g')
60+
local description=$(yq e -r '.description // ""' $productVersion/$apiName/content/info.yml | tr '\n' '\r' | sed 's/\r/\\n/g' | sed 's/"/\\"/g')
6161
# Get the aliases array from the configuration file.
6262
local aliases=$(yq e ".apis | .$api | .x-influxdata-docs-aliases" "$configPath")
6363
# If aliases is null, set it to an empty YAML array.

‎api-docs/influxdb3/core/v3/content/info.yml

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,20 @@ x-influxdata-version-matrix:
55
v2: Compatibility layer for InfluxDB 2.x clients (supported)
66
v3: Native API for InfluxDB 3.x (current)
77
description: |
8-
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
8+
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for
9+
interacting with InfluxDB 3 Core databases and resources.
10+
Use this API to:
911
10-
Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
12+
- Write data stored in InfluxDB 3 Core databases
13+
- Query data using SQL or InfluxQL
14+
- Process data using Processing engine plugins
15+
- Manage databases, tables, and Processing engine triggers
16+
- Perform administrative tasks and access system information
1117
12-
The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:
13-
- InfluxDB v1: Compatibility layer for InfluxDB 1.x clients (supported)
14-
- `/api/v2`: Compatibility layer for InfluxDB 2.x clients (supported)
15-
- `/api/v3`: Native API for InfluxDB 3.x (current)
18+
The API includes endpoints under the following paths:
19+
- `/api/v3`: InfluxDB 3 Core native endpoints
20+
- `/`: Compatibility endpoints for InfluxDB v1 workloads and clients
21+
- `/api/v2/write`: Compatibility endpoint for InfluxDB v2 workloads and clients
1622
1723
<!-- TODO: verify where to host the spec that users can download.
1824
This documentation is generated from the

‎api-docs/influxdb3/core/v3/content/tag-groups.yml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22
tags:
33
- Quick start
44
- Authentication
5-
- Headers
6-
- Pagination
5+
- Common parameters
76
- Response codes
7+
- Compatibility endpoints
8+
- Data I/O
9+
- Databases
10+
- Processing engine
11+
- Server information
12+
- Tables

‎api-docs/influxdb3/core/v3/ref.yml

Lines changed: 91 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,20 @@ openapi: 3.0.3
22
info:
33
title: InfluxDB 3 Core API Service
44
description: |
5-
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
5+
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for
6+
interacting with InfluxDB 3 Core databases and resources.
7+
Use this API to:
68
7-
Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
9+
- Write data stored in InfluxDB 3 Core databases
10+
- Query data using SQL or InfluxQL
11+
- Process data using Processing engine plugins
12+
- Manage databases, tables, and Processing engine triggers
13+
- Perform administrative tasks and access system information
814
9-
The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:
10-
- InfluxDB v1: Compatibility layer for InfluxDB 1.x clients (supported)
11-
- `/api/v2`: Compatibility layer for InfluxDB 2.x clients (supported)
12-
- `/api/v3`: Native API for InfluxDB 3.x (current)
15+
The API includes endpoints under the following paths:
16+
- `/api/v3`: InfluxDB 3 Core native endpoints
17+
- `/`: Compatibility endpoints for InfluxDB v1 workloads and clients
18+
- `/api/v2/write`: Compatibility endpoint for InfluxDB v2 workloads and clients
1319
1420
<!-- TODO: verify where to host the spec that users can download.
1521
This documentation is generated from the
@@ -35,59 +41,87 @@ servers:
3541
security:
3642
- BearerAuth: []
3743
tags:
44+
- name: Authentication
45+
description: |
46+
During the initial Alpha phase, InfluxDB 3 Core does not require authentication.
47+
x-traitTag: true
3848
- name: Compatibility endpoints
3949
description: |
4050
InfluxDB 3 provides compatibility endpoints for InfluxDB 1.x and InfluxDB 2.x workloads and clients.
4151
42-
### Write data
52+
### Write data using v1- or v2-compatible endpoints
4353
44-
Use the following endpoints for writing data stored in InfluxDB 3 Core:
54+
- [`/api/v2/write` endpoint](#operation/PostV2Write)
55+
for InfluxDB v2 clients and when you bring existing InfluxDB v2 write workloads to InfluxDB 3.
56+
- [`/write` endpoint](#operation/PostV1Write) for InfluxDB v1 clients and when you bring existing InfluxDB v1 write workloads to InfluxDB 3.
4557
46-
- **Recommended**: [`/api/v3/write_lp` endpoint]()
47-
for new write workloads and InfluxDB v3 clients that write line protocol.
48-
- [`/api/v2/write` endpoint]()
49-
for InfluxDB v2 clients and bringing existing InfluxDB v2 write workloads to InfluxDB 3.
50-
- [`/write` endpoint]() for InfluxDB v1 clients and bringing existing InfluxDB v1 write workloads to InfluxDB 3.
58+
For new workloads, use the [`/api/v3/write_lp` endpoint](#operation/PostWriteLP).
5159
52-
All endpoints accept the same line protocol format and process data in the same way.
53-
Like previous versions, InfluxDB 3 is a schema-on-write database, however tag column definitions for a table are immutable; you can't add tag columns to a table after it's created.
60+
All endpoints accept the same line protocol format.
5461
5562
### Query data
5663
57-
InfluxDB 3 supports Flight+gRPC and HTTP requests for querying data.
64+
Use the HTTP [`/query`](#operation/GetV1ExecuteQuery) endpoint for InfluxDB v1 clients and v1 query workloads using InfluxQL.
65+
66+
For new workloads, use one of the following:
5867
59-
- HTTP [`/api/v3/query_sql` endpoint]() for new query workloads using SQL.
60-
- HTTP [`/api/v3/query_influxql` endpoint]() for new query workloads using InfluxQL.
61-
- Flight SQL and InfluxDB 3 _Flight+gRPC_ APIs for querying with SQL or InfluxQL. For more information about using Flight+gRPC, see [InfluxDB 3 client libraries](https://github.com/InfluxCommunity).
62-
- HTTP [`/query`]() endpoint for InfluxDB v1 clients and v1 query workloads using InfluxQL.
68+
- HTTP [`/api/v3/query_sql` endpoint](#operation/GetExecuteQuerySQL) for new query workloads using SQL.
69+
- HTTP [`/api/v3/query_influxql` endpoint](#operation/GetExecuteInfluxQLQuery) for new query workloads using InfluxQL.
70+
- Flight SQL and InfluxDB 3 _Flight+gRPC_ APIs for querying with SQL or InfluxQL. For more information about using Flight APIs, see [InfluxDB 3 client libraries](https://github.com/InfluxCommunity).
6371
6472
### Server information
6573
66-
Server information endpoints are compatible with InfluxDB 1.x and InfluxDB 2.x clients.
74+
Server information endpoints such as `/health` and `metrics` are compatible with InfluxDB 1.x and InfluxDB 2.x clients.
6775
- name: Data I/O
6876
description: Write and query data
6977
- name: Databases
7078
description: Create, read, update, and delete database and cache resources
79+
- description: |
80+
Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use.
81+
82+
### Common parameters
83+
84+
The following table shows common parameters used by many InfluxDB API endpoints.
85+
Many endpoints may require other parameters in the query string or in the
86+
request body that perform functions specific to those endpoints.
87+
88+
| Query parameter | Value type | Description |
89+
|:------------------------ |:--------------------- |:-------------------------------------------|
90+
| `db` | string | The database name |
91+
92+
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
93+
The following table shows common headers used by many InfluxDB API endpoints.
94+
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
95+
the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body.
96+
97+
| Header | Value type | Description |
98+
|:------------------------ |:--------------------- |:-------------------------------------------|
99+
| `Accept` | string | The content type that the client can understand. |
100+
| `Authorization` | string | The authorization scheme and credential. |
101+
| `Content-Length` | integer | The size of the entity-body, in bytes. |
102+
| `Content-Type` | string | The format of the data in the request body. |
103+
name: Headers and parameters
104+
x-traitTag: true
71105
- name: Processing engine
72-
description: Manage processing engine triggers and plugins
73-
- name: Server information
74-
description: Retrieve server metrics, status, and version information
75-
- name: Tables
76-
description: Manage table schemas and data
77-
- name: Quick start
78106
description: |
79-
#### Get started with the InfluxDB HTTP API for InfluxDB 3 Core
107+
Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins.
80108
109+
InfluxDB 3 Core provides the InfluxDB 3 Processing engine, an embedded Python VM that can dynamically load and trigger Python plugins in response to events in your database.
110+
Use Processing engine plugins and triggers to run code and perform tasks for different database events.
111+
112+
To get started with the Processing engine, see the [Processing engine and Python plugins](/influxdb3/core/processing-engine/) guide.
113+
- name: Quick start
114+
description: |
81115
1. [Check the status](#section/Server-information) of the InfluxDB server.
82116
83117
```bash
84-
curl "http://localhost:9191/health"
118+
curl "http://localhost:8181/health"
85119
```
86120
87121
2. [Write data](#section/Compatibility-endpoints/Write-data) to InfluxDB.
88122
89123
```bash
90-
curl "http://localhost:9191/api/v3/write_lp?db=sensors&precision=auto" \
124+
curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" \
91125
--data-raw "home,room=Kitchen temp=72.0
92126
home,room=Living\ room temp=71.5"
93127
```
@@ -97,7 +131,7 @@ tags:
97131
3. [Query data](#section/Compatibility-endpoints/Query-data) from InfluxDB.
98132
99133
```bash
100-
curl -G "http://localhost:9191/api/v3/query_sql" \
134+
curl -G "http://localhost:8181/api/v3/query_sql" \
101135
--data-urlencode "db=sensors" \
102136
--data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
103137
--data-urlencode "format=jsonl"
@@ -111,36 +145,10 @@ tags:
111145
112146
For more information about using InfluxDB 3 Core, see the [Get started](/influxdb3/core/get-started/) guide.
113147
x-traitTag: true
114-
- name: Authentication
115-
description: |
116-
During the initial Alpha phase, InfluxDB 3 Core does not require authentication.
117-
x-traitTag: true
118-
- description: |
119-
Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use.
120-
121-
### Common parameters
122-
123-
The following table shows common parameters used by many InfluxDB API endpoints.
124-
Many endpoints may require other parameters in the query string or in the
125-
request body that perform functions specific to those endpoints.
126-
127-
| Query parameter | Value type | Description |
128-
|:------------------------ |:--------------------- |:-------------------------------------------|
129-
| `db` | string | The database name |
130-
131-
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
132-
The following table shows common headers used by many InfluxDB API endpoints.
133-
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
134-
the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body.
135-
136-
| Header | Value type | Description |
137-
|:------------------------ |:--------------------- |:-------------------------------------------|
138-
| `Accept` | string | The content type that the client can understand. |
139-
| `Authorization` | string | The authorization scheme and credential. |
140-
| `Content-Length` | integer | The size of the entity-body, in bytes. |
141-
| `Content-Type` | string | The format of the data in the request body. |
142-
name: Headers and parameters
143-
x-traitTag: true
148+
- name: Server information
149+
description: Retrieve server metrics, status, and version information
150+
- name: Tables
151+
description: Manage table schemas and data
144152
paths:
145153
/write:
146154
post:
@@ -1202,12 +1210,12 @@ paths:
12021210
type: string
12031211
get:
12041212
operationId: GetProcessingEnginePluginRequest
1205-
summary: On-request processing engine plugin request
1213+
summary: On Request processing engine plugin request
12061214
description: |
1207-
Sends a request to invoke an _on-request_ processing engine plugin.
1215+
Sends a request to invoke an _On Request_ processing engine plugin.
12081216
The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.
12091217
1210-
An on-request plugin implements the following signature:
1218+
An On Request plugin implements the following signature:
12111219
12121220
```python
12131221
def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)
@@ -1229,8 +1237,18 @@ paths:
12291237
- Processing engine
12301238
post:
12311239
operationId: PostProcessingEnginePluginRequest
1232-
summary: On-request processing engine plugin request
1233-
description: Sends custom request to a processing engine plugin.
1240+
summary: On Request processing engine plugin request
1241+
description: |
1242+
Sends a request to invoke an _On Request_ processing engine plugin.
1243+
The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.
1244+
1245+
An On Request plugin implements the following signature:
1246+
1247+
```python
1248+
def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)
1249+
```
1250+
1251+
The response depends on the plugin implementation.
12341252
parameters:
12351253
- $ref: '#/components/parameters/ContentType'
12361254
requestBody:
@@ -1744,6 +1762,11 @@ x-tagGroups:
17441762
tags:
17451763
- Quick start
17461764
- Authentication
1747-
- Headers
1748-
- Pagination
1765+
- Common parameters
17491766
- Response codes
1767+
- Compatibility endpoints
1768+
- Data I/O
1769+
- Databases
1770+
- Processing engine
1771+
- Server information
1772+
- Tables

‎api-docs/influxdb3/enterprise/v3/content/info.yml

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,24 @@ x-influxdata-version-matrix:
55
v2: Compatibility layer for InfluxDB 2.x clients (supported)
66
v3: Native API for InfluxDB 3.x (current)
77
description: |
8-
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
8+
The InfluxDB HTTP API for InfluxDB 3 Enterprise provides a programmatic interface for
9+
interacting with InfluxDB 3 Enterprise databases and resources.
10+
Use this API to:
911
10-
Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
12+
- Write data stored in InfluxDB 3 Enterprise databases
13+
- Query data using SQL or InfluxQL
14+
- Process data using Processing engine plugins
15+
- Manage databases, tables, and Processing engine triggers
16+
- Perform administrative tasks and access system information
1117
12-
The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:
13-
- InfluxDB v1: Compatibility layer for InfluxDB 1.x clients (supported)
14-
- `/api/v2`: Compatibility layer for InfluxDB 2.x clients (supported)
15-
- `/api/v3`: Native API for InfluxDB 3.x (current)
18+
The API includes endpoints under the following paths:
19+
- `/api/v3`: InfluxDB 3 Enterprise native endpoints
20+
- `/`: Compatibility endpoints for InfluxDB v1 workloads and clients
21+
- `/api/v2/write`: Compatibility endpoint for InfluxDB v2 workloads and clients
1622
1723
<!-- TODO: verify where to host the spec that users can download.
1824
This documentation is generated from the
19-
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml).
25+
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/).
2026
-->
2127
license:
2228
name: MIT

‎api-docs/influxdb3/enterprise/v3/content/tag-groups.yml

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,11 @@
22
tags:
33
- Quick start
44
- Authentication
5-
- Headers
6-
- Pagination
5+
- Common parameters
76
- Response codes
8-
- System information endpoints
9-
- name: All endpoints
10-
tags:
11-
- Ping
12-
- Query
13-
- Write
7+
- Compatibility endpoints
8+
- Data I/O
9+
- Databases
10+
- Processing engine
11+
- Server information
12+
- Tables

0 commit comments

Comments
 (0)