Add content negotiation docs.

plone · Jul 11, 2015 · 0579f5a · 0579f5a
1 parent 79e5bb7
commit 0579f5a
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 0 deletions.
diff --git a/docs/source/content-negotiation.rst b/docs/source/content-negotiation.rst
@@ -0,0 +1,23 @@
+Content Negotiation
+===================
+
+`Content negotiation`_ is a mechanism defined in the `HTTP specification`_ that makes it possible to serve different versions of a document (or more generally, a resource representation) at the same URI, so that user agents can specify which version fit their capabilities the best.
+
+The user agent (or the REST consumer) can ask for a specific representation by providing an Accept HTTP header that lists acceptable media types (e.g. JSON)::
+
+  GET /
+  Accept: application/json
+
+The server is then able to supply the version of the resource that best fits the user agent's needs. This is reflected in the Content-Type header::
+
+  HTTP 200 OK
+  Content-Type: application/json
+
+  {
+    'data': ...
+  }
+
+.. _`Content negotiation`: http://tools.ietf.org/html/rfc7231#section-5.3
+
+.. _`HTTP specification`: http://tools.ietf.org/html/rfc7231
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,6 +16,7 @@ Contents
    :maxdepth: 3
 
    introduction
+   content-negotiation
 
 ..   hydra
 ..   item