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

Jump to bottom

Added advice from 8/11/2020 board meeting #213

Open
wants to merge 2 commits into
base: vNext
Choose a base branch
from
Open

Added advice from 8/11/2020 board meeting #213

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a38ca7
Added advice from 8/11/2020 board meeting
adrianhall Aug 11, 2020
ed8f146
Added updated from Jeffrey Richter
adrianhall Sep 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
36 changes: 22 additions & 14 deletions azure/Guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
| ----------- | ------- | --------------------------------------------------- |
| 2020-Mar-31 | v3.1 | 1st public release of the Azure REST API Guidelines |
| 2020-Jul-31 | v3.2 | Added service advice for initial versions |
| 2020-Aug-11 | v3.3 | Clarified advice around extensible enums |

## Introduction

Expand Down Expand Up @@ -152,19 +153,23 @@ With the exception of _Compliance changes_ (which are extremely rare), Azure ser

A _breaking change_ is any change in the API that may cause client or service code making the API call to fail. Obvious examples of such a change are the removal of an endpoint, adding or removing a required field or changing the format of the body (from XML to JSON for example). Even though we recommend clients ignore new fields, there are many libraries and clients that fail when new fields are introduced. Removing an endpoint from an API is always a _breaking change_. Adding a new endpoint is always an _evolutionary change_. Changes to properties may be _evolutionary_ or _breaking_ depending on the type of change and whether the change is to an input parameter or output parameter:

| Property change | Input | Output |
|:-----------------------|:------------:|:------------:|
| Remove a property | Breaking | Breaking |
| Add optional property | Evolutionary | Breaking |
| Add required property | Breaking | Breaking |
| Data type change | Breaking | Breaking |
| Format change | Breaking | Breaking |
| Integer widens | Evolutionary | Breaking |
| Integer narrows | Breaking | Evolutionary |
| Add new value to enum | Evolutionary | Breaking |
| Remove value from enum | Breaking | Breaking |
| Optional to required | Breaking | Breaking |
| Required to optional | Evolutionary | Breaking |
| Property change | Input | Output |
|:----------------------------------|:--------------:|:--------------:|
| Remove a property | Breaking | Breaking |
| Add optional property | Evolutionary | Breaking |
| Add required property | Breaking | Breaking |
| Data type change | Breaking | Breaking |
| Format change | Breaking | Breaking |
| Integer widens | Evolutionary | Breaking |
| Integer narrows | Breaking | Evolutionary |
| Add new value to enum | Evolutionary | Breaking |
| Add new value to extensible enum | Evolutionary\* | Evolutionary\* |
| Remove value from enum | Breaking | Breaking |
| Remove value from extensible enum | Breaking | Evolutionary\* |
| Optional to required | Breaking | Breaking |
| Required to optional | Evolutionary | Breaking |

Changes marked with a \* are allowed without a version bump.

Breaking changes require prior approval of the Azure REST API review board and approval through the [Azure Global Breaking Change Policy][7]. In the case of deprecation, follow the [Azure Global Retirement Policy][7]. If the service is using SemVer for versioning, breaking changes constitute a major version change.

Expand All @@ -175,6 +180,7 @@ Evolutionary changes do not require prior approval (but still need a version bum
Because the API version represents a contract that a developer can rely on when generating SDKs to communicate with the service, there are a limited set of situations where changing the API is permissable without a version bump. The only changes universally allowed:

1. Adding a new (optional) value to an extensible enum.
2. Removing a value from an extensible enum in an output model.

An extensible enum is (in essence) a string. The values of the extensible enum drive intellisense and documentation, but the values are not considered exhaustive.

Expand Down Expand Up @@ -233,7 +239,9 @@ Service teams SHOULD prefer and recommend PATCH operations for updating resource

#### Use extensible enums

While removing a value from an enum is a breaking change, adding an enum can be handled with an _extensible enum_. An extensible enum is a string value that has been marked with a special marker - setting `modelAsString` to true within an `x-ms-enum` block. For example:
While removing a value from an enum is a breaking change, adding an enum can be handled with an _extensible enum_. An extensible enum is transmitted over the wire as a string, and contractually evolvable over time. As a developer, you can consider an extensible enum as a string property with some suggested values that are accepted by the service. The list of values provided within the extensible enum should not be considered exhaustive. They are there to provide hints for the user. For example, the values are used to assist with tab completion in command line tools.

adrianhall marked this conversation as resolved.
Show resolved Hide resolved
Within the swagger file, mark an extensible enum by setting `modelAsString` to true within an `x-ms-enum` block. For example:

```json
"createdByType": {
Expand Down