Merge branch 'barcelona-mocks' of github.com:plone/plone.restapi into…

… barcelona-mocks
plone · May 22, 2016 · fc2b3b7 · fc2b3b7
2 parents a17b314 + 642e3d8
commit fc2b3b7
Show file tree

Hide file tree

Showing 14 changed files with 263 additions and 188 deletions.
diff --git a/docs/source/alert-noindex.rst b/docs/source/alert-noindex.rst
@@ -1,6 +1,3 @@
-.. meta::
-   :robots: noindex, nofollow
-
 .. warning::
    plone.restapi ist still in a pre-alpha stage.
    Any functionality described by this document might not be currently available on Plone, and/or might change significantly in the future.
diff --git a/docs/source/crud.rst b/docs/source/crud.rst
@@ -47,11 +47,12 @@ If we want to create a new document within an existing folder, we send a POST re
 
       requests.post('http://localhost:8080/Plone/folder', auth=('admin', 'admin'), headers={'Accept': 'application/json'}, params={'@type': 'Document'})
 
-By setting the 'Accept' header, we tell the server that we would like to recieve the response in the 'application/json' representation format.
+By setting the 'Accept' header, we tell the server that we would like to receive the response in the 'application/json' representation format.
 
 The 'Content-Type' header indicates that the body uses the 'application/json' format.
 
-The request body contains the necessary information that is needed to create a document (the type and the title).
+The request body contains the minimal necessary information needed to create a document (the type and the title).
+You could set other properties, like "description" here as well.
 
 
 Successful Response (201 Created)
@@ -247,9 +248,9 @@ A successful response to a PATCH request will be indicated by a :term:`204 No Co
 
   HTTP/1.1  204 No Content
 
-.. note::
 
-  `RFC 5789: PATCH Method for HTTP <http://tools.ietf.org/html/rfc5789>`_
+
+See for full specs the `RFC 5789: PATCH Method for HTTP <http://tools.ietf.org/html/rfc5789>`_
 
 
 Replacing a Resource with PUT
@@ -350,15 +351,13 @@ Possible server reponses for a PUT request are:
 POST vs. PUT
 ^^^^^^^^^^^^
 
-Difference POST and PUT:
+Difference between POST and PUT:
 
   * Use POST to create a resource identified by a service-generated URI
   * Use POST to append a resource to a collection identified by a service-generated URI
   * Use PUT to overwrite a resource
 
-.. note::
-
-  `RFC 7231: HTTP 1.1: PUT Method <https://tools.ietf.org/html/rfc7231#section-4.3.4>`_.
+This follows `RFC 7231: HTTP 1.1: PUT Method <https://tools.ietf.org/html/rfc7231#section-4.3.4>`_.
 
 
 Removing a Resource with DELETE

diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -6,4 +6,7 @@ Glossary
 	:sorted:
 
 	REST
