Merge branch 'master' into barcelona-mocks

Conflicts: src/plone/restapi/tests/test_documentation.py
plone · May 16, 2016 · f9e2916 · f9e2916
2 parents 78c905c + 7fa90f4
commit f9e2916
Show file tree

Hide file tree

Showing 54 changed files with 560 additions and 1,811 deletions.
diff --git a/README.rst b/README.rst
@@ -80,6 +80,16 @@ Further Reading
 
 .. _`REST in Practice: Hypermedia and Systems Architecture (Webber, Parastatidis, Robinson)`: http://www.amazon.com/gp/product/0596805829
 
+Standards
+=========
+
+- JSON-LD: http://www.w3.org/TR/json-ld/
+- JSON Schema: http://json-schema.org/
+- Schema.org: http://schema.org/
+- Hydra: http://www.w3.org/ns/hydra/spec/latest/core/
+- Collection+JSON: http://amundsen.com/media-types/collection/
+- Siren: https://github.com/kevinswiber/siren
+
 License
 =======
 

diff --git a/base.cfg b/base.cfg
@@ -14,6 +14,7 @@ develop = .
 sources-dir = extras
 auto-checkout =
 #    plone.rest
+    sphinxcontrib-osexample
 
 [instance]
 recipe = plone.recipe.zope2instance
@@ -70,7 +71,9 @@ interpreter = ${buildout:directory}/bin/${sphinx-python:interpreter}
 
 [sphinx-python]
 recipe = zc.recipe.egg
-eggs = sphinxcontrib-httpdomain
+eggs = 
+    sphinxcontrib-httpdomain
+    sphinxcontrib-osexample
 interpreter = sphinxPython
 
 [deploy-to-heroku]
@@ -83,3 +86,4 @@ mode = 755
 
 [sources]
 plone.rest = git git://github.com/plone/plone.rest.git pushurl=git@github.com:plone/plone.rest.git branch=master
+sphinxcontrib-osexample = git https://github.com/svx/sphinxcontrib-osexample.git branch=plone
diff --git a/docs/source/_json/collection.json b/docs/source/_json/collection.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/collection", 
   "@type": "Collection", 
   "UID": "d0c89bc77f874ce1aad5720921d875c0", 

diff --git a/docs/source/_json/document.json b/docs/source/_json/document.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/front-page", 
   "@type": "Document", 
   "UID": "1f699ffa110e45afb1ba502f75f7ec33", 

diff --git a/docs/source/_json/event.json b/docs/source/_json/event.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/event", 
   "@type": "Event", 
   "UID": "846d632bc0854c5aa6d3dcae171ed2db", 

diff --git a/docs/source/_json/file.json b/docs/source/_json/file.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/file", 
   "@type": "File", 
   "UID": "9b6a4eadb9074dde97d86171bb332ae9", 

diff --git a/docs/source/_json/folder.json b/docs/source/_json/folder.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/folder", 
   "@type": "Folder", 
   "UID": "fc7881c46d61452db4177bc059d9dcb5", 

diff --git a/docs/source/_json/image.json b/docs/source/_json/image.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/image", 
   "@type": "Image", 
   "UID": "2166e81a0c224fe3b62e197c7fdc9c3e", 

diff --git a/docs/source/_json/link.json b/docs/source/_json/link.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/link", 
   "@type": "Link", 
   "UID": "6ff48d27762143a0ae8d63cee73d9fc2", 

diff --git a/docs/source/_json/newsitem.json b/docs/source/_json/newsitem.json
@@ -5,7 +5,6 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/newsitem", 
   "@type": "News Item", 
   "UID": "80c2a074cb4240d08c9a129e3a834c74", 

diff --git a/docs/source/_json/search.json b/docs/source/_json/search.json
@@ -5,13 +5,19 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "items_count": 1, 
+  "items_count": 2, 
   "member": [
     {
       "@id": "http://localhost:55001/plone/front-page", 
       "@type": "Document", 
       "description": "Congratulations! You have successfully installed Plone.", 
       "title": "Welcome to Plone"
+    }, 
+    {
+      "@id": "http://localhost:55001/plone/robot-test-folder", 
+      "@type": "Folder", 
+      "description": "", 
+      "title": "Test Folder"
     }
   ]
 }
diff --git a/docs/source/_json/siteroot.json b/docs/source/_json/siteroot.json
@@ -5,10 +5,15 @@ HTTP 200 OK
 content-type: application/json
 
 {
-  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone", 
   "@type": "Plone Site", 
   "member": [
+    {
+      "@id": "http://localhost:55001/plone/robot-test-folder", 
+      "@type": "Folder", 
+      "description": "", 
+      "title": "Test Folder"
+    }, 
     {
       "@id": "http://localhost:55001/plone/front-page", 
       "@type": "Document", 

diff --git a/docs/source/_json/workflow_get.json b/docs/source/_json/workflow_get.json
@@ -0,0 +1,27 @@
+GET /plone/front-page/workflow
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
+{
+  "history": [
+    {
+      "action": null, 
+      "actor": "test_user_1_", 
+      "comments": "", 
+      "review_state": "private", 
+      "time": "2016-05-16T13:42:42+00:00"
+    }
+  ], 
+  "transitions": [
+    {
+      "@id": "http://localhost:55001/plone/front-page/workflow/publish", 
+      "title": "Publish"
+    }, 
+    {
+      "@id": "http://localhost:55001/plone/front-page/workflow/submit", 
+      "title": "Submit for publication"
+    }
+  ]
+}
diff --git a/docs/source/_json/workflow_post.json b/docs/source/_json/workflow_post.json
@@ -0,0 +1,13 @@
+POST /plone/front-page/workflow/publish
+Accept: application/json
+
+HTTP 200 OK
+content-type: application/json
+
+{
+  "action": "publish", 
+  "actor": "admin", 
+  "comments": "", 
+  "review_state": "published", 
+  "time": "2016-05-16T13:42:42+00:00"
+}
diff --git a/docs/source/authentication.rst b/docs/source/authentication.rst
@@ -0,0 +1,40 @@
+==============
+Authentication
+==============
+
+``plone.restapi`` uses Plone PAS for Authentication.
+
+That means that any authentication method supported by an installed PAS Plugin
+should work, assuming it's an authentication method that makes sense to use
+with an API.
+
+For example, to authenticate using HTTP basic auth, you'd set an
+``Authorization`` header:
+
+.. code::
+
+  GET /Plone HTTP/1.1
+  Authorization: Basic Zm9vYmFyOmZvb2Jhcgo=
+  Accept: application/json
+
+HTTP client libraries usually contain helper functions to produce a proper
+``Authorization`` header for you based on given credentials.
+
+Using the ``requests`` library, you'd set up a session with basic auth like
+this:
+
+.. code:: python
+
+    import requests
+
+    session = requests.Session()
+    session.auth = ('username', 'password')
+    session.headers.update({'Accept': 'application/json'})
+
+    response = session.get(url)
+
+Or the same example using ``curl``:
+
+.. code:: python
+
+    curl -u username:password -H 'Accept:application/json' $URL