[Versioned APIs] Versioned interfaces dev docs guide #150705
Conversation
…the introduction of the new domain
jloleysens
added
Team:Core
|
Pinging @elastic/kibana-core (Team:Core) |
There was a problem hiding this comment.
The example here makes sense to me. I think what will really help folks reading these docs is when we can show how it would tie into a versioned API, e.g. show a couple route handlers.
But we'll need to have clarity on our versioning strategy first, unless we want to try to design a helper for apps to use which could abstract away the need to know how exactly the versions are being implemented in a given request. Dunno how much thought we've given to this yet so it may not be possible at this stage, just throwing the idea out there. Edit: Almost forgot we had done an exploratory design for what a versioned router would look like.
Co-authored-by: Luke Elmers <lukeelmers@gmail.com>
Co-authored-by: Luke Elmers <lukeelmers@gmail.com>
Yeah I agree. I've been working on some types-only designs for how a helper like this might look that I'm hoping to get feedback on: #149943 Do you think we should rather have a fuller picture of the router + client in place before merging something like this to main? Perhaps adding "[Draft]" to the title of the guide could be a good middle-ground? |
There was a problem hiding this comment.
Do you think we should rather have a fuller picture of the router + client in place before merging something like this to main?
IMO there is no need to hold merging this as it can always be updated as we know more. My point was just that I think it'll be easier for teams to grasp once they can see a complete end-to-end example.
| import type { DataSource } from '../data_source/v2'; | ||
|
|
||
| // Optionally, re-export the entire set of types. | ||
| export * from './v1'; |
There was a problem hiding this comment.
Would the re-export be overriden by any interface below it with the same name?
There was a problem hiding this comment.
Yes, exactly that
jloleysens
changed the title
There was a problem hiding this comment.
As @afharo already expressed, most (all?) interfaces from the examples are missing the export keyword.
Apart from that, the examples looks good to me, and I think it could be considered a fine initial documentation.
## Summary Adds a dev docs guide for the core-approved versioning strategy. This strategy is subject to some iteration but is based on the work we did for the Saved Objects Management plugin in elastic#149495. Closes elastic#149929 ## How to test 1. Run `./scripts/dev_docs.sh` 2. Navigate to "Versioning interfaces" in the side nav menu --------- Co-authored-by: Luke Elmers <lukeelmers@gmail.com>
Summary
Adds a dev docs guide for the core-approved versioning strategy. This strategy is subject to some iteration but is based on the work we did for the Saved Objects Management plugin in #149495.
Closes #149929
How to test
./scripts/dev_docs.sh