Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update API reference documentation #5819

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

Update API reference documentation #5819

wants to merge 5 commits into from

Conversation

peterbarnett03
Copy link
Collaborator

Adds OpenAPI spec

@peterbarnett03 peterbarnett03 self-assigned this Feb 3, 2025
jstirnaman
jstirnaman approved these changes Feb 3, 2025
View reviewed changes
Copy link
Contributor

@jstirnaman jstirnaman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this! Looks great - just a few minor suggestions.
I need to tweak our scripts to add it and then I'll push to staging.

api-docs/influxdb3/core/v3/ref.yml
schema:
type: string
description: Database name.
- name: accept_partial
Copy link
Contributor

@jstirnaman jstirnaman Feb 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- name: accept_partial
- name: accept_partial

Was this recently added? I thought it didn't work with the legacy endpoints when I tried last week.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't work.

api-docs/influxdb3/core/v3/ref.yml Outdated
summary: Write Line Protocol (Legacy)
description: >
Accepts line protocol data and writes it to the database.
Write options are provided via query parameters.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Write options are provided via query parameters.
Write options are provided via query parameters.
Provides compatibility for InfluxDB v1 workloads.

api-docs/influxdb3/core/v3/ref.yml Outdated
- BearerAuth: []
/api/v2/write:
post:
summary: Write Line Protocol (v2)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
summary: Write Line Protocol (v2)
summary: Write Line Protocol (v2-compatibility)

api-docs/influxdb3/core/v3/ref.yml Outdated
paths:
/write:
post:
summary: Write Line Protocol (Legacy)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
summary: Write Line Protocol (Legacy)
summary: Write Line Protocol (v1-compatibility)

api-docs/influxdb3/core/v3/ref.yml Outdated
summary: Write Line Protocol (v2)
description: >
Accepts line protocol data and writes it to the database.
Write options are provided via query parameters.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Write options are provided via query parameters.
Write options are provided via query parameters.
Provides compatibility for InfluxDB v2 workloads.

api-docs/influxdb3/core/v3/ref.yml Outdated
- BearerAuth: []
/query:
get:
summary: Execute InfluxQL Query
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
summary: Execute InfluxQL Query
summary: Execute InfluxQL Query (v1-compatibility)

@jstirnaman
Copy link
Contributor

@peterbarnett03 Currently working on this - I'll push to this branch for review.

@jstirnaman
feat(v3): WIP: Revise API specs for Core and Enterprise
e15120c 
- Adds basic support for core and enterprise in getswagger.sh
- Adds custom OpenAPI info for Core and Enterprise
- Validates as OpenAPI 3.0 (using Spectral)
    - operationId
    - tags
- Revises use of Legacy, v2
- TODO: need to check and validate in UI, adjust tags if nec.
jstirnaman
jstirnaman reviewed Feb 5, 2025
View reviewed changes
api-docs/influxdb3/core/v3/content/tag-groups.yml
@@ -0,0 +1,13 @@
- name: Using the InfluxDB HTTP API
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops.
@jstirnaman TODO: update or remove these.

@jstirnaman jstirnaman marked this pull request as draft February 5, 2025 15:34
@jstirnaman
Copy link
Contributor

jstirnaman commented Feb 5, 2025 •
edited
Loading

@peterbarnett03 Noting what I've found while testing:

  • API precision values are long-form-only (second), CLI values are abbrv-only (s)

  • Only /api/v3/write_lp supports accept_partial, right? Legacy APIs reject partial writes.

  • Should we remove no_sync for now? It's not available in the CLI yet and I'm not sure how to verify its affect in the API. What does it do?

  • I'm gonna back off using the term "Legacy" so we don't imply deprecation.

@peterbarnett03
Copy link
Collaborator Author

@jstirnaman Yeah, upon further review, we should probably walk through this live together since it's such a big update. You're write on the partial.

no_sync confirms WAL writes before persistence to object storage.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jstirnaman jstirnaman jstirnaman approved these changes

Assignees

@peterbarnett03 peterbarnett03

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@peterbarnett03 @jstirnaman