Skip to content

Commit 2f9b246

Browse files
mikekistlerheaths
andauthored
Apply suggestions from PR review
Co-authored-by: Heath Stewart <[email protected]>
1 parent f635b34 commit 2f9b246

File tree

2 files changed

+2
-2
lines changed

2 files changed

+2
-2
lines changed

azure/ConsiderationsForServiceDesign.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ Before releasing your API plan to invest significant design effort, get customer
173173
As your service evolves over time, it will be natural that you want to remove operations that are no longer needed. For example, additional requirements or new capability in your service, may have resulted in a new operation that, effectively, replaces an old one.
174174
Azure has a well established breaking changes policy that describes how to approach these kinds of changes. As part of this policy, the service team is required to clearly communicate to customers when their API is changing, e.g. deprecating operations. Often, this is done via an email to the address that is attached to the Azure subscription.
175175

176-
However, given how many organizations are structured, it's common that this email address is different from the actual people writing code against your API. To address this, the service API should declare that it may return the `azure-deprecating` header, to indicate that this operation will be removed in the future. There is a simple string convention, specified in the [Azure REST API Guidelines](https://aka.ms/azapi/guidelines) that provides more information about the forthcoming deprecation.
176+
However, given how many organizations are structured, it's common that this email address is different from the actual people writing code against your API. To address this, the service API should declare that it may return the `azure-deprecating` header, to indicate that this operation will be removed in the future. There is a simple string convention, specified in the [Azure REST API Guidelines](https://aka.ms/azapi/guidelines#deprecating-behavior-notification) that provides more information about the forthcoming deprecation.
177177
This header is targeted at developers or operation professionals, and it is intended to give them enough information and lead time to properly adapt to this change. Your documentation should reference this header and encourage logging and alerting practices based on its presence.
178178

179179
## Avoid Surprises

azure/Guidelines.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1023,7 +1023,7 @@ Depending on the requirements of the service, there can be any number of "input"
10231023

10241024
The [HTTP Standard][] defines request headers that clients may use to specify a _precondition_
10251025
for execution of an operation. These headers allow clients to implement efficient caching mechanisms
1026-
and avoid data loss in the event of concurrent updates to a resource. The headers that specify conditional execution are "If-Match", "If-None-Match", "If-Modified-Since", "If-Unmodified-Since", and "If-Range".
1026+
and avoid data loss in the event of concurrent updates to a resource. The headers that specify conditional execution are `If-Match`, `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`, and `If-Range`.
10271027

10281028
[HTTP Standard]: https://datatracker.ietf.org/doc/html/rfc9110
10291029

0 commit comments

Comments
 (0)