Skip to content

Commit 87a72c7

Browse files
Ignacio Van Droogenbroeckclaude
andcommitted
Add comprehensive integration documentation and updates
New Integration Documentation: - Grafana datasource plugin with Apache Arrow support - VS Code extension with SQL IntelliSense and Arc Notebooks - OpenTelemetry Collector exporter with unified observability Updates: - Updated integrations category description to include all tools - Updated API reference with complete endpoint listing and WAL/Data Lifecycle sections - Simplified Getting Started to Docker/Kubernetes only (removed native) - Simplified Docker installation documentation - Deleted native.md installation guide per user request - Updated all API endpoints to /api/v1/ prefix - Added Content-Type headers to all curl examples - Updated SQL queries to use database.table notation (prod.cpu, etc.) - Fixed escaped curly braces in API reference path parameters 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 5a69fc6 commit 87a72c7

13 files changed

Lines changed: 2366 additions & 858 deletions

File tree

docs/api-reference/overview.md

Lines changed: 67 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/query
2626
- `GET /health` - Health check
2727
- `GET /ready` - Readiness probe
2828
- `GET /docs` - Swagger UI
29-
- `GET /redoc` - ReDoc
3029
- `GET /openapi.json` - OpenAPI spec
3130

3231
## Quick Examples
@@ -47,7 +46,7 @@ data = {
4746
}
4847

