Alternate long running operation strategy #101
Conversation
darrelmiller
changed the title
| @@ -1360,7 +1357,7 @@ POST https://api.contoso.com/v1.0/databases/ | |||
|
|
|||
| ```http | |||
| HTTP/1.1 202 Accepted | |||
| Operation-Location: https://api.contoso.com/v1.0/operations/123 | |||
| Location: https://api.contoso.com/v1.0/operations/123 | |||
There was a problem hiding this comment.
This is a breaking change. While I like the use of a standard header here, I don't think it meets the bar for a breaking change. Stability is a feature, in and of itself.
I know we considered the location header at the time we wrote these, but I don't recall why it was rejected.
There was a problem hiding this comment.
Isn't this part of why we adopted semantic versioning for the guidelines? Putting stability as the guiding priority means that we will grind forward progress to a halt. This is a positive change in the guidelines. It warrants a bump to version 3. As before, APIs are not required to make breaking changes just so they can adopt the new guidelines - but for new APIs, wouldn't we want the right baseline in place?
In my opinion, we should be putting additive changes into 2.x of the API guidelines, but not unnecessarily blocking a 3.x of the guidelines from being created. We could say that we haven't gathered sufficient breaking changes to warrant a 3.x at this point, but then I would ask where we plan to track those changes, and whether we can start on 3.x-preview1 even if we choose not to release 3.x until we do get to critical mass.
|
|
||
| The 202 Accepted should return no body. | ||
| The 201 Created case should return the body of the target resource. | ||
| For services that need to return a partially created response here, use the hybrid flow described below. |
| ``` | ||
|
|
||
| For services that need to return a 201 Created here, use the hybrid flow described below. | ||
|
|
||
| The 202 Accepted should return no body. |
There was a problem hiding this comment.
These requirements seem important. Not clear why they are removed.
There was a problem hiding this comment.
This PR proposes that a 202 also be used for the hybrid flow and during that scenario a partially created response is returned. Therefore saying that a body should not be returned with a 202 would be contradictory.
| HTTP/1.1 201 Created | ||
| Location: https://api.contoso.com/v1.0/databases/db1 | ||
| Operation-Location: https://api.contoso.com/v1.0/operations/123 | ||
| HTTP/1.1 202 Accepted |
There was a problem hiding this comment.
This is a breaking change.
| Location: https://api.contoso.com/v1.0/databases/db1 | ||
| Operation-Location: https://api.contoso.com/v1.0/operations/123 | ||
| HTTP/1.1 202 Accepted | ||
| Content-Location: https://api.contoso.com/v1.0/databases/db1 |
There was a problem hiding this comment.
This is actually scarier than a breaking change. You're changing the meaning of the location header, which means developers that aren't paying attention will be actively doing the wrong thing. The interaction of old+new code will be very unpredictable here.
There was a problem hiding this comment.
If I understand correctly, @darrelmiller is not changing the meaning of the Location header. He's pointing out that 201 Created is a misnomer when we are talking about asynchronous resource creation. A strict interpretation of HTTP would lead one to believe that the resource is done being created. In reality, the create request has been 202 Accepted, in which case the usage of Content-Location is additive to the examples we had before.
There was a problem hiding this comment.
The meaning of Location header is dependent on the response code. A 202 response code means the Location header points at the status monitor resource (what we call operation). A 201 status code means the Location points to the created resource. For 3xx status codes Location means something else.
Therefore because I'm also changing the status code that is returned for a hybrid flow, the meaning of Location header would be consistently the same as what Operation-Location currently means. Old client code talking to a new API would be missing the Operation-Location header in a 202 response and new client code talking to an old service would see a 201 created and not be aware that it is a hybrid flow LRO.
| @@ -1491,7 +1488,7 @@ Services MAY choose to delete tombstones after a service defined period of time. | |||
| #### 13.2.7 The typical flow, polling | |||
| - Client invokes a stepwise operation by invoking an action using POST | |||
| - The server MUST indicate the request has been started by responding with a 202 Accepted status code. The response SHOULD include the location header containing a URL that the client should poll for the results after waiting the number of seconds specified in the Retry-After header. | |||
| - Client polls the location until receiving a 200 OK response from the server. | |||
| - Client polls the location until receiving a response that indicates the stepwise long running operation is complete. | |||
|
Do we have any consensus on this? We are building a new API and were wondering if we should follow this new approach. |
|
If there's concern on a breaking change, why not introduce a header or some way for clients to opt-in to the alternative behavior? The approach suggested seems like it is in-line with how the HTTP spec defines using the 202 header. On a different note, did anyone consider submitting the new header to the IETF, in order to get some discussion around its introduction? |
Related to #10
This change removes the need for the custom header
Operation-Locationand uses the standardContent-Locationheader to enable the hybrid flow. This approach ensures that all long running operations use the standard 202 status code and Location header pattern. It also removes the need to prevent a body from being returned with a 202 response.