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

Repeatability Header clarification #439

Open
wants to merge 2 commits into
base: vNext
Choose a base branch
from
+3 −4
Open

Repeatability Header clarification #439

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d81151d
Repeatability Header clarification
markweitzel Mar 9, 2023
94797d7
Updated to add clarity on the guidelines.
markweitzel Mar 16, 2023
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
7 changes: 3 additions & 4 deletions azure/Guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -936,14 +936,13 @@ azure-deprecating: API version 2009-27-07 will retire on 2022-12-01 (https://azu
<a name="repeatability"></a>
### Repeatability of requests

The ability to retry failed requests for which a client never received a response greatly simplifies the ability to write resilient distributed applications. While HTTP designates some methods as safe and/or idempotent (and thus retryable), being able to retry other operations such as create-using-POST-to-collection is desirable.
Fault tolerant applications require that clients retry requests for which they never got a response and the service must handle these retried requests idmepotently. In Azure, all HTTP operations are naturally idempotent except for POST used to create a resource and [POST when used to invoke some RPC-like actions](https://github.com/microsoft/api-guidelines/blob/d81151d990b437b34dcf7d05d9504b754eb4f456/azure/Guidelines.md#performing-an-action).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tiny typo

Suggested change
Fault tolerant applications require that clients retry requests for which they never got a response and the service must handle these retried requests idmepotently. In Azure, all HTTP operations are naturally idempotent except for POST used to create a resource and [POST when used to invoke some RPC-like actions](https://github.com/microsoft/api-guidelines/blob/d81151d990b437b34dcf7d05d9504b754eb4f456/azure/Guidelines.md#performing-an-action).
Fault tolerant applications require that clients retry requests for which they never got a response and the service must handle these retried requests idempotently. In Azure, all HTTP operations are naturally idempotent except for POST used to create a resource and [POST when used to invoke some RPC-like actions](https://github.com/microsoft/api-guidelines/blob/d81151d990b437b34dcf7d05d9504b754eb4f456/azure/Guidelines.md#performing-an-action).


<a name="repeatability-headers"></a>
:ballot_box_with_check: **YOU SHOULD** support repeatable requests according as defined in [OASIS Repeatable Requests Version 1.0](https://docs.oasis-open.org/odata/repeatable-requests/v1.0/repeatable-requests-v1.0.html).

- The tracked time window (difference between the `Repeatability-First-Sent` value and the current time) **MUST** be at least 5 minutes.
- A service advertises support for repeatability requests by adding the `Repeatability-First-Sent` and `Repeatability-Request-ID` to the set of headers for a given operation.
- When understood, all endpoints co-located behind a DNS name **MUST** understand the header. This means that a service **MUST NOT** ignore the presence of a header for any endpoints behind the DNS name, but rather fail the request containing a `Repeatability-Request-ID` header if that particular endpoint lacks support for repeatable requests. Such partial support **SHOULD** be avoided due to the confusion it causes for clients.
- Document the `POST` operation's support for the `Repeatability-First-Sent` and `Repeatability-Request-ID` header in the API contract and documentation.
- All non-POST operations should ignore the headers if specified by the client.

<a name="lro"></a>
### Long-Running Operations & Jobs
Expand Down