HTTP Return Codes don't mention HTTP HEAD

[abatishchev]

See the table

api-guidelines/azure/Guidelines.md

Lines 142 to 154 in 0611d2f

	##### HTTP Return Codes
	<a href="#http-success-status-codes" name="http-success-status-codes">:white_check_mark:</a> **DO** adhere to the return codes in the following table when the method completes synchronously and is successful:
	Method | Description | Response Status Code
	-------|-------------|---------------------
	PATCH | Create/Modify the resource with JSON Merge Patch | `200-OK`, `201-Created`
	PUT | Create/Replace the _whole_ resource | `200-OK`, `201-Created`
	POST | Create new resource (ID set by service) | `201-Created` with URL of created resource
	POST | Action | `200-OK`
	GET | Read (i.e. list) a resource collection | `200-OK`
	GET | Read the resource | `200-OK`
	DELETE | Remove the resource | `204-No Content`\; avoid `404-Not Found`

It lists all HTTP verbs but HEAD. And overall, this verb isn't mentioned in the guidelines. Why?

[JeffreyRichter]

HEAD is so rarely used that we thought/hoped that we could avoid using it in new Azure services since GET is a superset of functionality.
We could add HEAD if there was a compelling reason to do so (we haven't found one yet).
We do try to make Azure simple for customers and therefore we only add things if there is a compelling enough reason to do so.

[abatishchev]

Since HEAD is a more lightweight way to check for a resource existence than GET, I think using it would benefit both the client and the server and everything in between.

The reason I'm asking is this (internal-only) issue: https://github.com/Azure/azure-resource-manager-rpc/issues/174 which talks about using HEAD in ARM.

[JeffreyRichter]

Checking for the existence of a resource has an inherent race condition in it in that the resource can exist and HEAD returns success but then the resource is DELETEd. We'd like to ensure that customers avoid writing code that may fail due to race conditions. Another way to make GET more "lightweight" would be for the resource to support etags or last-modified dates and then the GET can specify a conditional header (like If-Match or If-Modified-Since) and then there is also no need for HEAD.

[MushMal]

Can this item be resolved please? I think Jeffrey has a comprehensive response and we would like to not proliferate features that do not have clear and consistent benefits across the board for our customers.

[abatishchev]

I was about to follow up with @JeffreyRichter to discuss my disagreement with his argument.

HTTP HEAD is a part of HTTP RFC and supporting it benefits both Microsoft and its customers.

ARM is willing to add it to ARM RPC for the same reasons, I'm working with ARM Core and RPaaS on this, in my spare time.

[MushMal]

Understood. My stance on this is the "support" for a particular feature is somewhat different than having a prescriptive guidance in the API. The API guidance should cover the cases that are applicable to all/most service API design while not negating the fact that some services can choose to use a particular feature.

My recommendation is the following: If HTTP HEAD is prolific and/or is required by Azure services then we must follow-up with the guidance.

Jeffrey will certainly have more details on this.

[JeffreyRichter]

Just because HTTP offers HEAD, doesn't mean that Azure offers HEAD. There must be a great use case for HEAD for us to support it and for us to provide proper guidelines around it. All of our guidelines take many things into account such as race conditions, idempotency, atomicity, versioning, error handling, etc. For example, this is why our guidelines say that all DELETE methods must return 204 (never 200).

Do you have a great use case for HEAD with hero scenarios as to how & why customers are expected to use it?

[abatishchev]

Originally, I came to the guidance looking for an argument for adding HTTP HEAD to ARM, i.e. the control plane. But as Jeffrey explained to me, the guidance is for the data plane, so doesn't concern ARM. Hence the issue doesn't apply and can be closed.