Skip to content

Commit d117061

Browse files
committed
Revise/improve guidance on api-version in Operation-Location
1 parent f3e08f2 commit d117061

File tree

1 file changed

+13
-5
lines changed

1 file changed

+13
-5
lines changed

azure/Guidelines.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -787,17 +787,21 @@ a [status monitor](https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.3)
787787

788788
:white_check_mark: **DO** generate an ID (typically a GUID) for the status monitor if the `Operation-Id` header was not passed by the client.
789789

790-
:white_check_mark: **DO** fail a request with a `400-BadRequest` if the `Operation-Id` header matches an outstanding operation unless the request is identical to the prior request (a retry scenario).
790+
:white_check_mark: **DO** fail a request with a `400-BadRequest` if the `Operation-Id` header matches an existing operation unless the request is identical to the prior request (a retry scenario).
791791

792792
:white_check_mark: **DO** perform as much validation as practical when initiating the operation to alert clients of errors early.
793793

794794
:white_check_mark: **DO** return a `202-Accepted` status code from the request that initiates an LRO if the processing of the operation was successfully initiated (except for "PUT with additional processing" type LRO).
795795

796796
:warning: **YOU SHOULD NOT** return any other `2xx` status code from the initial request of an LRO -- return `202-Accepted` and a status monitor even if processing was completed before the initiating request returns.
797797

798-
:ballot_box_with_check: **YOU SHOULD** include an `Operation-Location` header in the response with the absolute URL of the status monitor for the operation, but do not include an api-version query parameter.
798+
:white_check_mark: **DO** return a status monitor in the response body as described in [Obtaining status and results of long-running operations](#obtaining-status-and-results-of-long-running-operations).
799799

800-
:white_check_mark: **DO** return a status monitor in the response body as described in [Status and results of long-running operations](#status-and-results-of-long-running-operations).
800+
:ballot_box_with_check: **YOU SHOULD** include an `Operation-Location` header in the response with the absolute URL of the status monitor for the operation.
801+
802+
:ballot_box_with_check: **YOU SHOULD** include the `api-version` query parameter in the `Operation-Location` header with the same version passed on the initial request if it is required by the get operation on the status monitor.
803+
804+
:ballot_box_with_check: **YOU SHOULD** allow any valid value of the `api-version` query parameter to be used in the get operation on the status monitor.
801805

802806
#### PUT operation with additional long-running processing
803807

@@ -807,7 +811,7 @@ For a PUT (create or replace) with additional long-running processing:
807811

808812
:white_check_mark: **DO** generate an ID (typically a GUID) for the status monitor if the `Operation-Id` header was not passed by the client.
809813

810-
:white_check_mark: **DO** fail a request with a `400-BadRequest` if the `Operation-Id` header that matches an outstanding operation unless the request is identical to the prior request (a retry scenario).
814+
:white_check_mark: **DO** fail a request with a `400-BadRequest` if the `Operation-Id` header that matches an existing operation unless the request is identical to the prior request (a retry scenario).
811815

812816
:white_check_mark: **DO** perform as much validation as practical when initiating the operation to alert clients of errors early.
813817

@@ -817,7 +821,11 @@ For a PUT (create or replace) with additional long-running processing:
817821

818822
:white_check_mark: **DO** include response headers with any additional values needed for a GET request to the status monitor (e.g. location).
819823

820-
:ballot_box_with_check: **YOU SHOULD** include an `Operation-Location` header in the response with the absolute URL of the status monitor for the operation, but do not include an api-version query parameter.
824+
:ballot_box_with_check: **YOU SHOULD** include an `Operation-Location` header in the response with the absolute URL of the status monitor for the operation.
825+
826+
:ballot_box_with_check: **YOU SHOULD** include the `api-version` query parameter in the `Operation-Location` header with the same version passed on the initial request if it is required by the get operation on the status monitor.
827+
828+
:ballot_box_with_check: **YOU SHOULD** allow any valid value of the `api-version` query parameter to be used in the get operation on the status monitor.
821829

822830
#### Obtaining status and results of long-running operations
823831

0 commit comments

Comments
 (0)