Skip to content

Improve ES|QL data federation API docs and examples#6497

Merged
leemthompo merged 9 commits into
mainfrom
review-pr-6366
Jul 20, 2026
Merged

Improve ES|QL data federation API docs and examples#6497
leemthompo merged 9 commits into
mainfrom
review-pr-6366

Conversation

@leemthompo

@leemthompo leemthompo commented Jul 17, 2026

Copy link
Copy Markdown
Member

closes https://github.com/elastic/docs-content-internal/issues/1214

Summary

Improves the documentation experience for the ES|QL data federation APIs added in #6366.

  • Adds OpenAPI request and response examples for all six data source and dataset endpoints, covering eight request flows and eight corresponding success responses.
  • Marks all six endpoints as Technical Preview; Stack documentation identifies them as added in 9.5.0.
  • Uses concise, consistent navigation titles for getting, listing, creating, updating, and deleting data sources and datasets.
  • Connects every endpoint to the feature by mentioning ES|QL data federation in the opening description and adding an ES|QL Data Federation learn-more link.
  • Clarifies important behavior, including concrete-name versus wildcard misses, atomic dataset deletion, dependent-dataset conflicts, credential redaction, naming requirements, and create-or-replace semantics.
  • Adds request examples that generate client samples, including authenticated curl commands that use $ELASTICSEARCH_URL instead of the generic api.example.com fallback.

Testing

  • All eight Console request examples were tested against a live Elasticsearch deployment and returned the expected successful responses.
  • All eight generated curl examples were independently tested against the same live deployment and returned HTTP 200 with the expected response shapes.
  • Curl testing used unique temporary resource names and successfully deleted both resources afterward.
  • Confirmed returned data-source credentials use the ::es_redacted:: sentinel.
  • Generated 761 language examples with zero conversion errors.
  • Regenerated the schema successfully with Node.js 24, including TypeScript output validation.
  • Generated both Stack and Serverless documentation OpenAPI definitions and verified their explicit authenticated curl samples.
  • Verified all six Stack operations render Technical preview; Added in 9.5.0 and all six Serverless operations render Technical preview.
  • Rendered and inspected both Stack and Serverless Bump previews.

Screenshot

esql-data-federation-api-docs-screenshot

@github-actions

Copy link
Copy Markdown
Contributor

Following you can find the validation changes against the target branch for the APIs.

No changes detected.

You can validate these APIs yourself by using the make validate target.

@l-trotta l-trotta left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good, thank you! just a nit, to avoid the backport CI failing, could you remove the outputs from the PR? CI will regenerate everything anyways

@leemthompo
leemthompo merged commit 6d43637 into main Jul 20, 2026
10 checks passed
@leemthompo
leemthompo deleted the review-pr-6366 branch July 20, 2026 14:32
l-trotta pushed a commit that referenced this pull request Jul 20, 2026
* Improve ES|QL data federation API documentation

* Add ES|QL data federation API examples

* Use ES|QL Data Federation link text

* Shorten ES|QL data federation API titles

* Add generated ES|QL data federation language examples

* Update specification output

* Mark ES|QL data federation APIs as technical preview

* Update specification output

* Remove generated outputs

(cherry picked from commit 6d43637)

Co-authored-by: Liam Thompson <leemthompo@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants