.. image:: https://github.com/plone/plone.rest/actions/workflows/tests.yml/badge.svg
:alt: Github Actions Status
:target: https://github.com/plone/plone.rest/actions/workflows/tests.yml
.. image:: https://img.shields.io/coveralls/github/plone/plone.rest.svg
:alt: Coveralls github
:target: https://coveralls.io/github/plone/plone.restapi
.. image:: https://img.shields.io/pypi/status/plone.rest.svg
:target: https://pypi.org/project/plone.rest/
:alt: Egg Status
.. image:: https://img.shields.io/pypi/v/plone.rest.svg
:target: https://pypi.org/project/plone.rest/
:alt: Latest Version
.. image:: https://img.shields.io/pypi/l/plone.rest.svg
:target: https://pypi.org/project/plone.rest/
:alt: License
==========
Plone REST
==========
Purpose
-------
plone.rest allows you to use HTTP verbs such as GET, POST, PUT, DELETE, etc. in `Plone <https://www.plone.org>`_.
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.
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 <https://github.com/plone/plone.restapi>`_ 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 <https://github.com/plone/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:
.. code-block:: XML
<plone:service
method="PATCH"
accept="application/json"
for="plone.dexterity.interfaces.IDexterityContent"
factory=".service.Patch"
permission="cmf.ModifyPortalContent"
/>
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,
the factory class that actually returns the content and the permission required
to access the service.
The factory class needs to inherit from the plone.rest 'Service' class and to implement a render method that returns the body of the response::
from plone.rest import Service
class Patch(Service):
def render(self):
return '{"message": "PATCH: Hello World!"}'
Content Negotiation
-------------------
To access the service endpoint we created we have to send a GET request to a Dexterity object:
1. by setting the 'Accept' header to 'application/json'::
PATCH /Plone/doc1 HTTP/1.1
Host: localhost:8080
Accept: application/json
2. or by adding an explicit traversal step to the path like so::
PATCH /Plone/++api++/doc1 HTTP/1.1
Host: localhost:8080
The server then will respond with '200 OK'::
HTTP/1.1 200 OK
Content-Type: application/json
{
"message": "PATCH: Hello World!"
}
Why two methods?
Using the 'Accept' header is the intended way of RESTful APIs to get different responses from the same URL.
However, if it comes to caching the response in an web accelerator like Varnish or Cloudflare, additional challenges are added.
Setting the `Vary` header to 'Vary: Accept' helps to a certain degree in Varnish.
But cache pollution may happen, because different browsers send different headers on normal HTML requests.
Hosted services like Cloudflare just do not support the 'Vary' usage and can not be used for sites with REST calls.
Thus a second option with different URLs is needed.
You can try this out on the command line:
.. code-block:: console
$ http --auth admin:admin PATCH localhost:8080/Plone/doc1 Accept:application/json
.. note:: You have to install httpie (pip install httpie) to make this example work.
Here is a list of examples for all supported HTTP verbs:
GET::
$ http --auth admin:admin GET localhost:8080/Plone/doc1 Accept:application/json
$ http --auth admin:admin GET localhost:8080/Plone/++api++/doc1
POST::
$ http --auth admin:admin POST localhost:8080/Plone/doc1 Accept:application/json
$ http --auth admin:admin POST localhost:8080/Plone/++api++/doc1
PUT::
$ http --auth admin:admin PUT localhost:8080/Plone/doc1 Accept:application/json
$ http --auth admin:admin PUT localhost:8080/Plone/++api++/doc1
DELETE::
$ http --auth admin:admin DELETE localhost:8080/Plone/doc1 Accept:application/json
$ http --auth admin:admin DELETE localhost:8080/Plone/++api++/doc1
PATCH::
$ http --auth admin:admin PATCH localhost:8080/Plone/doc1 Accept:application/json
$ http --auth admin:admin PATCH localhost:8080/Plone/++api++/doc1
OPTIONS::
$ http --auth admin:admin OPTIONS localhost:8080/Plone/doc1 Accept:application/json
$ http --auth admin:admin OPTIONS localhost:8080/Plone/++api++/doc1
Named Services
--------------
Named services can be registered by providing a 'name' attribute in the service directive:
.. code-block:: XML
<plone:service
method="GET"
accept="application/json"
for="Products.CMFPlone.interfaces.IPloneSiteRoot"
factory=".service.Search"
name="search"
permission="zope2.View"
/>
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
Service endpoints can also be accessed using the traverser::
GET /Plone/++api++/search HTTP/1.1
Host: localhost:8080
Additional Path Segments
------------------------
To handle additional path segments after the service url like `/Plone/myservice/1/2`
a service has to implement `IPublishTraverse`. The following example simply
stores all path segments in an array in `self.params`.
.. code-block:: python
from plone.rest import Service
from zope.interface import implementer
from zope.publisher.interfaces import IPublishTraverse
@implementer(IPublishTraverse)
class MyService(Service):
def __init__(self, context, request):
super(MyService, self).__init__(context, request)
self.params = []
def publishTraverse(self, request, name):
self.params.append(name)
return self
def render(self):
return {'service': 'named get', 'params': self.params}
See also the implementation of the workflow transition endpoint in
plone.restapi for an other example.
CORS
----
plone.rest allows you to define CORS policies for services in ZCML. The
following example defines a policy for all services.
.. code-block:: XML
<plone:CORSPolicy
allow_origin="http://example.net"
allow_methods="DELETE,GET,OPTIONS,PATCH,POST,PUT"
allow_credentials="true"
expose_headers="Content-Length,X-My-Header"
allow_headers="Accept,Authorization,Content-Type,X-Custom-Header"
max_age="3600"
/>
CORS policies can be bound to specific interfaces of content objects and to
specific browser layers. This allows us to define different policies for
different content types or to override existing policies. The following example
defines a policy for the site root.
.. code-block:: XML
<plone:CORSPolicy
for="Products.CMFPlone.interfaces.IPloneSiteRoot"
layer="myproduct.interfaces.IMyBrowserLayer"
allow_origin="*"
allow_methods="GET"
/>
The CORSPolicy directive supports the following options:
allow_origin
Origins that are allowed to access the resource. Either a comma separated
list of origins, e.g. "http://example.net,http://mydomain.com" or "*".
allow_methods
A comma separated list of HTTP method names that are allowed by this CORS
policy, e.g. "DELETE,GET,OPTIONS,PATCH,POST,PUT". If not specified, all
methods for which there's a service registered are allowed.
allow_credentials
Indicates whether the resource supports user credentials in the request.
allow_headers
A comma separated list of request headers allowed to be sent by the client,
e.g. "X-My-Header"
expose_headers
A comma separated list of response headers clients can access,
e.g. "Content-Length,X-My-Header".
max_age
Indicates how long the results of a preflight request can be cached.
for
Specifies the interface for which the CORS policy is registered. If this
attribute is not specified, the CORS policy applies to all objects.
layer
A browser layer for which this CORS policy is registered. Useful for
overriding existing policies or for making them available only if a specific
add-on has been installed.
Installation
------------
Install plone.rest by adding it to your buildout::
[buildout]
...
eggs =
plone.rest
and then running "bin/buildout"
Plone/Python Support
--------------------
plone.rest 4.x.x supports Plone 5.2 and 6.x on Python 3.8 and newer.
plone.rest 3.x.x supports Plone 5.2 on Python 2.7 and 3.6 to 3.8 and Plone 6.0 on Python 3.8 to 3.11.
If you need to use Plone 4.3, 5.0, or 5.1 on Python 2.7, check out plone.rest 2.x.x or 1.x.x.
Redirects
---------
plone.rest will handle redirects created by ``plone.app.redirector`` pretty
much the same way as regular Plone.
If a redirect exists for a given URL, a ``GET`` request will be answered with
``302``, and the new location for the resource is indicated in the ``Location``
header::
HTTP/1.1 302 Moved Temporarily
Content-Type: application/json
Location: http://localhost:8080/Plone/my-folder-new-location
Any other request method than GET (``POST``, ``PATCH``, ...) will be answered
with ``307 Temporary Redirect``. This status code instructs the client that
it should NOT switch the method, but retry (if desired) the request with the
*same* method at the new location.
In practice, both the Python ``requests`` library a well as Postman seem to
honour this behavior by default.
Contribute
----------
- Issue Tracker: https://github.com/plone/plone.rest/issues
- Source Code: https://github.com/plone/plone.rest
- Documentation: https://pypi.org/project/plone.rest/
Support
-------
This package is maintained by Timo Stollenwerk <tisto@plone.org>.
If you are having issues, please `let us know <https://github.com/plone/plone.rest/issues>`_.
Credits
-------
plone.rest has been written by Timo Stollenwerk (`kitconcept GmbH <http://kitconcept.com>`_) and Ramon Navarro Bosch (`Iskra <https://iskra.cat>`_).
plone.rest was added as a Plone core package with Plone 5.2 (see `<https://github.com/plone/Products.CMFPlone/issues/2177>`_).
License
-------
The project is licensed under the GPLv2.
Changelog
=========
.. You should *NOT* be adding new change log entries to this file.
You should create a file in the news directory instead.
For helpful instructions, please see:
https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst
.. towncrier release notes start
4.1.3 (2024-01-26)
------------------
Internal:
- Update configuration files.
[plone devs] (93e1ab65)
4.1.2 (2023-10-28)
------------------
Bug fixes:
- Fix parsing mimetypes in Accept header with an extra slash. @djay (#153)
4.1.1 (2023-10-23)
------------------
Internal:
- Fix test leakage, enabling the publication check when it shouldn't be active. @jaroel (#168)
4.1.0 (2023-10-18)
------------------
New features:
- Add support for Python 3.12. @tisto (#167)
Bug fixes:
- Make REST endpoints check for acquired items. @jaroel (#166)
4.0.0 (2023-09-22)
------------------
Breaking changes:
- Drop support for Python 2.7, 3.6, and 3.7 @tisto (#141)
3.0.1 (2023-09-21)
------------------
Bug fixes:
- When ``++api++`` is in the url multiple times, redirect to the proper url.
When the url is badly formed, for example ``++api++/something/++api++``, give a 404 NotFound.
Fixes a denial of service.
See `security advisory <https://github.com/plone/plone.rest/security/advisories/GHSA-h6rp-mprm-xgcq>`_.
[maurits] (#1)
3.0.0 (2023-01-29)
------------------
Breaking changes:
- Change the HTTP status from 301 (Moved Permanently) to 302 (Found) for GET requests and to 307 (Temporary Redirect) for other request methods.
This fixes problems when an existing redirect is re-used.
[mamico] (#135)
- Drop official support for Plone 4.3, 5.0 and 5.1 (most likely the package will continue to work though)
[tisto] (#140)
New features:
- Add official support for Plone 6
[tisto] (#143)
- Add official support for Python 3.9, 3.10, and 3.11
[tisto] (#147)
2.0.0 (2022-10-15)
------------------
Bug fixes:
- Re-release 2.0.0a6 as 2.0.0 [tisto] (#136)
2.0.0a5 (2022-04-07)
--------------------
Bug fixes:
- Fix an infinite loop with redirections from parent to child [ericof] (#133)
2.0.0a4 (2022-03-24)
--------------------
Bug fixes:
- ++api++ traverser should be kept on 30x redirections [mamico] (#132)
2.0.0a3 (2022-02-12)
--------------------
Bug fixes:
- ++api++ traverser should be kept on 30x redirections [mamico] (#127)
2.0.0a2 (2022-01-25)
--------------------
Bug fixes:
- Fix typo in `README.rst` [jensens] (#123)
- Use document_view as default for site root.
[agitator] (#126)
- Resolve all the deprecation warnings that originate in this package's code that are
exposed by running the tests that do not stem from backwards compatibility we support.
[rpatterson] (#128)
2.0.0a1 (2021-10-05)
--------------------
New features:
- Add a traverser `++api++` as an alternative to mark a request as REST request.
[jensens] (#113)
1.6.2 (2021-02-20)
------------------
Bug fixes:
- Explicitly make ``allow_credentials`` required in CORS policy.
This was the default for Bool fields until and including zope.schema 6.0.1, but in 6.1.0 this changed.
[maurits] (#104)
1.6.1 (2020-03-22)
------------------
Bug fixes:
- CORS preflight should happen for all error codes, fixes #101
[sneridagh] (#101)
1.6.0 (2019-10-15)
------------------
New features:
- Remove CMFPlone and make plone.app.redirector dependency optional [timo] (#81)
1.5.1 (2019-10-15)
------------------
- Brown bag release.
1.5.0 (2019-10-13)
------------------
- Brown bag release.
1.4.0 (2018-11-08)
------------------
New features:
- Python 3 compatibility
[tschorr,pbauer,frapell]
1.3.0 (2018-09-11)
------------------
New features:
- Remove unnecessary dependency on Products.CMFPlone.
Import ISiteRoot from Products.CMFCore.interfaces instead of
IPloneSiteRoot from Products.CMFPlone.interfaces.siteroot.
[jordic]
1.2.0 (2018-06-29)
------------------
New features:
- Add support for redirects from plone.app.redirector.
[lgraf]
1.1.1 (2018-06-22)
------------------
Bugfixes:
- Re-release 1.1.0.
1.1.0 (2018-06-22)
------------------
New features:
- Get rid of Products.Five.metaclass dependency for Zope 4 compatibility.
[timo]
1.0.0 (2018-01-17)
------------------
New features:
- Add support for Plone 5.1.
[timo]
- Add Plone 4.3, 5.0 and 5.1 to list classifiers in setup.py.
[timo]
- Set development status to production/stable in setup.py.
[timo]
1.0b1 (2017-05-14)
------------------
Bugfixes:
- Do not render service in preflight requests when no CORS policy was defined.
Fixes: https://github.com/plone/plone.rest/issues/63
[buchi]
1.0a7 (2016-11-21)
------------------
Bugfixes:
- Do not handle view namespace at all. This fixes: https://github.com/plone/plone.rest/issues/50
[buchi]
1.0a6 (2016-05-22)
------------------
- Add support for CORS policies.
[buchi]
- Remove JSON render implementation in service base class. Services
must provide their own render implementation.
[buchi]
- Fallback to regular views during traversal to ensure compatibility with
views being called with a specific Accept header.
[buchi]
1.0a5 (2016-02-27)
------------------
- Implement permission handling. The permission required to access a service
must be declared in the service directive.
[buchi]
- Register services with the Zope configuration system. This provides better
conflict detection and resolution.
[buchi]
- Improve message for 404 Not Found exceptions (don't return HTML).
[lgraf]
- Add regression tests for service dispatching.
[lgraf]
- Restrict traversal of REST requests to content objects. This allows us to
override existing views with a named service (e.g. /search).
[buchi]
- Allow virtual hosting scenarios. This fixes #48.
[tomgross]
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 overridden 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]
Raw data
{
"_id": null,
"home_page": "https://github.com/plone/plone.rest/",
"name": "plone.rest",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "rest http",
"author": "Plone Foundation",
"author_email": "plone-developers@lists.sourceforge.net",
"download_url": "https://files.pythonhosted.org/packages/7c/c1/0d88ef7ac5634cb5dd43e5c2eeea541130d458212aaf4a9348efe2687167/plone.rest-4.1.3.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/plone/plone.rest/actions/workflows/tests.yml/badge.svg\n :alt: Github Actions Status\n :target: https://github.com/plone/plone.rest/actions/workflows/tests.yml\n\n.. image:: https://img.shields.io/coveralls/github/plone/plone.rest.svg\n :alt: Coveralls github\n :target: https://coveralls.io/github/plone/plone.restapi\n\n.. image:: https://img.shields.io/pypi/status/plone.rest.svg\n :target: https://pypi.org/project/plone.rest/\n :alt: Egg Status\n\n.. image:: https://img.shields.io/pypi/v/plone.rest.svg\n :target: https://pypi.org/project/plone.rest/\n :alt: Latest Version\n\n.. image:: https://img.shields.io/pypi/l/plone.rest.svg\n :target: https://pypi.org/project/plone.rest/\n :alt: License\n\n\n==========\nPlone REST\n==========\n\nPurpose\n-------\n\nplone.rest allows you to use HTTP verbs such as GET, POST, PUT, DELETE, etc. in `Plone <https://www.plone.org>`_.\n\nREST stands for `Representational State Transfer <http://en.wikipedia.org/wiki/Representational_state_transfer>`_.\nIt is a software architectural principle to create loosely coupled web APIs.\n\nplone.rest provides the basic infrastructure that allows us to build RESTful endpoints in Plone.\n\nThe reason for separating this infrastructure into a separate package from the 'main' full `Plone REST API <https://github.com/plone/plone.restapi>`_ is so you can create alternative endpoints tailored to specific usecases.\nA number of these specific endpoints are already in active use.\n\n\nAudience\n--------\n\nplone.rest is for experienced web developers who want to build their own HTTP/REST endpoints on top of Plone.\n\nIf you want to **use** a ready-made full RESTful Plone API, you should use `plone.restapi <https://github.com/plone/plone.restapi>`_.\nThat package uses, and depends upon, this one.\n\n\nFeatures\n--------\n\n* Registering RESTful service endpoints for the following HTTP verbs:\n\n * GET\n * POST\n * PUT\n * DELETE\n * PATCH\n * OPTIONS\n\n* Support for Dexterity and Archetypes-based content objects\n* Content negotiation: Services can be registered for arbitrary media types (e.g. 'application/json').\n* Named services allows to register service endpoints for custom URLs\n\n\nRegistering RESTful Service Endpoints\n-------------------------------------\n\nplone.rest allows you to register HTTP verbs for Plone content with ZCML.\n\nThis is how you would register a PATCH request on Dexterity content:\n\n.. code-block:: XML\n\n <plone:service\n method=\"PATCH\"\n accept=\"application/json\"\n for=\"plone.dexterity.interfaces.IDexterityContent\"\n factory=\".service.Patch\"\n permission=\"cmf.ModifyPortalContent\"\n />\n\nYou have to specify the HTTP verb (GET, POST, PUT, DELETE, HEAD, OPTIONS), the\nmedia type used for content negotiation, the interface for the content objects,\nthe factory class that actually returns the content and the permission required\nto access the service.\n\nThe factory class needs to inherit from the plone.rest 'Service' class and to implement a render method that returns the body of the response::\n\n from plone.rest import Service\n\n class Patch(Service):\n\n def render(self):\n return '{\"message\": \"PATCH: Hello World!\"}'\n\n\nContent Negotiation\n-------------------\n\nTo access the service endpoint we created we have to send a GET request to a Dexterity object:\n\n1. by setting the 'Accept' header to 'application/json'::\n\n PATCH /Plone/doc1 HTTP/1.1\n Host: localhost:8080\n Accept: application/json\n\n2. or by adding an explicit traversal step to the path like so::\n\n PATCH /Plone/++api++/doc1 HTTP/1.1\n Host: localhost:8080\n\nThe server then will respond with '200 OK'::\n\n HTTP/1.1 200 OK\n Content-Type: application/json\n\n {\n \"message\": \"PATCH: Hello World!\"\n }\n\nWhy two methods?\nUsing the 'Accept' header is the intended way of RESTful APIs to get different responses from the same URL.\nHowever, if it comes to caching the response in an web accelerator like Varnish or Cloudflare, additional challenges are added.\nSetting the `Vary` header to 'Vary: Accept' helps to a certain degree in Varnish.\nBut cache pollution may happen, because different browsers send different headers on normal HTML requests.\nHosted services like Cloudflare just do not support the 'Vary' usage and can not be used for sites with REST calls.\nThus a second option with different URLs is needed.\n\n\nYou can try this out on the command line:\n\n.. code-block:: console\n\n $ http --auth admin:admin PATCH localhost:8080/Plone/doc1 Accept:application/json\n\n.. note:: You have to install httpie (pip install httpie) to make this example work.\n\nHere is a list of examples for all supported HTTP verbs:\n\nGET::\n\n $ http --auth admin:admin GET localhost:8080/Plone/doc1 Accept:application/json\n $ http --auth admin:admin GET localhost:8080/Plone/++api++/doc1\n\nPOST::\n\n $ http --auth admin:admin POST localhost:8080/Plone/doc1 Accept:application/json\n $ http --auth admin:admin POST localhost:8080/Plone/++api++/doc1\n\nPUT::\n\n $ http --auth admin:admin PUT localhost:8080/Plone/doc1 Accept:application/json\n $ http --auth admin:admin PUT localhost:8080/Plone/++api++/doc1\n\nDELETE::\n\n $ http --auth admin:admin DELETE localhost:8080/Plone/doc1 Accept:application/json\n $ http --auth admin:admin DELETE localhost:8080/Plone/++api++/doc1\n\nPATCH::\n\n $ http --auth admin:admin PATCH localhost:8080/Plone/doc1 Accept:application/json\n $ http --auth admin:admin PATCH localhost:8080/Plone/++api++/doc1\n\nOPTIONS::\n\n $ http --auth admin:admin OPTIONS localhost:8080/Plone/doc1 Accept:application/json\n $ http --auth admin:admin OPTIONS localhost:8080/Plone/++api++/doc1\n\n\nNamed Services\n--------------\n\nNamed services can be registered by providing a 'name' attribute in the service directive:\n\n.. code-block:: XML\n\n <plone:service\n method=\"GET\"\n accept=\"application/json\"\n for=\"Products.CMFPlone.interfaces.IPloneSiteRoot\"\n factory=\".service.Search\"\n name=\"search\"\n permission=\"zope2.View\"\n />\n\nThis registers a service endpoint accessible at the site root using the\nfollowing request::\n\n GET /Plone/search HTTP/1.1\n Host: localhost:8080\n Accept: application/json\n\nService endpoints can also be accessed using the traverser::\n\n GET /Plone/++api++/search HTTP/1.1\n Host: localhost:8080\n\n\nAdditional Path Segments\n------------------------\n\nTo handle additional path segments after the service url like `/Plone/myservice/1/2`\na service has to implement `IPublishTraverse`. The following example simply\nstores all path segments in an array in `self.params`.\n\n.. code-block:: python\n\n from plone.rest import Service\n from zope.interface import implementer\n from zope.publisher.interfaces import IPublishTraverse\n\n @implementer(IPublishTraverse)\n class MyService(Service):\n\n def __init__(self, context, request):\n super(MyService, self).__init__(context, request)\n self.params = []\n\n def publishTraverse(self, request, name):\n self.params.append(name)\n return self\n\n def render(self):\n return {'service': 'named get', 'params': self.params}\n\n\nSee also the implementation of the workflow transition endpoint in\nplone.restapi for an other example.\n\n\nCORS\n----\n\nplone.rest allows you to define CORS policies for services in ZCML. The\nfollowing example defines a policy for all services.\n\n.. code-block:: XML\n\n <plone:CORSPolicy\n allow_origin=\"http://example.net\"\n allow_methods=\"DELETE,GET,OPTIONS,PATCH,POST,PUT\"\n allow_credentials=\"true\"\n expose_headers=\"Content-Length,X-My-Header\"\n allow_headers=\"Accept,Authorization,Content-Type,X-Custom-Header\"\n max_age=\"3600\"\n />\n\nCORS policies can be bound to specific interfaces of content objects and to\nspecific browser layers. This allows us to define different policies for\ndifferent content types or to override existing policies. The following example\ndefines a policy for the site root.\n\n.. code-block:: XML\n\n <plone:CORSPolicy\n for=\"Products.CMFPlone.interfaces.IPloneSiteRoot\"\n layer=\"myproduct.interfaces.IMyBrowserLayer\"\n allow_origin=\"*\"\n allow_methods=\"GET\"\n />\n\nThe CORSPolicy directive supports the following options:\n\nallow_origin\n Origins that are allowed to access the resource. Either a comma separated\n list of origins, e.g. \"http://example.net,http://mydomain.com\" or \"*\".\n\nallow_methods\n A comma separated list of HTTP method names that are allowed by this CORS\n policy, e.g. \"DELETE,GET,OPTIONS,PATCH,POST,PUT\". If not specified, all\n methods for which there's a service registered are allowed.\n\nallow_credentials\n Indicates whether the resource supports user credentials in the request.\n\nallow_headers\n A comma separated list of request headers allowed to be sent by the client,\n e.g. \"X-My-Header\"\n\nexpose_headers\n A comma separated list of response headers clients can access,\n e.g. \"Content-Length,X-My-Header\".\n\nmax_age\n Indicates how long the results of a preflight request can be cached.\n\nfor\n Specifies the interface for which the CORS policy is registered. If this\n attribute is not specified, the CORS policy applies to all objects.\n\nlayer\n A browser layer for which this CORS policy is registered. Useful for\n overriding existing policies or for making them available only if a specific\n add-on has been installed.\n\n\nInstallation\n------------\n\nInstall plone.rest by adding it to your buildout::\n\n [buildout]\n\n ...\n\n eggs =\n plone.rest\n\nand then running \"bin/buildout\"\n\n\nPlone/Python Support\n--------------------\n\nplone.rest 4.x.x supports Plone 5.2 and 6.x on Python 3.8 and newer.\n\nplone.rest 3.x.x supports Plone 5.2 on Python 2.7 and 3.6 to 3.8 and Plone 6.0 on Python 3.8 to 3.11.\n\nIf you need to use Plone 4.3, 5.0, or 5.1 on Python 2.7, check out plone.rest 2.x.x or 1.x.x.\n\nRedirects\n---------\n\nplone.rest will handle redirects created by ``plone.app.redirector`` pretty\nmuch the same way as regular Plone.\n\nIf a redirect exists for a given URL, a ``GET`` request will be answered with\n``302``, and the new location for the resource is indicated in the ``Location``\nheader::\n\n HTTP/1.1 302 Moved Temporarily\n\n Content-Type: application/json\n Location: http://localhost:8080/Plone/my-folder-new-location\n\nAny other request method than GET (``POST``, ``PATCH``, ...) will be answered\nwith ``307 Temporary Redirect``. This status code instructs the client that\nit should NOT switch the method, but retry (if desired) the request with the\n*same* method at the new location.\n\nIn practice, both the Python ``requests`` library a well as Postman seem to\nhonour this behavior by default.\n\n\nContribute\n----------\n\n- Issue Tracker: https://github.com/plone/plone.rest/issues\n- Source Code: https://github.com/plone/plone.rest\n- Documentation: https://pypi.org/project/plone.rest/\n\n\nSupport\n-------\n\nThis package is maintained by Timo Stollenwerk <tisto@plone.org>.\n\nIf you are having issues, please `let us know <https://github.com/plone/plone.rest/issues>`_.\n\n\nCredits\n-------\n\nplone.rest has been written by Timo Stollenwerk (`kitconcept GmbH <http://kitconcept.com>`_) and Ramon Navarro Bosch (`Iskra <https://iskra.cat>`_).\n\nplone.rest was added as a Plone core package with Plone 5.2 (see `<https://github.com/plone/Products.CMFPlone/issues/2177>`_).\n\n\nLicense\n-------\n\nThe project is licensed under the GPLv2.\n\n\nChangelog\n=========\n\n.. You should *NOT* be adding new change log entries to this file.\n You should create a file in the news directory instead.\n For helpful instructions, please see:\n https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst\n\n.. towncrier release notes start\n\n4.1.3 (2024-01-26)\n------------------\n\nInternal:\n\n\n- Update configuration files.\n [plone devs] (93e1ab65)\n\n\n4.1.2 (2023-10-28)\n------------------\n\nBug fixes:\n\n\n- Fix parsing mimetypes in Accept header with an extra slash. @djay (#153)\n\n\n4.1.1 (2023-10-23)\n------------------\n\nInternal:\n\n\n- Fix test leakage, enabling the publication check when it shouldn't be active. @jaroel (#168)\n\n\n4.1.0 (2023-10-18)\n------------------\n\nNew features:\n\n\n- Add support for Python 3.12. @tisto (#167)\n\n\nBug fixes:\n\n\n- Make REST endpoints check for acquired items. @jaroel (#166)\n\n\n4.0.0 (2023-09-22)\n------------------\n\nBreaking changes:\n\n\n- Drop support for Python 2.7, 3.6, and 3.7 @tisto (#141)\n\n\n3.0.1 (2023-09-21)\n------------------\n\nBug fixes:\n\n\n- When ``++api++`` is in the url multiple times, redirect to the proper url.\n When the url is badly formed, for example ``++api++/something/++api++``, give a 404 NotFound.\n Fixes a denial of service.\n See `security advisory <https://github.com/plone/plone.rest/security/advisories/GHSA-h6rp-mprm-xgcq>`_.\n [maurits] (#1)\n\n\n3.0.0 (2023-01-29)\n------------------\n\nBreaking changes:\n\n\n- Change the HTTP status from 301 (Moved Permanently) to 302 (Found) for GET requests and to 307 (Temporary Redirect) for other request methods.\n This fixes problems when an existing redirect is re-used.\n [mamico] (#135)\n- Drop official support for Plone 4.3, 5.0 and 5.1 (most likely the package will continue to work though)\n [tisto] (#140)\n\n\nNew features:\n\n\n- Add official support for Plone 6\n [tisto] (#143)\n- Add official support for Python 3.9, 3.10, and 3.11\n [tisto] (#147)\n\n\n2.0.0 (2022-10-15)\n------------------\n\nBug fixes:\n\n\n- Re-release 2.0.0a6 as 2.0.0 [tisto] (#136)\n\n\n2.0.0a5 (2022-04-07)\n--------------------\n\nBug fixes:\n\n\n- Fix an infinite loop with redirections from parent to child [ericof] (#133)\n\n\n2.0.0a4 (2022-03-24)\n--------------------\n\nBug fixes:\n\n\n- ++api++ traverser should be kept on 30x redirections [mamico] (#132)\n\n\n2.0.0a3 (2022-02-12)\n--------------------\n\nBug fixes:\n\n\n- ++api++ traverser should be kept on 30x redirections [mamico] (#127)\n\n\n2.0.0a2 (2022-01-25)\n--------------------\n\nBug fixes:\n\n\n- Fix typo in `README.rst` [jensens] (#123)\n- Use document_view as default for site root.\n [agitator] (#126)\n- Resolve all the deprecation warnings that originate in this package's code that are\n exposed by running the tests that do not stem from backwards compatibility we support.\n [rpatterson] (#128)\n\n\n2.0.0a1 (2021-10-05)\n--------------------\n\nNew features:\n\n\n- Add a traverser `++api++` as an alternative to mark a request as REST request. \n [jensens] (#113)\n\n\n1.6.2 (2021-02-20)\n------------------\n\nBug fixes:\n\n\n- Explicitly make ``allow_credentials`` required in CORS policy.\n This was the default for Bool fields until and including zope.schema 6.0.1, but in 6.1.0 this changed.\n [maurits] (#104)\n\n\n1.6.1 (2020-03-22)\n------------------\n\nBug fixes:\n\n\n- CORS preflight should happen for all error codes, fixes #101\n [sneridagh] (#101)\n\n\n1.6.0 (2019-10-15)\n------------------\n\nNew features:\n\n\n- Remove CMFPlone and make plone.app.redirector dependency optional [timo] (#81)\n\n\n1.5.1 (2019-10-15)\n------------------\n\n- Brown bag release.\n\n\n1.5.0 (2019-10-13)\n------------------\n\n- Brown bag release.\n\n\n1.4.0 (2018-11-08)\n------------------\n\nNew features:\n\n- Python 3 compatibility\n [tschorr,pbauer,frapell]\n\n\n1.3.0 (2018-09-11)\n------------------\n\nNew features:\n\n- Remove unnecessary dependency on Products.CMFPlone.\n Import ISiteRoot from Products.CMFCore.interfaces instead of\n IPloneSiteRoot from Products.CMFPlone.interfaces.siteroot.\n [jordic]\n\n\n1.2.0 (2018-06-29)\n------------------\n\nNew features:\n\n- Add support for redirects from plone.app.redirector.\n [lgraf]\n\n\n1.1.1 (2018-06-22)\n------------------\n\nBugfixes:\n\n- Re-release 1.1.0.\n\n\n1.1.0 (2018-06-22)\n------------------\n\nNew features:\n\n- Get rid of Products.Five.metaclass dependency for Zope 4 compatibility.\n [timo]\n\n\n1.0.0 (2018-01-17)\n------------------\n\nNew features:\n\n- Add support for Plone 5.1.\n [timo]\n\n- Add Plone 4.3, 5.0 and 5.1 to list classifiers in setup.py.\n [timo]\n\n- Set development status to production/stable in setup.py.\n [timo]\n\n\n1.0b1 (2017-05-14)\n------------------\n\nBugfixes:\n\n- Do not render service in preflight requests when no CORS policy was defined.\n Fixes: https://github.com/plone/plone.rest/issues/63\n [buchi]\n\n\n1.0a7 (2016-11-21)\n------------------\n\nBugfixes:\n\n- Do not handle view namespace at all. This fixes: https://github.com/plone/plone.rest/issues/50\n [buchi]\n\n\n1.0a6 (2016-05-22)\n------------------\n\n- Add support for CORS policies.\n [buchi]\n\n- Remove JSON render implementation in service base class. Services\n must provide their own render implementation.\n [buchi]\n\n- Fallback to regular views during traversal to ensure compatibility with\n views being called with a specific Accept header.\n [buchi]\n\n\n1.0a5 (2016-02-27)\n------------------\n\n- Implement permission handling. The permission required to access a service\n must be declared in the service directive.\n [buchi]\n\n- Register services with the Zope configuration system. This provides better\n conflict detection and resolution.\n [buchi]\n\n- Improve message for 404 Not Found exceptions (don't return HTML).\n [lgraf]\n\n- Add regression tests for service dispatching.\n [lgraf]\n\n- Restrict traversal of REST requests to content objects. This allows us to\n override existing views with a named service (e.g. /search).\n [buchi]\n\n- Allow virtual hosting scenarios. This fixes #48.\n [tomgross]\n\n\n1.0a4 (2016-02-07)\n------------------\n\n- Refactor Dexterity tests to make sure services return the correct object.\n [timo]\n\n- Add support for browser layers. REST services can now be registered to a\n specific browser layer using the 'layer' attribute.\n [buchi]\n\n- Remove request method specific marker interfaces (IGET, IPOST, etc.) because\n they're no longer required for service lookup.\n [buchi]\n\n- Add support for content negotiation. REST services are no longer hardwired\n to 'application/json' Accept headers. Instead the media type can be\n configured with the service directive.\n [buchi]\n\n- Refactor traversal of REST requests by using a traversal adapter on the site\n root instead of a traversal adapter for each REST service. This prevents\n REST services from being overridden by other traversal adapters.\n [buchi]\n\n\n1.0a3 (2015-12-16)\n------------------\n\n- Release fix. 1.0a2 was a brown-bag release. This fixes https://github.com/plone/plone.rest/issues/34.\n [timo]\n\n\n1.0a2 (2015-12-10)\n------------------\n\n- Simplify patch of DynamicType pre-traversal hook and actually make it work\n with Archetypes.\n [buchi]\n\n- Render errors as JSON.\n [jone]\n\n- Add support for named services which allows registering services like\n ``GET /Plone/search`` or ``GET /Plone/doc1/versions/1`` using a 'name' attribute.\n [jone, lukasgraf, buchi]\n\n- Remove \"layer\" from service directive for now,\n because it is not yet implemented properly.\n [jone]\n\n\n1.0a1 (2015-08-01)\n------------------\n\n- Initial release.\n [bloodbare, timo]\n\n\n",
"bugtrack_url": null,
"license": "GPL version 2",
"summary": "Plone support for HTTP verbs.",
"version": "4.1.3",
"project_urls": {
"Homepage": "https://github.com/plone/plone.rest/"
},
"split_keywords": [
"rest",
"http"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb559739b8522e1d407679ccc7fb2bb98b360ff31810b00b4fd87c46d29ef6b9",
"md5": "cc9c3658aa1d3a19ae43935869dc4880",
"sha256": "d0b6b4f7aedd37dfe3134035961a0efb6461490157290998c97c517da028d1d4"
},
"downloads": -1,
"filename": "plone.rest-4.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc9c3658aa1d3a19ae43935869dc4880",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 109216,
"upload_time": "2024-01-26T00:29:26",
"upload_time_iso_8601": "2024-01-26T00:29:26.717708Z",
"url": "https://files.pythonhosted.org/packages/eb/55/9739b8522e1d407679ccc7fb2bb98b360ff31810b00b4fd87c46d29ef6b9/plone.rest-4.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7cc10d88ef7ac5634cb5dd43e5c2eeea541130d458212aaf4a9348efe2687167",
"md5": "22590185b499b2e731521543ab766d95",
"sha256": "a014837725c8f7e6a61fc4c59b340f1d4968e05773739f9cfb69a5beeacf258d"
},
"downloads": -1,
"filename": "plone.rest-4.1.3.tar.gz",
"has_sig": false,
"md5_digest": "22590185b499b2e731521543ab766d95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 109536,
"upload_time": "2024-01-26T00:29:28",
"upload_time_iso_8601": "2024-01-26T00:29:28.752390Z",
"url": "https://files.pythonhosted.org/packages/7c/c1/0d88ef7ac5634cb5dd43e5c2eeea541130d458212aaf4a9348efe2687167/plone.rest-4.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 00:29:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plone",
"github_project": "plone.rest",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"landscape": true,
"requirements": [],
"tox": true,
"lcname": "plone.rest"
}
JSON
