[OAS] Promote space awareness in REST docs by jloleysens · Pull Request #230594 · elastic/kibana

jloleysens · 2025-08-05T14:01:24Z

Summary

Copies the ES approach to specifying alternate paths in our docs. This is a best effort approach to providing docs users with information about each path's space alternative. Every path that is "spaces aware" will have the following call out in the description:

Relates to: https://github.com/elastic/docs-content-internal/issues/40

elasticmachine · 2025-08-05T14:01:28Z

Pinging @elastic/kibana-core (Team:Core)

jloleysens · 2025-08-05T15:14:41Z

oas_docs/scripts/promote_space_awareness.js

+function getSpaceAlternatePathHtml(method, path) {
+  return `<div><span class="operation-verb ${method.toLocaleLowerCase()}">${method}</span>&nbsp;<span class="operation-path">/s/{space_id}${path}</span></div>\n\nSee [spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.`;
+}


Copying https://github.com/elastic/elasticsearch-specification/blob/4ff06a6135ca742cd3f0a81feb9a46625c4ce867/compiler-rs/clients_schema_to_openapi/src/paths.rs#L287

elasticmachine · 2025-08-05T17:18:37Z

⏳ Build in-progress, with failures

Buildkite Build
Commit: efaaf88

Failed CI Steps

Test Failures

[job] [logs] FTR Configs #41 / Serverless Observability feature flag testing - Deployment-agnostic API integration tests SyntheticsCustomStatusRule NumberOfChecks - Location threshold > 1 - ungrouped - 2 down locations - recoveryStrategy: firstUp should be down again
[job] [logs] FTR Configs #41 / Serverless Observability feature flag testing - Deployment-agnostic API integration tests SyntheticsCustomStatusRule NumberOfChecks - Location threshold > 1 - ungrouped - 2 down locations - recoveryStrategy: firstUp should be down again

History

💔 Build #326533 failed c16d37d

cc @jloleysens

jloleysens · 2025-08-06T08:15:58Z

oas_docs/scripts/promote_space_awareness.js

+const NON_SPACE_PATH_PREFIXES = new Set([
+  '/api/upgrade_assistant',
+  '/api/logstash/pipeline',
+  '/api/logstash/pipelines',
+  '/api/task_manager/_health',
+  '/api/cases/reporters',
+  '/api/encrypted_saved_objects/_rotate_key',
+  '/api/short_url',
+  '/api/features',
+  '/api/security/role',
+  '/api/spaces',
+  '/api/security/session/_invalidate',
+]).values();


This is the "best effort" aspect. Based on where we did not mention the spaces alternative in our previous docs iterations. There may be a few paths this does not catch.

The other side-effect of this is that new paths will get the spaces alternative mentioned unless they are captured here. I think this is OK, but others may feel differently.

SGTM. I wonder if another downside is: if most endpoints have the extra Space awareness callout, maybe folks won't notice this subset.

Yeah, that's true. It's kind of a drop in the bucket. The most useful one to skip is probably /api/spaces... And come to think of it /api/status too. Will add these in #230931

florent-leborgne

LGTM. Thanks for the improvement! If possible I'd wait for @georgewallace's input since this work relates to https://github.com/elastic/docs-content-internal/issues/40

oas_docs/scripts/promote_space_awareness.js

Co-authored-by: florent-leborgne <florent.leborgne@elastic.co>

szabosteve

LGTM! Thanks for the temporary fix!

afharo · 2025-08-06T20:04:39Z

oas_docs/scripts/promote_space_awareness.js

+const NON_SPACE_PATH_PREFIXES = new Set([
+  '/api/upgrade_assistant',
+  '/api/logstash/pipeline',
+  '/api/logstash/pipelines',
+  '/api/task_manager/_health',
+  '/api/cases/reporters',
+  '/api/encrypted_saved_objects/_rotate_key',
+  '/api/short_url',
+  '/api/features',
+  '/api/security/role',
+  '/api/spaces',
+  '/api/security/session/_invalidate',
+]).values();


SGTM. I wonder if another downside is: if most endpoints have the extra Space awareness callout, maybe folks won't notice this subset.

kibanamachine · 2025-08-07T07:22:27Z

Starting backport for target branches: 8.19

https://github.com/elastic/kibana/actions/runs/16797879779

kibanamachine · 2025-08-07T07:29:03Z

💔 All backports failed

Status	Branch	Result
❌	8.19	Backport failed because of merge conflicts

Manual backport

To create the backport manually run:

node scripts/backport --pr 230594

Questions ?

Please refer to the Backport tool documentation

jloleysens · 2025-08-07T12:06:08Z

💚 All backports created successfully

Status	Branch	Result
✅	8.19

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

