Skip to content

Commit fdef09f

Browse files
committed
Versioning clarificattion
1 parent fb3438e commit fdef09f

File tree

1 file changed

+3
-4
lines changed

1 file changed

+3
-4
lines changed

graph/GuidelinesGraph.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ Guidelines](https://github.com/microsoft/api-guidelines/blob/master/Guidelines.m
182182
|----------------------------------------------------------------------------------------------------|
183183
| :heavy_check_mark: **MUST** support \$select on resource to enable properties projection |
184184
| :ballot_box_with_check: **SHOULD** support \$filter with eq, ne operations on properties of entities for collections|
185-
| :heavy_check_mark: **MUST** support server-side pagination for large collections |
185+
| :heavy_check_mark: **MUST** support server-side pagination for collections |
186186
| :ballot_box_with_check: **SHOULD** support pagination $top, $skip and $count for collections |
187187

188188
The query options part of an OData URL can be quite long, potentially exceeding
@@ -393,10 +393,9 @@ breaking change.
393393

394394
### Versioning and Deprecation
395395
As the market and technology evolves your APIs will require modifications in this case you must avoid breaking changes and add new resources and features incrementally. If that is not possible then you must version elements of your APIs.
396-
Microsoft Graph allows versioning of elements including entities and properties. The versioning process goes along with deprecation and as soon as you introduce a new element update the previous version needs to follow the deprecation process.
396+
Microsoft Graph allows versioning of elements including entities and properties. Versioning involves adding a new, uniquely named version of the element and marking the old version as deprecated.
397397

398-
You must create a new version of your element for any breaking change and name it uniquely.
399-
In some cases, the API will have evolved such that there is a new, natural unique name. In other cases, the original name may still be the most descriptive for the evolved element. In the latter case, the suffix _v2 must be added to the original name to make it unique.
398+
In some cases, there will be a natural new name for the element. In other cases, where the original name is still the most descriptive, the suffix _v2 can be added to the original name to make it unique.
400399
The original element is then marked as deprecated using annotations.
401400

402401
Microsoft Graph provides two public endpoints to support API lifecycle:

0 commit comments

Comments
 (0)