Fix content negotiation and create more verbose docs.

buildout.cfg

@@ -65,7 +65,9 @@ interpreter = ${buildout:directory}/bin/${sphinx-python:interpreter}
 
 [sphinx-python]
 recipe = zc.recipe.egg
-eggs = sphinx_rtd_theme
+eggs =
+    sphinx_rtd_theme
+    sphinxcontrib-httpdomain
 interpreter = sphinxPython
 
 [deploy-to-heroku]

docs/source/_json/collection.json

@@ -1,3 +1,9 @@
+GET /plone/collection
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/collection", 

docs/source/_json/document.json

@@ -1,3 +1,9 @@
+GET /plone/front-page
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/front-page", 

docs/source/_json/event.json

@@ -1,3 +1,9 @@
+GET /plone/event
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/event", 

docs/source/_json/file.json

@@ -1,3 +1,9 @@
+GET /plone/file/@@json
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/file", 

docs/source/_json/folder.json

@@ -1,3 +1,9 @@
+GET /plone/folder
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/folder", 

docs/source/_json/image.json

@@ -1,3 +1,9 @@
+GET /plone/image/@@json
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/image", 

docs/source/_json/link.json

@@ -1,3 +1,9 @@
+GET /plone/link
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/link", 

docs/source/_json/newsitem.json

@@ -1,3 +1,9 @@
+GET /plone/newsitem
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/newsitem", 

docs/source/_json/siteroot.json

@@ -1,3 +1,9 @@
+GET /plone
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
 {
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone", 

docs/source/conf.py

@@ -27,7 +27,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinxcontrib.httpdomain']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

src/plone/restapi/browser/traversal.py

@@ -18,7 +18,7 @@ def mark_as_api_request(context, event):
     """Mark views with application/json as Content-Type with the IAPIRequest
        interface.
     """
-    if event.request.getHeader('Content-Type') == 'application/json':
+    if event.request.getHeader('Accept') == 'application/json':
         alsoProvides(event.request, IAPIRequest)  # pragma: no cover
 
 

src/plone/restapi/tests/test_browser_traversal.py

@@ -70,14 +70,14 @@ def test_json_view_site_root_traversal(self):
     def test_document_traversal(self):
         response = requests.get(
             self.document_url,
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)
         self.assertEqual(
             response.headers.get('content-type'),
             'application/json',
-            'When sending a GET request with content-type: application/json ' +
+            'When sending a GET request with Accept: application/json ' +
             'the server should respond with sending back application/json.'
         )
         self.assertEqual(
@@ -97,7 +97,7 @@ def test_news_item_traversal(self):
         transaction.commit()
         response = requests.get(
             self.portal.news1.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)
@@ -123,7 +123,7 @@ def test_news_item_traversal(self):
     def test_folder_traversal(self):
         response = requests.get(
             self.folder_url,
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)
@@ -141,7 +141,7 @@ def test_folder_traversal(self):
     def test_site_root_traversal(self):
         response = requests.get(
             self.portal_url,
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)
@@ -162,7 +162,7 @@ def test_site_root_traversal_with_default_page(self):
         transaction.commit()
         response = requests.get(
             self.portal_url,
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)
@@ -196,7 +196,7 @@ def test_file_traversal(self):  # pragma: no cover
         transaction.commit()
         response = requests.get(
             self.portal.file1.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)
@@ -225,7 +225,7 @@ def test_image_traversal(self):  # pragma: no cover
         transaction.commit()
         response = requests.get(
             self.portal.img1.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         self.assertEqual(response.status_code, 200)

src/plone/restapi/tests/test_documentation.py

@@ -19,10 +19,32 @@
 import os
 import requests
 
+REQUEST_HEADER_KEYS = [
+    'accept'
+]
+
+RESPONSE_HEADER_KEYS = [
+    'content-type',
+    'allow',
+]
+
 
 def save_response_for_documentation(filename, response):
     f = open('../../docs/source/_json/%s' % filename, 'w')
-    f.write(response.text)
+    f.write('{} {}\n'.format(
+        response.request.method,
+        response.request.path_url
+    ))
+    for key, value in response.request.headers.items():
+        if key.lower() in REQUEST_HEADER_KEYS:
+            f.write('{}: {}\n'.format(key, value))
+    f.write('\n')
+    f.write('HTTP {} {}\n'.format(response.status_code, response.reason))
+    for key, value in response.headers.items():
+        if key.lower() in RESPONSE_HEADER_KEYS:
+            f.write('{}: {}\n'.format(key, value))
+    f.write('\n')
+    f.write(response.content)
     f.close()
 
 
@@ -61,7 +83,7 @@ def setUp(self):
     def test_documentation_document(self):
         response = requests.get(
             self.document.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('document.json', response)
@@ -86,7 +108,7 @@ def test_documentation_news_item(self):
         transaction.commit()
         response = requests.get(
             self.portal.newsitem.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('newsitem.json', response)
@@ -101,7 +123,7 @@ def test_documentation_event(self):
         transaction.commit()
         response = requests.get(
             self.portal.event.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('event.json', response)
@@ -115,7 +137,7 @@ def test_documentation_link(self):
         transaction.commit()
         response = requests.get(
             self.portal.link.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('link.json', response)
@@ -141,7 +163,7 @@ def test_documentation_file(self):
         # soon as this has been fixed.
         response = requests.get(
             self.portal.file.absolute_url() + '/@@json',
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('file.json', response)
@@ -162,7 +184,7 @@ def test_documentation_image(self):
         # soon as this has been fixed.
         response = requests.get(
             self.portal.image.absolute_url() + '/@@json',
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('image.json', response)
@@ -185,7 +207,7 @@ def test_documentation_folder(self):
         transaction.commit()
         response = requests.get(
             self.portal.folder.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('folder.json', response)
@@ -214,15 +236,15 @@ def test_documentation_collection(self):
         transaction.commit()
         response = requests.get(
             self.portal.collection.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('collection.json', response)
 
     def test_documentation_siteroot(self):
         response = requests.get(
             self.portal.absolute_url(),
-            headers={'content-type': 'application/json'},
+            headers={'Accept': 'application/json'},
             auth=(SITE_OWNER_NAME, SITE_OWNER_PASSWORD)
         )
         save_response_for_documentation('siteroot.json', response)