(cherry picked from commit c9fedf5) # Conflicts: # oas_docs/output/kibana.serverless.yaml # oas_docs/output/kibana.yaml

## Summary Follow up on #230594

## Summary Follow up on elastic#230594

# Backport This will backport the following commits from `main` to `8.19`: - [[OAS] Promote space awareness in REST docs (#230594)](#230594)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)  --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Michael Dokolin <dokmic@gmail.com>

## Summary Follow up on elastic#230594

## Summary Follow up on elastic#230594 (cherry picked from commit 0fb028c) # Conflicts: # oas_docs/output/kibana.serverless.yaml # oas_docs/output/kibana.yaml

added promote space awareness script

c16d37d

jloleysens self-assigned this Aug 5, 2025

jloleysens requested a review from a team as a code owner August 5, 2025 14:01

jloleysens commented Aug 5, 2025

View reviewed changes

Merge branch 'main' into oas/promote-space-awareness

efaaf88

Merge branch 'main' into oas/promote-space-awareness

3b7d155

jloleysens commented Aug 6, 2025

View reviewed changes

florent-leborgne approved these changes Aug 6, 2025

View reviewed changes

oas_docs/scripts/promote_space_awareness.js Outdated Show resolved Hide resolved

jloleysens and others added 2 commits August 6, 2025 10:27

Update oas_docs/scripts/promote_space_awareness.js

59c86d0

Co-authored-by: florent-leborgne <florent.leborgne@elastic.co>

[CI] Auto-commit changed files from 'make api-docs'

703629a

szabosteve approved these changes Aug 6, 2025

View reviewed changes

afharo approved these changes Aug 6, 2025

View reviewed changes

jloleysens merged commit c9fedf5 into elastic:main Aug 7, 2025
12 checks passed

kibanamachine mentioned this pull request Aug 7, 2025

[Oblt Onboarding] Adjust e2e onboarding tests to work in serverless environment #229969

Merged

This was referenced Aug 7, 2025

[OAS] Do not promote space path on serverless #230931

Merged

[8.19] [OAS] Promote space awareness in REST docs (#230594) #230975

Merged

jloleysens added a commit to jloleysens/kibana that referenced this pull request Aug 7, 2025

[OAS] Promote space awareness in REST docs (elastic#230594)

996c76d

(cherry picked from commit c9fedf5) # Conflicts: # oas_docs/output/kibana.serverless.yaml # oas_docs/output/kibana.yaml

jloleysens added a commit that referenced this pull request Aug 7, 2025

[OAS] Do not promote space path on serverless (#230931)

0fb028c

## Summary Follow up on #230594

gergoabraham pushed a commit to gergoabraham/kibana that referenced this pull request Aug 7, 2025

[OAS] Promote space awareness in REST docs (elastic#230594)

d7fe5c5

gergoabraham pushed a commit to gergoabraham/kibana that referenced this pull request Aug 7, 2025

[OAS] Do not promote space path on serverless (elastic#230931)

a3487d1

## Summary Follow up on elastic#230594

kibanamachine mentioned this pull request Aug 7, 2025

[Docs] Add defaultSolution setting to config reference #229650

Merged

denar50 pushed a commit to denar50/kibana that referenced this pull request Aug 8, 2025

[OAS] Promote space awareness in REST docs (elastic#230594)

5f9b880

kibanamachine added the v8.19.1 label Aug 8, 2025

NicholasPeretti pushed a commit to NicholasPeretti/kibana that referenced this pull request Aug 18, 2025

[OAS] Promote space awareness in REST docs (elastic#230594)

5c53898

NicholasPeretti pushed a commit to NicholasPeretti/kibana that referenced this pull request Aug 18, 2025

[OAS] Do not promote space path on serverless (elastic#230931)

ce1a175

## Summary Follow up on elastic#230594

jloleysens mentioned this pull request Sep 23, 2025

[OAS] Figure out how to make spaces more discoverable in our API docs #224598

Closed

Conversation

jloleysens commented Aug 5, 2025 • edited by kibanamachine Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

elasticmachine commented Aug 5, 2025

Uh oh!

jloleysens Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Aug 5, 2025

⏳ Build in-progress, with failures

Failed CI Steps

Test Failures

History

Uh oh!

jloleysens Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afharo Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

jloleysens Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

florent-leborgne left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

szabosteve left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afharo Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kibanamachine commented Aug 7, 2025

Uh oh!

kibanamachine commented Aug 7, 2025

💔 All backports failed

Manual backport

Questions ?

Uh oh!

jloleysens commented Aug 7, 2025

💚 All backports created successfully

Questions ?

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jloleysens commented Aug 5, 2025 •

edited by kibanamachine

Loading

jloleysens Aug 6, 2025 •

edited

Loading

szabosteve left a comment •

edited

Loading