4948
response = requests.post(
50-
"http://localhost:8000/write/v1/msgpack",
49+
"http://localhost:8000/api/v1/write/msgpack",
5150
headers={
5251
"Authorization": "Bearer YOUR_TOKEN",
5352
"Content-Type": "application/msgpack"
@@ -96,56 +95,78 @@ curl http://localhost:8000/health
9695

9796
High-performance data writing endpoints.
9897

99-
- **[MessagePack Protocol](/arc/api-reference/ingestion#messagepack)** (Recommended - 8x faster)
100-
- **[Line Protocol](/arc/api-reference/ingestion#line-protocol)** (InfluxDB compatible)
101-
- **[JSON API](/arc/api-reference/ingestion#json)** (Simple integration)
102-
103-
[View Ingestion API →](/arc/api-reference/ingestion)
98+
- **POST /api/v1/write** - InfluxDB 1.x line protocol (text/plain)
99+
- **POST /api/v1/write/line-protocol** - Standard line protocol endpoint
100+
- **POST /api/v1/write/influxdb** - InfluxDB 2.x compatible endpoint
101+
- **POST /api/v1/write/msgpack** - High-performance MessagePack format (recommended)
104102

105103
### Querying
106104

107105
Execute SQL queries with DuckDB.
108106

109-
- **[Execute Query](/arc/api-reference/queries#execute)** - Run SQL queries (JSON format)
110-
- **[Execute Query (Arrow)](/arc/api-reference/queries#arrow)** - Run SQL queries (Apache Arrow format)
111-
- **[Stream Results](/arc/api-reference/queries#stream)** - Stream large datasets
112-
- **[Query Estimation](/arc/api-reference/queries#estimate)** - Estimate query cost
113-
- **[List Measurements](/arc/api-reference/queries#list)** - Show available tables
114-
115-
[View Query API →](/arc/api-reference/queries)
107+
- **POST /api/v1/query** - Run SQL queries (JSON format)
108+
- **POST /api/v1/query/arrow** - Run SQL queries (Apache Arrow format)
109+
- **POST /api/v1/query/stream** - Stream large datasets (CSV/JSON)
116110

117111
### Authentication
118112

119113
Manage API tokens and access control.
120114

121-
- **[Create Token](/arc/api-reference/auth#create)** - Generate new tokens
122-
- **[List Tokens](/arc/api-reference/auth#list)** - View all tokens
123-
- **[Rotate Token](/arc/api-reference/auth#rotate)** - Generate new token value
124-
- **[Delete Token](/arc/api-reference/auth#delete)** - Revoke access
125-
126-
[View Auth API →](/arc/api-reference/auth)
115+
- **POST /api/v1/auth/verify** - Verify token validity
116+
- **GET /api/v1/auth/tokens** - List all tokens
117+
- **POST /api/v1/auth/tokens** - Create new token
118+
- **DELETE /api/v1/auth/tokens/\{token_id\}** - Revoke token
127119

128120
### Health & Monitoring
129121

130122
Monitor Arc's health and performance.
131123

132-
- **[Health Check](/arc/api-reference/monitoring#health)** - Service status
133-
- **[Metrics](/arc/api-reference/monitoring#metrics)** - Prometheus metrics
134-
- **[Memory Profile](/arc/api-reference/monitoring#memory)** - Memory usage
135-
- **[Logs](/arc/api-reference/monitoring#logs)** - Application logs
136-
137-
[View Monitoring API →](/arc/api-reference/monitoring)
124+
- **GET /health** - Service health status
125+
- **GET /ready** - Readiness probe
126+
- **GET /** - API information and version
138127

139128
### Compaction
140129

141130
Manage Parquet file compaction.
142131

143-
- **[Status](/arc/api-reference/compaction#status)** - Current compaction state
144-
- **[Trigger](/arc/api-reference/compaction#trigger)** - Manual compaction
145-
- **[History](/arc/api-reference/compaction#history)** - Job history
146-
- **[Candidates](/arc/api-reference/compaction#candidates)** - Eligible partitions
132+
- **GET /api/v1/compaction/status** - Current compaction state
133+
- **POST /api/v1/compaction/trigger** - Trigger manual compaction
134+
- **GET /api/v1/compaction/history** - View compaction job history
135+
- **GET /api/v1/compaction/candidates** - List eligible partitions for compaction
136+
137+
### Write-Ahead Log (WAL)
138+
139+
Manage Write-Ahead Log for zero data loss.
140+
141+
- **GET /api/v1/wal/status** - Current WAL state
142+
- **GET /api/v1/wal/stats** - WAL statistics and metrics
143+
- **GET /api/v1/wal/files** - List WAL files
144+
- **POST /api/v1/wal/flush** - Force WAL flush to Parquet
145+
- **POST /api/v1/wal/compact** - Compact WAL files
146+
- **POST /api/v1/wal/recover** - Recover data from WAL
147+
148+
### Data Lifecycle
149+
150+
Manage data retention, deletion, and aggregation.
151+
152+
**Retention Policies** - See [Retention Policies Documentation](/arc/data-lifecycle/retention-policies)
153+
- **GET /api/v1/retention** - List all retention policies
154+
- **POST /api/v1/retention** - Create new retention policy
155+
- **GET /api/v1/retention/\{policy_id\}** - Get specific policy
156+
- **PUT /api/v1/retention/\{policy_id\}** - Update retention policy
157+
- **DELETE /api/v1/retention/\{policy_id\}** - Delete retention policy
158+
- **POST /api/v1/retention/\{policy_id\}/execute** - Execute policy manually
159+
160+
**Delete Operations** - See [Delete Operations Documentation](/arc/data-lifecycle/delete-operations)
161+
- **POST /api/v1/delete** - Delete data matching conditions
147162

148-
[View Compaction API →](/arc/api-reference/compaction)
163+
**Continuous Queries** - See [Continuous Queries Documentation](/arc/data-lifecycle/continuous-queries)
164+
- **GET /api/v1/continuous_queries** - List all continuous queries
165+
- **POST /api/v1/continuous_queries** - Create new continuous query
166+
- **GET /api/v1/continuous_queries/\{query_id\}** - Get specific query
167+
- **PUT /api/v1/continuous_queries/\{query_id\}** - Update continuous query
168+
- **DELETE /api/v1/continuous_queries/\{query_id\}** - Delete continuous query
169+
- **POST /api/v1/continuous_queries/\{query_id\}/execute** - Execute query manually
149170

150171
## Interactive Documentation
151172

@@ -239,12 +260,15 @@ cors_origins = ["http://localhost:3000", "https://your-app.com"]
239260

240261
## Versioning
241262

242-
Arc API uses URL versioning:
263+
Arc API uses URL versioning with the `/api/v1/` prefix:
243264

244-
- `/write` - Current version (InfluxDB compatibility)
245-
- `/write/v1/msgpack` - Versioned MessagePack endpoint
246-
- `/api/v1/write` - InfluxDB 1.x compatible
247-
- `/api/v1/write/influxdb` - InfluxDB 2.x compatible
265+
- `/api/v1/write` - InfluxDB 1.x line protocol (text/plain)
266+
- `/api/v1/write/line-protocol` - Standard line protocol endpoint
267+
- `/api/v1/write/influxdb` - InfluxDB 2.x compatible endpoint
268+
- `/api/v1/write/msgpack` - High-performance MessagePack format (recommended)
269+
- `/api/v1/query` - SQL query endpoint (JSON format)
270+
- `/api/v1/query/arrow` - Apache Arrow format queries
271+
- `/api/v1/query/stream` - Streaming query results
248272

249273
## Client Libraries
250274

@@ -272,7 +296,7 @@ class ArcClient:
272296
}
273297

274298
response = requests.post(
275-
f"{self.base_url}/write/v1/msgpack",
299+
f"{self.base_url}/api/v1/write/msgpack",
276300
headers={**self.headers, "Content-Type": "application/msgpack"},
277301
data=msgpack.packb(data)
278302
)
@@ -320,7 +344,7 @@ class ArcClient {
320344
}]
321345
};
322346

323-
await this.client.post('/write/v1/msgpack',
347+
await this.client.post('/api/v1/write/msgpack',
324348
msgpack.encode(data),
325349
{ headers: { 'Content-Type': 'application/msgpack' } }
326350
);
@@ -382,7 +406,7 @@ func (c *ArcClient) Write(m string, fields map[string]interface{}, tags map[stri
382406
}
383407

384408
body, _ := msgpack.Marshal(data)
385-
req, _ := http.NewRequest("POST", c.BaseURL+"/write/v1/msgpack", bytes.NewBuffer(body))
409+
req, _ := http.NewRequest("POST", c.BaseURL+"/api/v1/write/msgpack", bytes.NewBuffer(body))
386410
req.Header.Set("Authorization", "Bearer "+c.Token)
387411
req.Header.Set("Content-Type", "application/msgpack")
388412

@@ -509,7 +533,7 @@ for chunk in response.iter_content(chunk_size=8192):
509533

510534
## Next Steps
511535

512-
- **[Ingestion API](/arc/api-reference/ingestion)** - Write data to Arc
513-
- **[Query API](/arc/api-reference/queries)** - Execute SQL queries
514-
- **[Authentication ](/arc/api-reference/auth)** - Manage tokens
515-
- **[Interactive Docs](http://localhost:8000/docs)** - Try the API
536+
- **[Getting Started](/arc/getting-started)** - Learn how to use Arc
537+
- **[Data Lifecycle](/arc/data-lifecycle/retention-policies)** - Manage data retention and deletion
538+
- **[Interactive Docs ](http://localhost:8000/docs)** - Try the API with Swagger UI
539+
- **[OpenAPI Spec](http://localhost:8000/openapi.json)** - Download OpenAPI specification

0 commit comments

Comments
 (0)