Address comments in PR and working session on LRO guidelines

Author: mikekistler

azure/ConsiderationsForServiceDesign.md

@@ -6,7 +6,7 @@
 
 | Date        | Notes                                                          |
 | ----------- | -------------------------------------------------------------- |
-| 2022-May-20 | Update guidance on long-running operations                     |
+| 2022-Jun-08 | Update guidance on long-running operations                     |
 | 2022-Feb-01 | Updated error guidance                                        |
 | 2021-Sep-11 | Add long-running operations guidance                           |
 | 2021-Aug-06 | Updated Azure REST Guidelines per Azure API Stewardship Board. |
@@ -168,7 +168,7 @@ sequenceDiagram
     participant API Endpoint
     participant Status Monitor
     Client->>API Endpoint: POST/DELETE
-    API Endpoint->>Client: HTTP/1.1 202 Accepted<br/>Retry-After: 5<br/>{ "id": "22", "status": "NotStarted" }
+    API Endpoint->>Client: HTTP/1.1 202 Accepted<br/>{ "id": "22", "status": "NotStarted" }
     Client->>Status Monitor: GET
     Status Monitor->>Client: HTTP/1.1 200 OK<br/>Retry-After: 5<br/>{ "id": "22", "status": "Running" }
     Client->>Status Monitor: GET
@@ -177,7 +177,7 @@ sequenceDiagram
 
 1. The client sends the request to initiate the long-running operation.
 The initial request could be a POST or DELETE method.
-The request may contain an `operation-id` header that the service uses as the ID of the status monitor created for the operation.
+The request may contain an `Operation-Id` header that the service uses as the ID of the status monitor created for the operation.
 
 2. The service validates the request and initiates the operation processing.
 If there are any problems with the request, the service responds with a `4xx` status code and error response body.
@@ -199,25 +199,26 @@ If the operation is still being processed, the status field will contain a "non-
 
 5. After the operation processing completes, a GET request to the status monitor returns the status monitor with a status field set to a terminal value -- `Succeeded`, `Failed`, or `Canceled` -- that indicates the result of the operation.
 If the status is `Failed`, the status monitor resource contains an `error` field with a `code` and `message` that describes the failure.
-If the status is `Succeeded` and the LRO is an Action operation, the operation results will be returned in the `results` field of the status monitor.
+If the status is `Succeeded` and the LRO is an Action operation, the operation results will be returned in the `result` field of the status monitor.
 If the status is `Succeeded` and the LRO is an operation on a resource, the client can perform a GET on the resource
 to observe the result of the operation if desired.
 
 6. There may be some cases where a long-running operation can be completed before the response to the initial request.
 In these cases, the operation should still return a `202 Accepted` with the `status` property set to the appropriate terminal state.
 
