plone.rest 1.0a4

Purpose

plone.rest allows you to use HTTP verbs such as GET, POST, PUT, DELETE, etc. in Plone.

REST stands for Representational State Transfer. It is a software architectural principle to create loosely coupled web APIs.

plone.rest provides the basic infrastructure that allows us to build RESTful endpoints in Plone.

The reason for separating this infrastructure into a separate package from the ‘main’ full Plone REST API is so you can create alternative endpoints tailored to specific usecases. A number of these specific endpoints are already in active use.

Audience

plone.rest is for experienced web developers who want to build their own HTTP/REST endpoints on top of Plone.

If you want to use a ready-made full RESTful Plone API, you should use plone.restapi. That package uses, and depends upon, this one.

Features

• Registering RESTful service endpoints for the following HTTP verbs:

  • GET

  • POST

  • PUT

  • DELETE

  • PATCH

  • OPTIONS

• Support for Dexterity and Archetypes-based content objects

• Content negotiation: Services can be registered for arbitrary media types (e.g. ‘application/json’).

• Named services allows to register service endpoints for custom URLs

Registering RESTful Service Endpoints

plone.rest allows you to register HTTP verbs for Plone content with ZCML.

This is how you would register a PATCH request on Dexterity content:

<plone:service
  method="PATCH"
  accept="application/json"
  for="plone.dexterity.interfaces.IDexterityContent"
  factory=".service.Patch"
  />

You have to specify the HTTP verb (GET, POST, PUT, DELETE, HEAD, OPTIONS), the media type used for content negotiation, the interface for the content objects and the factory class that actually returns the content.

The factory class needs to inherit from the plone.rest ‘Service’ class and to implement a render method that returns a list or a dict:

from plone.rest import Service

class Patch(Service):

    def render(self):
        return {'message': 'PATCH: Hello World!'}

The return value (list or dict) will be automatically transformed into JSON.

Content Negotiation

To access the service endpoint we just created we have to send a GET request to a Dexterity object by setting the ‘Accept’ header to ‘application/json’:

PATCH /Plone/doc1 HTTP/1.1
Host: localhost:8080
Accept: application/json

The server then will respond with ‘200 OK’:

HTTP/1.1 200 OK
Content-Type: application/json

{
  'message': 'PATCH: Hello World!'
}

You can try this out on the command line:

$ http --auth admin:admin PATCH localhost:8080/Plone/doc1 Accept:application/json

Here is a list of examples for all supported HTTP verbs:

GET:

$ http --auth admin:admin GET localhost:8080/Plone/doc1 Accept:application/json

POST:

$ http --auth admin:admin POST localhost:8080/Plone/doc1 Accept:application/json

PUT:

$ http --auth admin:admin PUT localhost:8080/Plone/doc1 Accept:application/json

DELETE:

$ http --auth admin:admin DELETE localhost:8080/Plone/doc1 Accept:application/json

PATCH:

$ http --auth admin:admin PATCH localhost:8080/Plone/doc1 Accept:application/json

OPTIONS:

$ http --auth admin:admin OPTIONS localhost:8080/Plone/doc1 Accept:application/json

Named Services

Named services can be registered by providing a ‘name’ attribute in the service directive:

<plone:service
  method="GET"
  accept="application/json"
  for="Products.CMFPlone.interfaces.IPloneSiteRoot"
  factory=".service.Search"
  name="search"
  />

This registers a service endpoint accessible at the site root using the following request:

GET /Plone/search HTTP/1.1
Host: localhost:8080
Accept: application/json

Installation

Install plone.rest by adding it to your buildout:

[buildout]

 ...

 eggs =
     plone.rest

and then running “bin/buildout”

Contribute

• Issue Tracker: https://github.com/plone/plone.rest/issues

• Source Code: https://github.com/plone/plone.rest

• Documentation: https://pypi-hypernode.com/pypi/plone.rest

Support

This package is maintained by Timo Stollenwerk <tisto@plone.org> and Ramon Navarro Bosch <ramon.nb@gmail.com>.

If you are having issues, please let us know.

License

The project is licensed under the GPLv2.

1.0a4 (2016-02-07)

• Refactor Dexterity tests to make sure services return the correct object. [timo]

• Add support for browser layers. REST services can now be registered to a specific browser layer using the ‘layer’ attribute. [buchi]

• Remove request method specific marker interfaces (IGET, IPOST, etc.) because they’re no longer required for service lookup. [buchi]

• Add support for content negotiation. REST services are no longer hardwired to ‘application/json’ Accept headers. Instead the media type can be configured with the service directive. [buchi]

• Refactor traversal of REST requests by using a traversal adapter on the site root instead of a traversal adapter for each REST service. This prevents REST services from being overriden by other traversal adapters. [buchi]

1.0a3 (2015-12-16)

• Release fix. 1.0a2 was a brown-bag release. This fixes https://github.com/plone/plone.rest/issues/34. [timo]

1.0a2 (2015-12-10)

• Simplify patch of DynamicType pre-traversal hook and actually make it work with Archetypes. [buchi]

• Render errors as JSON. [jone]

• Add support for named services which allows registering services like GET /Plone/search or GET /Plone/doc1/versions/1 using a ‘name’ attribute. [jone, lukasgraf, buchi]

• Remove “layer” from service directive for now, because it is not yet implemented properly. [jone]

1.0a1 (2015-08-01)

• Initial release. [bloodbare, timo]