plone.restapi: A RESTful hypermedia API for Plone.¶
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.
- CRUD Web Services
- Additional Endpoints (MOCKS ONLY)
- Customizing the API
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 write a client implementation that follows that specification 100% 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 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.
Heroku live demo:: http://stormy-headland-44390.herokuapp.com/Plone/
You will need some kind of API browser application to explore the API. We recommend to use Postman.
- A truly RESTful API (Hypermedia / HATEOAS / Linked-data)
- JSON is the main target formt, support other formats (HTML, XML) later
- Use HTTP headers (to set format and versioning, also provide URL-based option to make it easier for people to try it out)
- Versioning should be included (we will decide later, if we actually want to support multiple versions at the same time)
- Field names just map over (we will not try to clean up attributes or enforce naming standards like pep8 (e.g. isPrincipiaFoldish -> is_folderish)
- Dexterity only. We will not put effort into supporting Archetypes.
- 100% Test Coverage
- 100% PEP8 compliant