github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 17:59:23 -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
#### 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.
<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.
##### 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
@ -335,4 +363,5 @@ export class MyPlugin implements Plugin {
```
#### Additional reading
For more details on the versioning specification see [this document](https://docs.google.com/document/d/1YpF6hXIHZaHvwNaQAxWFzexUF1nbqACTtH2IfDu0ldA/edit?usp=sharing).