RESTful hypermedia API for Plone.
Switch branches/tags
Clone or download
pbauer Merge pull request #542 from plone/python3
[WIP] Python 3 support
Latest commit 1d4d683 Oct 17, 2018
Permalink
Failed to load latest commit information.
docs/source Docs: Add note to clarify that @search endpoint includes container Sep 8, 2018
src/plone add crazy dummy-test to fix plone/Products.CMFPlone#2592 Oct 12, 2018
.coveragerc There's no point in measuring the coverage of test modules. Mar 4, 2017
.editorconfig Don't remove whitespace in .resp files. Apr 20, 2017
.gitignore gitignore mypy cache Oct 3, 2018
.isort.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
.landscape.yml Make landscape ignore pylint inherit-non-class. Jul 11, 2015
.travis.yml Do not build docker images. Jun 28, 2018
CHANGES.rst add changenote and classifiers Oct 17, 2018
CONTRIBUTORS.rst Fix ReST on pypi. Jun 25, 2018
Dockerfile Install git on Dokcerfile which is needed for the mr.developer auto-c… Jun 3, 2017
Jenkinsfile Revert "Mv jmeter.csv -> jmeter.jtl." Jan 8, 2018
MANIFEST.in Exclude .editorconfig from release. Jul 19, 2018
Makefile Use requirements.txt in Makefile. Sep 10, 2018
README.rst Demo URL is plonedemo.kitconcept.com not plonerestapi.kitconcept.com. Jun 14, 2017
base.cfg Allow CORS calls from port 3000 as well (create-react-app). Jul 20, 2018
buildout.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
heroku.cfg heroku: do not pin pytz. Aug 15, 2016
performance.jmx Upload image data when creating a news item. Jan 8, 2018
plone-4.3.x-performance.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
plone-4.3.x.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
plone-5.0.x-performance.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
plone-5.0.x.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
plone-5.1.x-performance.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
plone-5.1.x.cfg Update to latest plone releases (4.3.17, 5.1.2); remove old buildout … Jun 23, 2018
requirements.txt Upgrade to zc.buildout 2.12.2 and setuptools 40.4.3. Oct 11, 2018
setup.py add changenote and classifiers Oct 17, 2018
site.cfg Dockerfile: create instance and cors policy. Jul 6, 2017
swagger-siteroot.yaml initial basic swagger yaml May 17, 2016
test-no-sphinx-warnings.in Add test that fails if Sphinx build has warnings or errors: Jun 23, 2018
test-no-uncommitted-doc-changes.in Update HTTP examples path in test-no-uncommitted-doc-changes.in. Jun 28, 2018
travis.cfg Remove createcoverage section from travis.cfg. May 27, 2017
versions.cfg Merge branch 'master' into newnewtiles Jun 25, 2018

README.rst

https://secure.travis-ci.org/plone/plone.restapi.png?branch=master https://coveralls.io/repos/github/plone/plone.restapi/badge.svg?branch=master Code Health https://readthedocs.org/projects/pip/badge/

Introduction

plone.restapi is a RESTful hypermedia API for Plone.

RESTful Hypermedia API

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

Most web APIs have a tight coupling between client and server. This makes them brittle and hard to change over time. It requires them not only to fully document every small detail of the API, but also to write a client implementation that follows that specification 100% correctly and breaks as soon as you change any detail.

A hypermedia API just provides an entry point to the API that contains hyperlinks the clients can follow, just as a human user of a regular website knows the initial URL of the site and then follows hyperlinks to navigate through the site. This has the advantage that the client needs to understand only how to detect and follow links. The URL and other details of the API can change without breaking the client.

Documentation

http://plonerestapi.readthedocs.org

Roadmap

https://github.com/plone/plone.restapi/milestones

Live Demo

A live demo of Plone 5 with the latest plone.restapi release is available at:

http://plonedemo.kitconcept.com

Example GET request on the portal root:

$ curl -i http://plonedemo.kitconcept.com -H "Accept: application/json"

Example POST request to create a new document:

$ curl -i -X POST http://plonedemo.kitconcept.com -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"@type": "Document", "title": "My Document"}' --user admin:admin

Note

You will need some kind of API browser application to explore the API. We recommend using Postman.

Design Decisions

  • A truly RESTful API (Hypermedia / HATEOAS / Linked-data)
  • JSON is the main target format; support for other formats (HTML, XML) will come later
  • Use HTTP headers (to set format and versioning, also provide URL-based option to make it easier for people to try it out)
  • No versioning; versioning in the HTTP header can be added later
  • Field names just map over (we will not try to clean up attributes or enforce naming standards like pep8 (e.g. isPrincipiaFoldish -> is_folderish)

Software Quality

  • 100% test coverage
  • 100% PEP8 compliant
  • Documentation-first approach for enhancements

Further Reading

Standards

License

The project is licensed under the GPLv2.