github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-25 02:09:32 -04:00
Code Issues Projects Releases Packages Wiki Activity

[HTTP/Docs] Clarify versioning practices for internal vs public endpoints (#158828)

Browse source 
## Summary

Expands on the HTTP versioning tutorial with more information about
`internal` vs `public` endpoints.

## Screenshots

<img width="875" alt="Screenshot 2023-06-01 at 15 52 18"
src="f8f790a0-31ec-4123-89db-b1f01aa17845">

<img width="923" alt="Screenshot 2023-06-01 at 15 52 33"
src="f97ad89b-face-4176-a814-8e17ecd3d2a5">
This commit is contained in:
Jean-Louis Leysens 2023-06-02 13:40:42 +02:00 • committed by GitHub
parent 4281e6b9ef
commit f21f7ce6ca
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

39
dev_docs/tutorials/versioning_http_apis.mdx
View file

@ -212,17 +212,45 @@ The changes are:
### 4. Adhere to the HTTP versioning specification ### 4. Adhere to the HTTP versioning specification
#### Choosing the right version
##### Public endpoints We categorize our endpoints based on their intended audience: `public` or `internal`. Different versioning practices apply to each.
#### Public endpoints
Public endpoints include any endpoint that is intended for users to directly integrate with via HTTP. Public endpoints include any endpoint that is intended for users to directly integrate with via HTTP.
<DocCallOut title="Version all public endpoints">
All Kibana's public endpoints must be versioned using the format described below.
</DocCallOut>
##### Version lifecycle
Introducing a new version or moving a current version into deprecation to eventually be deleted must
follow [this process](https://github.com/elastic/dev/issues/new?assignees=&labels=breaking-change-proposal&projects=&template=breaking-change.md).
##### Version format
Choose a date string in the format `YYYY-MM-DD`. This date should be the date that a (group) of APIs was made available. Choose a date string in the format `YYYY-MM-DD`. This date should be the date that a (group) of APIs was made available.
##### Internal endpoints --------
Internal endpoints are all non-public endpoints (see definition above).
If you need to maintain backwards-compatibility for an internal endpoint use a single, larger-than-zero number. Ex. `1`. #### Internal endpoints
Internal endpoints are all non-public endpoints (see definition above). Note: these endpoints do not need to be versioned,
but versioning can be leveraged to maintain BWC with existing clients.
##### Version lifecycle
Introducing/removing a version is up to the team who owns the HTTP API. Consider how introduction or removal might
affect client code when being rolled out.
<DocCallOut title="Keep internal versions to a minimum">
To keep maintenance light it is **highly** recommended to reduce the number of versions you have for internal endpoints. In your code it is possible to
centrally define and share internal versions through code that is `common` to your browser- and server-side plugin code.
</DocCallOut>
##### Version format
If you need to version an internal endpoint use a single, larger-than-zero major version. Ex. `1`.
#### Use the versioned router #### Use the versioned router
@ -335,4 +363,5 @@ export class MyPlugin implements Plugin {
``` ```
#### Additional reading #### Additional reading
For more details on the versioning specification see [this document](https://docs.google.com/document/d/1YpF6hXIHZaHvwNaQAxWFzexUF1nbqACTtH2IfDu0ldA/edit?usp=sharing). For more details on the versioning specification see [this document](https://docs.google.com/document/d/1YpF6hXIHZaHvwNaQAxWFzexUF1nbqACTtH2IfDu0ldA/edit?usp=sharing).