You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/src/content/docs/docs/getstarted/versioning.md
+59-3Lines changed: 59 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,8 @@ Versioning lets you evolve your API without breaking existing clients. This guid
8
8
9
9
To support multiple API versions, define them in an enum. After defining your enum, link it to your namespace using the `@versioned` decorator. For each version, specify your dependencies:
10
10
11
+
**ARM:**
12
+
11
13
```tsp
12
14
/** Contoso API versions */
13
15
enum Versions {
@@ -22,6 +24,19 @@ enum Versions {
22
24
namespace Microsoft.ContosoProviderHub;
23
25
```
24
26
27
+
**Data-plane:**
28
+
29
+
```tsp
30
+
enum Versions {
31
+
v1,
32
+
v2,
33
+
}
34
+
35
+
@versioned(Versions)
36
+
@service(#{ title: "Widget Service" })
37
+
namespace DemoService;
38
+
```
39
+
25
40
## Adding a Resource or Operation
26
41
27
42
To introduce a new model or operation in a specific version (and all later versions), use the `@added` decorator:
@@ -35,7 +50,7 @@ model Employee {
35
50
}
36
51
```
37
52
38
-
**Add an operation in v2:**
53
+
**Add an operation in v2 (ARM):**
39
54
40
55
```tsp
41
56
@armResourceOperations
@@ -46,6 +61,16 @@ interface Employees {
46
61
}
47
62
```
48
63
64
+
**Add an operation in v2 (Data-plane):**
65
+
66
+
```tsp
67
+
interface Widgets {
68
+
getWidget is Operations.ResourceRead<Widget>;
69
+
@added(Versions.v2)
70
+
createOrReplaceWidget is Operations.ResourceCreateOrReplace<Widget>;
71
+
}
72
+
```
73
+
49
74
## Adding a Property or Parameter
50
75
51
76
You can also add new properties or parameters to models and operations in a specific version:
@@ -61,7 +86,7 @@ model Employee {
61
86
}
62
87
```
63
88
64
-
**Add a parameter in v2:**
89
+
**Add a parameter in v2 (ARM):**
65
90
66
91
```tsp
67
92
@armResourceOperations
@@ -78,11 +103,31 @@ interface Employees {
78
103
}
79
104
```
80
105
106
+
**Add a parameter in v2 (Data-plane):**
107
+
108
+
```tsp
109
+
interface Widgets {
110
+
getWidget is Operations.ResourceRead<
111
+
Widget,
112
+
Traits = {
113
+
parameters: {
114
+
@query
115
+
name: string;
116
+
117
+
@added(Versions.v2)
118
+
@query
119
+
department?: string;
120
+
};
121
+
}
122
+
>;
123
+
}
124
+
```
125
+
81
126
## Adding New Operations
82
127
83
128
You can add new operations to an interface for a specific version:
84
129
85
-
**Add a new operation in v2:**
130
+
**Add a new operation in v2 (ARM):**
86
131
87
132
```tsp
88
133
@armResourceOperations
@@ -94,6 +139,17 @@ interface Employees {
94
139
}
95
140
```
96
141
142
+
**Add a new operation in v2 (Data-plane):**
143
+
144
+
```tsp
145
+
interface Widgets {
146
+
getWidget is Operations.ResourceRead<Widget>;
147
+
148
+
@added(Versions.v2)
149
+
moveWidget is Operations.ResourceAction<Widget, MoveRequest, MoveResponse>;
150
+
}
151
+
```
152
+
97
153
---
98
154
99
155
For more details and advanced scenarios, see the [full versioning documentation](../howtos/Versioning/01-about-versioning.md).
Copy file name to clipboardExpand all lines: website/src/content/docs/docs/howtos/Versioning/01-about-versioning.md
+5-114Lines changed: 5 additions & 114 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,25 +19,22 @@ Additionally, in Azure, preview APIs have a limited lifespan and limited support
19
19
- Only one version may be marked with the `@previewVersion` decorator.
20
20
- Mark all changes from the latest stable with appropriate versioning decorators, using `Versions.<PreviewVersion>` as the version argument (where `<PreviewVersion>` is the name of the last enum value)
21
21
22
-
## Preview Versioning Rules for Data Plane APIs
23
-
24
-
- For a new GA, add a new version enum **BEFORE** the preview enum value. Manually change all **preview** items that are GA'ing so that the `@added` version value matches the new GA enum value
25
-
- For any items remaining in **preview**, rename the **old preview** enum value to the **new preview** enum value.
26
-
27
22
## Common Version Transition Scenarios
28
23
29
-
This section describes how to evolve APIs according to these guidelines, and how to meet both the single active preview guideline and the need to maintain some preview versions in certain situations:
24
+
These documents add specific guidance about how to follow these guidelines for specific version changes
30
25
31
26
-[How to add a new preview version when the last version was preview](./02-preview-after-preview.md)
32
27
-[How to add a new stable version when the last version was preview](./03-stable-after-preview.md)
33
28
-[How to add a new preview version when the last version was stable](./04-preview-after-stable.md)
34
29
-[How to add a new stable version when the last version was stable](./05-stable-after-stable.md)
35
30
36
-
This section also describes how to convert an existing multi-API TypeSpec spec with multiple previews into a spec with a single active preview. Note that this is not required, but it may significantly simplify the versioning decoration in your spec:
31
+
This document describes how to convert an existing multi-API TypeSpec spec with multiple previews into a spec with a single active preview. Note that this is not required, but it may significantly simplify the versioning decoration in your spec:
37
32
38
33
-[How to convert a spec with multiple preview versions into a spec with a single active preview](./uncommon-scenarios/01-converting-specs.md)
39
34
40
-
Additionally, there are some services that may always have features that remain in preview after a stable version is released. This can happen, for example, if there are multiple independent teams that own different resources in a service and operate on their own schedule. The recommended way to handle this scenario is to model your ResourceProvider as multiple services, so each version and the corresponding SDKs can version independently. For some older services, this is not an option, so there is specialized guidance on how to maintain preview features over stable API releases (described below). If you are thinking about splitting your service, or about creating a new preview version with every stable version, be sure to have a discussion with the [Azure API Stewardship Board](https://aka.ms/azapi/officehours) and the [Azure SDK team](https://eng.ms/docs/products/azure-developer-experience/onboard) first.
35
+
### Uncommon Scenarios
36
+
37
+
Additionally, there are some (ARM) services that may always have features that remain in preview after a stable version is released. This can happen, for example, if there are multiple independent teams that own different resources in a service and operate on their own schedule. The recommended way to handle this scenario is to model your ARM ResourceProvider as multiple services, so each sub-service and the corresponding SDKs can version independently. For some older services, this is not an option, so there is specialized guidance on how to maintain preview features over stable API releases (described below). If you are thinking about splitting your service, or about creating a new preview version with every stable version, be sure to have a discussion with the [Azure API Stewardship Board](https://aka.ms/azapi/officehours) and the [Azure SDK team](https://eng.ms/docs/products/azure-developer-experience/onboard) first.
41
38
42
39
-[How to manage a single active preview if your service always has some features in preview (ARM only)](./uncommon-scenarios/02-perpetual-preview.md)
43
40
@@ -57,109 +54,3 @@ It is safe to remove the swagger for an old API version if any of the following
57
54
- The OpenAPI document in the azure-rest-api-specs repo is not needed for ARM registration
58
55
59
56
It is recommended that preview api-versions are set for retirement within 90 days when a preview or stable API is introduced. See the [Azure Retirement Policy](https://aka.ms/AzureRetirementPolicy) and [Azure Retirement Process](https://aka.ms/cpexretirementsprocess) for details.
60
-
61
-
### Usage Examples
62
-
63
-
#### New preview version
64
-
65
-
In the following example we introduce a new preview version called `v3Preview` which includes everything from `v2` plus adds a new property to the `Widget` resource.
66
-
67
-
```diff lang=tsp
68
-
import "@typespec/http";
69
-
import "@typespec/rest";
70
-
import "@typespec/versioning";
71
-
import "@azure-tools/typespec-azure-core";
72
-
73
-
using Http;
74
-
using Rest;
75
-
using Versioning;
76
-
using Azure.Core;
77
-
78
-
79
-
@versioned(Versions)
80
-
@service(#{ title: "Widget Service" })
81
-
namespace DemoService;
82
-
83
-
enum Versions {
84
-
v1,
85
-
v2,
86
-
+ @previewVersion
87
-
+ v3Preview
88
-
}
89
-
90
-
/**
91
-
* Model defining the Widget resource
92
-
*/
93
-
model Widget {
94
-
/**
95
-
* Identifier of the Widget Resource
96
-
*/
97
-
@visibility(Lifecycle.Read)
98
-
@key id: string;
99
-
/**
100
-
* Weight of the widget
101
-
*/
102
-
weight: int32;
103
-
/**
104
-
* Color of the widget;
105
-
*/
106
-
color: "red" | "blue";
107
-
/**
108
-
* Nickname of the Widget resource
109
-
*/
110
-
+ @added(Versions.v3Preview) nickname: string;
111
-
}
112
-
```
113
-
114
-
#### Adding a new stable (GA) version
115
-
116
-
This example builds on the previous one, where `v3` is introduced which GA's the `nickname` property introduced in `v3Preview`
Copy file name to clipboardExpand all lines: website/src/content/docs/docs/howtos/Versioning/02-preview-after-preview.md
+51Lines changed: 51 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -174,3 +174,54 @@ This includes the following steps:
174
174
```
175
175
176
176
- If you _do_ need the older preview version (see [Should I Retain the OpenAPI for an Old Preview API](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api-arm-only) if you are not sure), update README.md to include a new entry for the new preview version.
177
+
178
+
## Data-Plane Example
179
+
180
+
In the following example, we introduce a new preview version called `v3Preview` which includes everything from `v2` plus adds a new property to the `Widget` resource.
Copy file name to clipboardExpand all lines: website/src/content/docs/docs/howtos/Versioning/03-stable-after-preview.md
+53Lines changed: 53 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -164,3 +164,56 @@ This includes the following steps:
164
164
```
165
165
166
166
- update README.md to include a new entry for the new preview version.
167
+
168
+
## Data-Plane Example
169
+
170
+
This example builds on the data-plane preview version example in [Adding a Preview Version when the Last Version was Preview](./02-preview-after-preview.md#data-plane-example), where `v3` is introduced which GA's the `nickname` property introduced in `v3Preview`.
0 commit comments