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 all 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
22 changes: 19 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,24 @@ _Backwards-**compatible** changes_
* May be proposed to _any_ API
* Proposed changes to both the HTTP and gRPC API must be included

### Progression of API lifecycle to Stable

Currently for HTTP API, the alpha API has the path `v1.0-alpha1` and the beta API must have the path `v1.0-beta1` and the stable APIs must have the form `v1.0`. Similarly for gRPC, the alpha and beta APIs must have the suffix `Alpha1` or `Beta1` 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 as soon as possible.

#### Compatibility

For `alpha` to `beta` or `alpha` to `stable` or `beta` to `stable` progressions, the following rules must be followed:
- Once an API has progressed to "higher" stage be it `beta` or `stable` from `alpha`, the prior API endpoints (HTTP/gRPC) must be still supported together with the newer stage (`beta` or `stable`) API endpoints in Dapr runtime for atleast 1 release to give SDKs enough time to update to the new API endpoints. Functionality wise, there may be breaking changes between a API stage transitions, but both the prior API endpoint and the newer endpoint must point to the same same functionality once it has graduated to a particular stage.

> Note: The components themselves might have breaking changes, that will not affect the API-SDK compatibility.

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. In this case both path `/v1.0-alpha1`, method`Alpha1` and path `/v1.0`, ,method without suffix 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.

> Note: This guidance is specifically for Dapr runtime API-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 +120,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 +146,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-lifecycle-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