[OAS] Support setting availability #196647

jloleysens · 2024-10-17T09:26:23Z

Summary

Close #181995

Related #195325

Enables API authors to set APIs overall availability to one of:

experimental: the "loosest" commitment to a public API, may be removed
beta: expect changes, but the intention is to reach stable
stable: rock soild 🪨 , ain't going nowhere and safe to integrate with and expect long term support with a deprecation window of 18 months

Note: at time of writing we still need to figure out what experimental and beta practically mean for APIs, but could enable a bit more iteration without versioning and maintenance overhead.

Checklist

Unit or functional tests were updated or added to match the most common scenarios

jloleysens · 2024-10-17T09:26:32Z

/ci

jloleysens · 2024-10-17T09:27:01Z

packages/kbn-router-to-openapispec/src/util.ts

+export function setXState(
+  availability: RouteConfigOptions<RouteMethod>['availability'],
+  operation: CustomOperationObject
+): void {
+  if (availability) {
+    if (availability.stability === 'experimental') {
+      operation['x-state'] = 'Technical Preview';
+    }
+    if (availability.stability === 'beta') {
+      operation['x-state'] = 'Beta';
+    }
+  }
+}


This is the logic for adding x-state, added the types for since but we can implement it in another PR.

jloleysens · 2024-10-17T13:35:43Z

/ci

lcawl · 2024-10-17T16:06:36Z

I added this new availability clause to a couple of endpoints and regenerated the OpenAPI document and it looks great! The only thing I can't tell from this PR is how/if I could indicate that an endpoint has differing availability in serverless context, for example. In the elasticsearch specification they have this flavour-awareness per https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md#add-the-endpoint-request-definition. Is this something that's possible and desirable here too?

TinaHeiligers · 2024-10-17T21:18:02Z

packages/core/http/core-http-server/src/router/route.ts

