Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Api version guide #24

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Api version guide #24

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0a9c67b
add API version progression guidelines
mukundansundar Apr 12, 2023
56ee30e
clarify when alpha suffixed paths will be removed
mukundansundar Apr 12, 2023
4801ef8
add changes for beta lifecycle stage also
mukundansundar Aug 17, 2023
7138b9c
fix typo
mukundansundar Aug 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions guides/api-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,29 @@ _Backwards-**compatible** changes_
* May be proposed to _any_ API
* Proposed changes to both the HTTP and gRPC API must be included

### Progression of API version to Stable
<!-- TODO: change this when once this issue relating to Beta is decided https://github.com/dapr/proposals/issues/13-->

Currently for HTTP API, the non-stable API has the path `v1.0-alpha1` instead of stable APIs having the form `v1.0`. Similarly for gRPC, the non-stable API has the suffix `Alpha1` added to the gRPC methods.
SDKs implementing the API before the stable release use the above mentioned paths/methods for HTTP and gRPC respectively. Once the API is promoted to stable, the SDKs must be updated to use the stable paths/methods.

#### Compatibility

To cater to the scenario where an older SDK is accessing a newer version of Dapr, the following compatibility rules must be followed:
- If there are no breaking changes in the API(User request/response) from the prior version to the version it is made stable, then both the old and new paths/methods must be supported by the Dapr runtime.
- The `alpha` suffixed API paths/methods must be removed from the Dapr runtime once all _core_ SDKs have been updated (preferrably in the next Dapr release). Removal of the `alpha` suffixed API is still considered a breaking change and must be documented in the release notes as such.
- If there are breaking changes in the API(User request/response) from the prior version to the version it is made stable, then only the new paths/methods must be supported by the Dapr runtime. The old paths/methods must be removed from the Dapr runtime.

> Note: The components themselves might have breaking changes, that will not affect the API version progression.

Example Scenario:
Consider v3.0 of JS SDK supporting the Config API in Alpha stage and Dapr runtime v1.10. The Config API is promoted to Stable in v1.11 of the runtime. If between v1.10 Dapr and v1.11 Dapr runtime there are no breaking changes in the Config API then both Path/`v1.0-alpha1`/Method`Alpha1` and Path/`v1.0`/Method must be supported by the Dapr runtime.

Then the SDK can be updated independent of the runtime i.e. v3.0 version of JS SDK will still continue to work with the v1.11 runtime Config API.

If there are breaking changes in the Config API then only Path/`v1.0`/Method must be supported by the Dapr runtime. In this case, the SDKs must be updated to use the new path/methods. In this case only the newer version of the SDK will work with the newer version of the runtime.

> Note: This guidance is specifically for Dapr runtime SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs.

## Requirements for Building Block changes

Expand All @@ -102,10 +125,7 @@ Finally on addition of a new API, there may be addition of the capability to eit
- Implement the suite of conformance tests as part of the existing suite of tests for the building block
- Ensure successful execution of existing conformance and certification tests for any modified components



## Progression of an API/Building block

### Alpha to Beta

In addition to the requirements that are required of any Alpha API, the following requirements must be met so that the API can graduate to Beta. For an API to be promoted to Beta, it must exist for at least one release cycle after its initial addition as Alpha. (i.e something added in 1.10 could become Beta in 1.12, having been stabilized through 1.11)
Expand All @@ -131,6 +151,7 @@ For **building blocks** to progress, the following criteria are required:

In addition to the requirements for a Beta API, the following requirements must be met so that the API can graduate to Stable. Similar to the previous phase change, this API must have been in the Beta phase for at least one full release _without any breaking changes_. In addition, the following criteria apply:

* Change API version based on the [API version progression guidelines](#progression-of-api-version-to-stable)
* E2E scenarios must be well defined and comprehensive
* Performance tests must be added(in case a new building block does not have performance tests in the Alpha/Beta stage)/updated
* Expected performance data must be added to documentation
Expand Down
14 changes: 8 additions & 6 deletions templates/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Links to any relevant resources go here:

## Alpha / Beta / Stable

For each stage, identify the expectations of this feature at that stage. For example,
For each stage, identify the expectations of this feature at that stage. For example,
are there any performance issues, configuration changes or feature deprecation that will happen?

* Anticipated performance / known limitations
Expand Down Expand Up @@ -63,15 +63,17 @@ Additionally, for **building blocks**:
Additionally, for **building blocks**:

- [ ] Conformance tests updated to match any API changes that have been made
- [ ] Conformance tests exercise both positive and negative cases
- [ ] Minimum of N (three?) implementations of this building block
- [ ] Certification tests for implementations
- [ ] Conformance tests exercise both positive and negative cases
- [ ] Minimum of N (three?) implementations of this building block
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we keep this three or is it a TBD?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call out, this should be decided. IMO 3 is reasonable.

- [ ] Certification tests for implementations
- [ ] APIs that are used in the building block also meet Beta criteria


## Stable

## Stable

- [ ] Change API version to stable. See [Stable API Versioning](../guides/api-design.md#progression-of-api-version-to-stable)
- [ ] HTTP `v1.0-suffix` to `v1.0`
- [ ] gRPC `MethodSuffix` to `Method`
Comment on lines +74 to +76
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be also added to beta? Change alpha suffix to beta?

- [ ] Documentation is complete in `dapr/docs` with any changes since Beta
- [ ] E2E scenarios well defined and comprehensive
- [ ] Performance tests exist and regressions will prevent them from successfully passing
Expand Down