Potential alternative to the new "Operation-Location" header

[darrelmiller]

ref: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#1321-put

For long running operations that return 202, it is suggested to use Operation-Location to refer to a resource that can be monitored to determine when the requested operation is complete. Although, not explicitly specified by the HTTP spec, it is common practice to use the Location header to point to this status monitoring resource. See RFC7240 and RESTful Web Services Cookbook

It would seem prudent to follow common practice and avoid creating a new non-standard header for something that is commonly done.

For the hybrid scenario where the Location header is used to refer to the partially created resource and the Operation-Location header is used to point to the status resource, an alternative would be the following response:

HTTP/1.1 202 Accepted
Location: https://api.contoso.com/v1.0/operations/123
Content-Location: https://api.contoso.com/v1.0/databases/db1
{
  "databaseName": "db1",
  "color": "red",
  "Status": "Provisioning",
  [ … other fields for "database" …]
}

This approach is consistent with it's use of 202 to indicate that the creation process has not completed. It continues to use the Location header to indicate the location of the status monitoring resource. However, it also uses the Content-Location header to indicate that there is a response body that represents the current state of the resource being created and provides a URL to the final destination of the resource.

This approach provides equivalent functionality but doesn't require inventing a new header, it follows current common practices and it avoids having to impose the rules that the hybrid 201 must a have a body, and it must indicate that it is incomplete, and that 202 responses shouldn't return a body.

[garethj-msft]

I really like this proposal. I'm circulating it internally to see what reaction we have to changing to this as our preferred guidance.

[jmealo]

Any updates on this? (For what it's worth, I agree with the proposal.)

[darrelmiller]

I guess I should write a PR. /cc Thoughts? @garethj-msft @RobDolinMS @markdstafford

[freeranger]

@garethj-msft What was the internal reaction to this proposal?

[letmaik]

@darrelmiller @garethj-msft Could you please add a final statement and close issues and PRs that have been abandoned? If this issue is indeed still actively under discussion then a status update would be good.