+   * @remark intended to be used for informational purposes only.
+   *
+   */
+  availability?: {


The ES specification has availability as either stack or serverless and we're missing that in the route config options.
It's probably not a deal breaker now but would be great to surface in the generated spec.

TinaHeiligers

Looks good thus far. I left a question about choosing stability default that I'd like to hear your thoughts on. The main concern is consistency and risk.

TinaHeiligers · 2024-10-17T21:25:00Z

packages/core/http/core-http-server/src/router/route.ts

+   *
+   */
+  availability?: {
+    /** @default stable */


Route access defaults to 'internal'. WDYT about reflecting that here and setting the default stability as 'experimental'? That way there's less risk to adding new routes and forgetting to change the stability descriptor to 'experimental' pre-GA.

Yeah, I considered this too, but then realised our existing public routes would default to "experimental" too unless we explicitly set them all to "stable". So, in practice, we default to "stable" already today.

I'm not opposed to changing the default, and I tend to agree with you starting as "experimental" is better I just wanted to avoid a wider effort. We could do it as follow up work, happy to open an issue.

I wasn't too concerned about internal routes bc they are in principle "not available", but I think we can capture that in the doc comment.

Yeah, I considered this too, but then realised our existing public routes would default to "experimental" too unless we explicitly set them all to "stable".

We don't have that many public routes as we do internal. From a cost/benefit pov, changing public routes to stable is worth the effort of mitigating the risk of accidentally marking a route as stable when it's not.

I'm not opposed to changing the default, and I tend to agree with you starting as "experimental" is better I just wanted to avoid a wider effort. We could do it as follow up work, happy to open an issue.

Sounds good, LMK when you've created an issue.

#197003 🙌🏻

packages/core/http/core-http-server/src/router/route.ts

packages/kbn-router-to-openapispec/openapi-types.d.ts

Co-authored-by: Christiane (Tina) Heiligers <[email protected]>

jloleysens · 2024-10-18T09:13:47Z

@TinaHeiligers @lcawl re "flavour" availability would this not already be captured by the fact that we have a kibana.yaml and kibana.serverless.yaml bundle for each flavour? Teams can dynamically register routes per offering.

Let me know what you think!

elasticmachine · 2024-10-18T09:14:17Z

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

TinaHeiligers · 2024-10-18T15:52:14Z

re "flavour" availability would this not already be captured by the fact that we have a kibana.yaml and kibana.serverless.yaml bundle for each flavour?

~~It would if we release separate specs for each. So far, I've only seen the OpenApi specs for stack. Where do we publish those for Serverless?~~
nm, I found them in our internal docs.

TinaHeiligers

Unblocking to add x-state with the understanding that we'll switch the default stability to experimental in a follow up PR.

TinaHeiligers · 2024-10-18T21:49:56Z

packages/core/http/core-http-server/src/router/route.ts

+   *
+   */
+  availability?: {
+    /** @default stable */


I'm not opposed to changing the default, and I tend to agree with you starting as "experimental" is better I just wanted to avoid a wider effort. We could do it as follow up work, happy to open an issue.

Sounds good, LMK when you've created an issue.

kibanamachine · 2024-10-21T10:31:00Z

Starting backport for target branches: 8.16

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

elasticmachine · 2024-10-21T10:31:13Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: a2a9b3c

Failed CI Steps

FTR Configs #53

Test Failures

[job] [logs] FTR Configs #53 / Rule execution logic API Detection Engine - Execution logic @ess @serverless New terms type rules, alert suppression should NOT suppress and update an alert if the alert is closed

Metrics [docs]

Unknown metric groups

API count

id	before	after	diff
`@kbn/core-http-server`	532	533	+1

History

💚 Build #243758 succeeded 5e462cf
💛 Build #243521 was flaky a783311
💔 Build #243387 failed 58d13de

cc @jloleysens

## Summary Close elastic#181995 Related elastic#195325 ### Checklist - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios --------- Co-authored-by: Christiane (Tina) Heiligers <[email protected]> (cherry picked from commit 608cc70)

kibanamachine · 2024-10-21T10:35:35Z

💚 All backports created successfully

Status	Branch	Result
✅	8.16

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

Questions ?

Please refer to the Backport tool documentation

# Backport This will backport the following commits from `main` to `8.16`: - [[OAS] Support setting availability (#196647)](#196647)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Jean-Louis Leysens <[email protected]>

jbudz · 2024-10-22T00:29:54Z

@jloleysens there's a version gap with this backport. Can you check if this should also be backported to 8.x/8.17?

jloleysens · 2024-10-23T09:53:51Z

💚 All backports created successfully

Status	Branch	Result
✅	8.x

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

Questions ?

Please refer to the Backport tool documentation

## Summary Close elastic#181995 Related elastic#195325 ### Checklist - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios --------- Co-authored-by: Christiane (Tina) Heiligers <[email protected]> (cherry picked from commit 608cc70)

# Backport This will backport the following commits from `main` to `8.x`: - [[OAS] Support setting availability (#196647)](#196647)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) \n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sqren/backport)\n\n\n\nCo-authored-by: Jean-Louis Leysens <[email protected]>"}},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT-->

jloleysens added 6 commits October 17, 2024 11:22

updated router types

b33f607

updated tests to check that metadata is being passed through

ed1e333

fix minor type bug

4254559

fix typo

e03d4d2

added integration level test for availability

60be4e4

set x-state

58d13de

jloleysens self-assigned this Oct 17, 2024

jloleysens commented Oct 17, 2024

View reviewed changes

fix types

a783311

TinaHeiligers reviewed Oct 17, 2024

View reviewed changes

lcawl mentioned this pull request Oct 17, 2024

[API][DOCS] Add x-state to saved object APIs #196783

Open

jloleysens and others added 2 commits October 18, 2024 11:08

Update packages/core/http/core-http-server/src/router/route.ts

6fe22e6

Co-authored-by: Christiane (Tina) Heiligers <[email protected]>

updated comment

251b5ce

Merge branch 'main' into oas/support-x-state

5e462cf

jloleysens marked this pull request as ready for review October 18, 2024 09:14

jloleysens requested a review from a team as a code owner October 18, 2024 09:14

TinaHeiligers approved these changes Oct 18, 2024

View reviewed changes

Merge branch 'main' into oas/support-x-state

a2a9b3c

jloleysens enabled auto-merge (squash) October 21, 2024 08:35

jloleysens mentioned this pull request Oct 21, 2024

[OAS] Change default availability.stability to experimental #197003

Open

jloleysens merged commit 608cc70 into elastic:main Oct 21, 2024
23 checks passed

kibanamachine mentioned this pull request Oct 21, 2024

[8.16] [OAS] Support setting availability (#196647) #197025

Merged

jloleysens deleted the oas/support-x-state branch October 23, 2024 09:52

jloleysens added the v8.17.0 label Oct 23, 2024

jloleysens mentioned this pull request Oct 23, 2024

[8.x] [OAS] Support setting availability (#196647) #197394

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[OAS] Support setting availability #196647

[OAS] Support setting availability #196647

jloleysens commented Oct 17, 2024 •

edited

Loading

jloleysens commented Oct 17, 2024

jloleysens Oct 17, 2024 •

edited

Loading

jloleysens commented Oct 17, 2024

lcawl commented Oct 17, 2024

TinaHeiligers Oct 17, 2024

TinaHeiligers left a comment

TinaHeiligers Oct 17, 2024 •

edited

Loading

jloleysens Oct 18, 2024

TinaHeiligers Oct 18, 2024

TinaHeiligers Oct 18, 2024

jloleysens Oct 21, 2024

jloleysens commented Oct 18, 2024 •

edited

Loading

elasticmachine commented Oct 18, 2024

TinaHeiligers commented Oct 18, 2024 •

edited

Loading

TinaHeiligers left a comment

TinaHeiligers Oct 18, 2024

kibanamachine commented Oct 21, 2024

elasticmachine commented Oct 21, 2024

API count

kibanamachine commented Oct 21, 2024

jbudz commented Oct 22, 2024

jloleysens commented Oct 23, 2024

[OAS] Support setting availability #196647

[OAS] Support setting availability #196647

Conversation

jloleysens commented Oct 17, 2024 • edited Loading

Summary

Checklist

jloleysens commented Oct 17, 2024

jloleysens Oct 17, 2024 • edited Loading

Choose a reason for hiding this comment

jloleysens commented Oct 17, 2024

lcawl commented Oct 17, 2024

TinaHeiligers Oct 17, 2024

Choose a reason for hiding this comment

TinaHeiligers left a comment

Choose a reason for hiding this comment

TinaHeiligers Oct 17, 2024 • edited Loading

Choose a reason for hiding this comment

jloleysens Oct 18, 2024

Choose a reason for hiding this comment

TinaHeiligers Oct 18, 2024

Choose a reason for hiding this comment

TinaHeiligers Oct 18, 2024

Choose a reason for hiding this comment

jloleysens Oct 21, 2024

Choose a reason for hiding this comment

jloleysens commented Oct 18, 2024 • edited Loading

elasticmachine commented Oct 18, 2024

TinaHeiligers commented Oct 18, 2024 • edited Loading

TinaHeiligers left a comment

Choose a reason for hiding this comment

TinaHeiligers Oct 18, 2024

Choose a reason for hiding this comment

kibanamachine commented Oct 21, 2024

elasticmachine commented Oct 21, 2024

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

Metrics [docs]

API count

History

kibanamachine commented Oct 21, 2024

💚 All backports created successfully

Questions ?

jbudz commented Oct 22, 2024

jloleysens commented Oct 23, 2024

💚 All backports created successfully

Questions ?

jloleysens commented Oct 17, 2024 •

edited

Loading

jloleysens Oct 17, 2024 •

edited

Loading

TinaHeiligers Oct 17, 2024 •

edited

Loading

jloleysens commented Oct 18, 2024 •

edited

Loading

TinaHeiligers commented Oct 18, 2024 •

edited

Loading