ChangeIntelIT change radar
Public mode

No access to your tenant or devices. Every item links to its source. What this means

Some sources or documents need attention: 258/260 feeds/APIs · 416/439 docs · checked 19:52 UTC Customize Public modeDiscuss ChangeIntel on Discord

Graph versioning and breaking-change policy

This page's changes and edits · All guidance changes

Microsoft's edit ·

Fixed Acrolinx issues commit 1

Microsoft's commit message in microsoftgraph/microsoft-graph-docs-contrib · commit 2c747de · +11 −11 lines · also on GitHub

⋯ 13 unchanged lines
1414
1515 As new versions of the Microsoft Graph REST APIs and Microsoft Graph SDKs are released, earlier versions will be retired. Microsoft declares a version as deprecated at least 24 months in advance of retiring it. Similarly, for individual APIs that are generally available (GA), Microsoft declares an API as deprecated at least 24 months in advance of removing it from the GA version.
1616
17 −When we increment the major version of the API (for example, from v1.0 to v2.0), we are announcing that the current version (in this example, v1.0) is immediately deprecated and we will no longer support it 24 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.
17 +When we increment the major version of the API (for example, from v1.0 to v2.0), we're announcing that the current version (in this example, v1.0) is immediately deprecated and we'll no longer support it 24 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.
1818
19 −When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. In some cases, we will announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated. In those cases, only active applications that currently use the deprecated APIs can continue to use them.
19 +When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. In some cases, we'll announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated. In those cases, only active applications that currently use the deprecated APIs can continue to use them.
2020
21 −### API contract and non-backward compatible changes
21 +### API contract and nonbackward compatible changes
2222
23 −Microsoft Graph has a log of changes across versions. These changes are listed in the [Microsoft Graph Changelog](changelog.md). As new functionality and data is added to Microsoft Graph, we will increment the API version number for any non-backward compatible changes to the API.
23 +Microsoft Graph has a log of changes across versions. These changes are listed in the [Microsoft Graph Changelog](changelog.md). As new functionality and data are added to Microsoft Graph, we'll increment the API version number for any nonbackward compatible changes to the API.
2424
25 −The following are examples of non-backward compatible changes:
25 +The following are examples of nonbackward compatible changes:
2626
2727 - Changes to the URL or fundamental request/response associated with a resource
2828 - Removal, rename, or change to the type of a declared property
⋯ 18 unchanged lines
4747 The following versions of the Microsoft Graph API are currently available.
4848
4949 ### Beta version
50 −In general, APIs debut in the beta version and are accessible in the `https://graph.microsoft.com/beta` endpoint. For beta API documentation, see [Microsoft Graph beta endpoint reference](/graph/api/overview?view=graph-rest-beta&preserve-view=true). Expect breaking changes and deprecation of APIs in the beta version from time to time. Do not take a production dependency on beta APIs.
50 +In general, APIs debut in the beta version and are accessible in the `https://graph.microsoft.com/beta` endpoint. For beta API documentation, see [Microsoft Graph beta endpoint reference](/graph/api/overview?view=graph-rest-beta&preserve-view=true). Expect breaking changes and deprecation of APIs in the beta version from time to time. Don't take a production dependency on beta APIs.
5151
52 −We make no guarantees that a beta feature will be promoted to the current version. When the Microsoft Graph API team believes that a beta feature is ready for general availability, we will add that feature to the latest current version. If the promotion of the feature would result in a breaking change to the current version, the version number will be incremented, with the new version becoming the current version.
53 −Our developer community can post feature requests on the [Microsoft 365 Developer Platform ideas forum](https://techcommunity.microsoft.com/t5/microsoft-365-developer-platform/idb-p/Microsoft365DeveloperPlatform/label-name/Microsoft%20Graph), including requests for new features as well as requests to promote existing beta APIs to the current version.
52 +We make no guarantees that a beta feature will be promoted to the current version. When the Microsoft Graph API team believes that a beta feature is ready for general availability, we'll add that feature to the latest current version. If the promotion of the feature would result in a breaking change to the current version, the version number is incremented, with the new version becoming the current version.
53 +Our developer community can post feature requests on the [Microsoft 365 Developer Platform ideas forum](https://techcommunity.microsoft.com/t5/microsoft-365-developer-platform/idb-p/Microsoft365DeveloperPlatform/label-name/Microsoft%20Graph), including requests for new features and requests to promote existing beta APIs to the current version.
5454
5555 ### Current version
5656
5757 The current version of Microsoft Graph is v1.0. Exposed under `https://graph.microsoft.com/v1.0`, the Microsoft Graph API v1.0 version contains features that are generally available and ready for production use. Browse the [documentation for the v1.0 APIs](/graph/api/overview?view=graph-rest-1.0&preserve-view=true).
5858
5959 ## Preview status
60 −An API or feature in Microsoft Graph is labelled as "(preview)" to indicate its behavior is _unique_ in the beta endpoint.
60 +An API or feature in Microsoft Graph is labeled as "(preview)" to indicate its behavior is _unique_ in the beta endpoint.
6161
6262 The behavior of most APIs and features in the v1.0 version is in parity with the beta version. "preview" qualifies a minority of APIs and features in one of the following two cases:
6363 - Available in only beta
6464 - Available in beta differently than in v1.0
6565
66 −Like any other API in the beta endpoint, APIs marked in the documentation as "(preview)" may experience breaking changes without notice. Do not access APIs from the beta endpoint in production apps.
66 +Like any other API in the beta endpoint, APIs marked in the documentation as "(preview)" may experience breaking changes without notice. Don't access APIs from the beta endpoint in production apps.
6767
68 −As an example, [attack simulation training](/microsoft-365/security/office-365-security/attack-simulation-training?view=o365-worldwide&preserve-view=true) is a feature that has been generally available for administrators in the [Microsoft 365 Defender portal](https://security.microsoft.com/). When the REST API for attack simulation training becomes available in Microsoft Graph in only the beta endpoint, the REST API [documentation](/graph/api/resources/security-api-overview?view=graph-rest-beta&preserve-view=true#attack-simulation-and-training-preview) is labelled as "(preview)". The "(preview)" label applies to the REST API and its documentation in Microsoft Graph, even though the service itself is generally available.
68 +As an example, [attack simulation training](/microsoft-365/security/office-365-security/attack-simulation-training?view=o365-worldwide&preserve-view=true) is a feature that has been generally available for administrators in the [Microsoft 365 Defender portal](https://security.microsoft.com/). When the REST API for attack simulation training becomes available in Microsoft Graph in only the beta endpoint, the REST API [documentation](/graph/api/resources/security-api-overview?view=graph-rest-beta&preserve-view=true#attack-simulation-and-training-preview) is labeled as "(preview)". The "(preview)" label applies to the REST API and its documentation in Microsoft Graph, even though the service itself is generally available.
6969
7070 ### Deprecated and unsupported versions
7171
⋯ 7 unchanged lines

Microsoft's Markdown source from microsoftgraph/microsoft-graph-docs-contrib, © Microsoft Corporation, under CC BY 4.0. Changed lines with up to 3 unchanged lines around each; ChangeIntel kept this copy 10 Oct 09:39 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.

ChangeIntel

An IT change radar: releases, security, known issues, retirements, documentation changes, and service status from public sources. Every item links to supporting evidence; dates and statuses can change after they are read.

Sources read 20 Oct 19:52 UTC · 258 of 260 readable · 256 fully read · documentation 416/439 current

No accounts or analytics; your preferences stay in your browser. Information, not advice. ChangeIntel is an independent tool and is not affiliated with or endorsed by Microsoft, Apple, Google, Broadcom (VMware), Jamf, Oracle, Mozilla, or any other vendor it covers. Product names are trademarks of their owners. Built by Evotec.