-		REST stands for `Representational State Transfer <http://en.wikipedia.org/wiki/Representational_state_transfer>`_. It is a software architectural principle to create loosely coupled web APIs.
+		REST stands for `Representational State Transfer <http://en.wikipedia.org/wiki/Representational_state_transfer>`_. It is a software architectural principle to create loosely coupled web APIs.
+
+	workflow
+		A concept in Plone (and other CMS's) whereby a content object can be in a number of states (private, public, etcetera) and uses transitions to change between them (e.g. "publish", "approve", "reject", "retract"). See the `Plone docs on Workflow <http://docs.plone.org/working-with-content/collaboration-and-workflow/>`_
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -12,18 +12,20 @@ plone.restapi: A RESTful hypermedia API for Plone.
 Contents
 --------
 
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    introduction
+.. toctree::
+   :maxdepth: 2
+
    authentication
    crud
    workflow
    registry
    serialization
    searching
-   content-negotiation
-   types
    additional-endpoints
    customization
 
@@ -35,9 +37,9 @@ Appendix, Indices and tables
 
 .. toctree::
 
+   Available content types <types>
    http-status-codes
    glossary
 
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -1,70 +1,43 @@
 Introduction
 ============
 
-A hypermedia API just provides an entry point to the API that contains hyperlinks the clients can follow. Just like a human user of a regular website, that knows the initial URL of a website and then follows hyperlinks to navigate through the site. This has the advantage, that the client just needs to understand how to detect and follow links. The URL and other details of the API can change without breaking the client.
+A hypermedia API provides an entry point to the API, which contains hyperlinks the clients can follow.
+Just like a human user of a regular website, who knows the initial URL of a website and then follows hyperlinks to navigate through the site.
+This has the advantage that the client only needs to understand how to detect and follow links.
+The URLs (apart from the inital entry point) and other details of the API can change without breaking the client.
 
-The entry point to the Plone RESTful API is the portal root. The client can ask for a :term:`REST` API response by setting the 'Accept' HTTP header to 'application/json'::
+The entry point to the Plone RESTful API is the portal root.
+The client can ask for a :term:`REST` API response by setting the ``'Accept'`` HTTP header to ``'application/json'``::
 
   GET /
   Accept: application/json
 
-The server will then respond with the portal root in the JSON format:
-
-.. literalinclude:: _json/siteroot.json
-   :language: json-ld
 
-`@id` is a unique identifier for resources (IRIs). The @id property can be used to navigate through the web API by following the links.
+This uses so-called 'content negotiation'
 
-`@type` sets the data type of a node or typed value
-
-`member` is a list that contains all objects within that resource.
+  .. toctree::
+   :maxdepth: 1
 
-A client application can "follow" the links (by calling the @id property) to other resources. 
-This allows to build a losely coupled client that does not break if some of the URLs change, only the entry point of the entire API (in our case the portal root) needs to be known in advance.
-
-
-Plone Content
--------------
-
-Plone Portal Root:
-
-.. example-code::
-
-    .. code-block:: curl
+    More on Content Negotiation <content-negotiation>
 
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone Accept:application/json
-
-    .. code-block:: python-requests
-
-      requests.get('http://localhost:8080/Plone', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
+The server will then respond with the portal root in the JSON format:
 
 .. literalinclude:: _json/siteroot.json
    :language: json-ld
 
-Plone Folder:
-
-.. example-code::
-
-    .. code-block:: curl
-
-        curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/folder
-
-    .. code-block:: http-request
+`@id` is a unique identifier for resources (IRIs).
+The `@id` property can be used to navigate through the web API by following the links.
 
-        http GET http://localhost:8080/Plone/folder Accept:application/json
+`@type` sets the data type of a node or typed value
 
-    .. code-block:: python-requests
+`member` is a list that contains all objects within that resource.
 
-      requests.get('http://localhost:8080/Plone/folder', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
+A client application can "follow" the links (by calling the @id property) to other resources.
+This allows to build a losely coupled client that does not break if some of the URLs change, only the entry point of the entire API (in our case the portal root) needs to be known in advance.
 
-.. literalinclude:: _json/folder.json
-   :language: jsonld
+Another example, this time showing syntax in curl, as an http-request and how a python request would look like.
+Click on the buttons below to show the different syntaxes for the request.
 
-Plone Document:
 
 .. example-code::
 
@@ -83,116 +56,9 @@ Plone Document:
 .. literalinclude:: _json/document.json
    :language: jsonld
 
-News Item:
-
-.. example-code::
-
-    .. code-block:: curl
-
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/newsitem
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone/newsitem Accept:application/json
-
-    .. code-block:: python-requests
-
-      requests.get('http://localhost:8080/Plone/newsitem', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
-
-.. literalinclude:: _json/newsitem.json
-   :language: json-ld
-
-Event:
-
-.. example-code::
-
-    .. code-block:: curl
-
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/event
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone/event Accept:application/json
-
-    .. code-block:: python-requests
+And so on, see
 
-      requests.get('http://localhost:8080/Plone/event', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
+  .. toctree::
+   :maxdepth: 1
 
-.. literalinclude:: _json/event.json
-   :language: json-ld
-
-Image:
-
-.. example-code::
-
-    .. code-block:: curl
-
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/image
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone/image Accept:application/json
-
-    .. code-block:: python-requests
-
-      requests.get('http://localhost:8080/Plone/image', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
-
-.. literalinclude:: _json/image.json
-   :language: json-ld
-
-File:
-
-.. example-code::
-
-    .. code-block:: curl
-
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/file
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone/file Accept:application/json
-
-    .. code-block:: python-requests
-
-      requests.get('http://localhost:8080/Plone/file', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
-
-.. literalinclude:: _json/file.json
-   :language: json-ld
-
-Link:
-
-.. example-code::
-
-    .. code-block:: curl
-
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/link
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone/link Accept:application/json
-
-    .. code-block:: python-requests
-
-      requests.get('http://localhost:8080/Plone/link', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
-
-.. literalinclude:: _json/link.json
-   :language: json-ld
-
-Collection:
-
-.. example-code::
-
-    .. code-block:: curl
-
-      curl -i -H "Accept: application/json" -X GET http://localhost:8080/Plone/collection
-
-    .. code-block:: http-request
-
-      http GET http://localhost:8080/Plone/collection Accept:application/json
-
-    .. code-block:: python-requests
-
-      requests.get('http://localhost:8080/Plone/collection', auth=('admin', 'admin'), headers={'Accept': 'application/json'})
-
-.. literalinclude:: _json/collection.json
-   :language: json-ld
+     Representation of all standard Plone contenttypes<plone-content>