From 3ec748370d5bb28ccf2a509aa0e5af4e219bac00 Mon Sep 17 00:00:00 2001
From: EdLeafe <ed@leafe.com>
Date: Wed, 29 Mar 2017 19:24:07 +0000
Subject: [PATCH] Recommend the correct HTTP method for tags
The existing guideline recommends to do a GET on a tag to check its
existence, while our HTTP guideline recommends HEAD for such checks.
Since this is just a check, we should recommend HEAD in this case.
Wording was also added to the HTTP guideline stating that in all cases
where HEAD is implemented, the corresponding GET must be implemented,
too.
Closes-Bug #1677360
Change-Id: I36045e84e906dfbdf60c8989e2a5a5fb39b7cc34
---
guidelines/http.rst | 4 ++++
guidelines/tags.rst | 2 +-
2 files changed, 5 insertions(+), 1 deletion(-)
diff --git a/guidelines/http.rst b/guidelines/http.rst
index 0a56837..75d24e7 100644
--- a/guidelines/http.rst
+++ b/guidelines/http.rst
@@ -257,6 +257,10 @@ More generally, CRUD models the four basic functions of persistent
storage. An HTTP API is not solely a proxy for persistent storage.
It can provide access to such storage, but it can do much more.
+Please note that while HEAD is recommended for checking for the existence of a
+resource, the corresponding GET should always be implemented too, and should
+return an identical response with the addition of a body, if applicable.
+
**TODO**: HEAD is weird in a bunch of our wsgi frameworks and you
don't have access to it. Figure out if there is anything useful
there.
diff --git a/guidelines/tags.rst b/guidelines/tags.rst
index e7a22af..486966a 100644
--- a/guidelines/tags.rst
+++ b/guidelines/tags.rst
@@ -182,7 +182,7 @@ Response::
Location: http://example.com:8774/servers/1234567890/tags/qux
<no body>
-To check if a tag exists or not, the client should send a GET request to the
+To check if a tag exists or not, the client should send a HEAD request to the
individual tag URL. If the tag exists, the server responds with a status code
204 and no response body. If the tag does not exist, the server responds with
a status code 404.