-7. The service will auto-purge the status monitor resource after completion (at least 24 hours).
+7. The service is responsible for purging the status-monitor resource.
+It should auto-purge the status monitor resource after completion (at least 24 hours).
 The service may offer DELETE of the status monitor resource due to GDPR/privacy.
 
 ### Long-running Action Operations
 
 An action operation that is also long-running combines the [Action Operations](#action-operations) pattern
 with the [Long Running Operations](#long-running-operations) pattern.
 
-The operation is initiated with a POST operation and the operation path ends in `:action`.
+The operation is initiated with a POST operation and the operation path ends in `:<action>`.
 
 ```text
-POST /<service-or-resource-url>:action?api-version=2022-05-01
+POST /<service-or-resource-url>:<action>?api-version=2022-05-01
 Operation-Id: 22 
  
 { 
@@ -231,7 +232,6 @@ The response is a `202 Accepted` as described above.
 ```text
 HTTP/1.1 202 Accepted
 Operation-Location: https://<status-monitor-endpoint>/22
-Retry-After: 5 
  
 {
    "id": "22",
@@ -262,7 +262,7 @@ HTTP/1.1 200 OK
 A special case of long-running operation that occurs often is a PUT operation to create or replace a resource
 that involves some additional long-running processing.
 One example is a resource requires physical resources (e.g. servers) to be "provisioned" to make the resource functional.
-In this case, the request may contain an `operation-id` header that the service will use as
+In this case, the request may contain an `Operation-Id` header that the service will use as
 the ID of the status monitor created for the operation.
 
 ```text
@@ -314,7 +314,8 @@ HTTP/1.1 200 OK
 }
 ```
 
-If the additional processing failed, the service may delete the original resource if it is not usable in this state.
+If the additional processing failed, the service may delete the original resource if it is not usable in this state,
+but would have to clearly document this behavior.
 
 ### Long-running delete operation
 
@@ -328,7 +329,7 @@ When the delete operation completes successfully, a client must be able to creat
 ### Controlling a long-running operation
 
 It might be necessary to support some control action on a long-running operation, such as cancel.
-This is implemented as a POST on the status monitor endpoint with `:action` added.
+This is implemented as a POST on the status monitor endpoint with `:<action>` added.
 
 ```text
 POST /<status-monitor-url>:cancel?api-version=2022-05-01

azure/Guidelines.md

@@ -6,7 +6,7 @@
 
 | Date        | Notes                                                          |
 | ----------- | -------------------------------------------------------------- |
-| 2022-May-20 | Update guidance on long-running operations                     |
+| 2022-Jun-08 | Update guidance on long-running operations                     |
 | 2022-May-11 | Drop guidance on version discovery                             |
 | 2022-Mar-29 | Add guidelines about using durations                           |
 | 2022-Mar-25 | Update guideline for date values in headers to follow RFC 7231 |
@@ -765,14 +765,15 @@ Considerations for Service Design for an introduction to the design of long-runn
 
 :white_check_mark: **DO** implement an operation as an LRO if the 99th percentile response time is greater than 1s.
 
-:no_entry: **DO NOT** implement PATCH as an LRO.  If LRO update is required it should be implemented with POST.
+:no_entry: **DO NOT** implement PATCH as an LRO.  If LRO update is required it must be implemented with POST.
 
 In rare instances where an operation may take a _very long_ time to complete, e.g. longer than 15 minutes,
 it may be better to expose this as a first class resource of the API rather than as an operation on another resource.
 
 There are two basic patterns for long-running operations in Azure. The first pattern is used for a POST and DELETE
 operations that initiate the LRO. These return a `202 Accepted` response with a JSON status monitor in the response body.
 The second pattern applies only in the case of a PUT operation to create a resource that also involves additional long-running processing.
+For guidance on when to use a specific pattern, please refer to [Considerations for Service Design, Long Running Operations](./ConsiderationsForServiceDesign.md#long-running-operations).
 These are described in the following two sections.
 
 #### POST or DELETE LRO pattern
@@ -794,8 +795,6 @@ a [status monitor](https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.3)
 
 :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.
 
-:white_check_mark: **DO** include a `Retry-After` header in the response to the initiating request if the operation is not complete. The value of this header should be an integer number of seconds to wait before making the first request to the status monitor.
-
 :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.
 
 :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).
@@ -818,8 +817,6 @@ For a PUT (create or replace) with additional long-running processing:
 
 :white_check_mark: **DO** include response headers with any additional values needed for a GET request to the status monitor (e.g. location).
 
-:white_check_mark: **DO** include a `Retry-After` header in the response to the initiating request if the operation is not complete. The value of this header should be an integer number of seconds to wait before making the first request to the status monitor.
-
 :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.
 
 #### Obtaining status and results of long-running operations
@@ -835,18 +832,20 @@ For all long-running operations, the client will issue a GET on a status monitor
 Property | Type        | Required | Description
 -------- | ----------- | :------: | -----------
 `id`     | string      | true     | The unique id of the operation
-other    |             | true     | Other values needed for a GET request to the status monitor (e.g. location)
 `status` | string      | true     | enum that includes terminal values "Succeeded", "Failed", "Canceled"
 `error`  | ErrorDetail |          | Error object that describes the error when status is "Failed"
 `result` | object      |          | Only for POST action-type LRO, the results of the operation when completed successfully
+additional<br/>properties | |     | Additional named or dynamic properties of the operation
+
+:white_check_mark: **DO** include the `id` of the operation and any other values needed for the client to form a GET request to the status monitor (e.g. a `location` path parameter).
 
 :white_check_mark: **DO** include a `Retry-After` header in the response to GET requests to the status monitor if the operation is not complete. The value of this header should be an integer number of seconds to wait before making the next request to the status monitor.
 
 :white_check_mark: **DO** include the `result` property (if any) in the status monitor for a POST action-type long-running operation when the operation completes successfully.
 
 :no_entry: **DO NOT** include a `result` property in the status monitor for a long-running operation that is not a POST action-type long-running operation.
 
-:white_check_mark: **DO** retain the status monitor resource for some documented period of time (at least 24 hours) after the operation completes.
+:white_check_mark: **DO** retain the status monitor resource for some publicly documented period of time (at least 24 hours) after the operation completes.
 
 ### Bring your own Storage
 When implementing your service, it is very common to store and retrieve data and files. When you encounter this scenario, avoid implementing your own storage strategy and instead use Azure Bring Your Own Storage (BYOS). BYOS provides significant benefits to service implementors, e.g. security, an aggressively optimized frontend, uptime, etc.

azure/README.md

@@ -7,6 +7,6 @@ Designing powerful APIs with strong defaults, consistent behavior across related
 * [OpenAPI Style Guidelines](https://github.com/Azure/azure-api-style-guide/blob/main/README.md)
 * [Breaking Changes](http://aka.ms/AzBreakingChangesPolicy/) <sub>Note: Internal Microsoft link</sub>
 
-You can reach out to use via [email](mailto://[email protected]) or in our [Teams](https://teams.microsoft.com/l/team/19%3a3ebb18fded0e47938f998e196a52952f%40thread.tacv2/conversations?groupId=1a10b50c-e870-4fe0-8483-bf5542a8d2d8&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47) channel.
+You can reach out to us via [email](mailto://[email protected]) or in our [Teams](https://teams.microsoft.com/l/team/19%3a3ebb18fded0e47938f998e196a52952f%40thread.tacv2/conversations?groupId=1a10b50c-e870-4fe0-8483-bf5542a8d2d8&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47) channel.
 
 <sub>Note: The Teams channel is internal MS.</sup>