toniginard / plone.restapi

RESTful hypermedia API for Plone.

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

• REST in Practice: Hypermedia and Systems Architecture (Webber, Parastatidis, Robinson)

Standards

• JSON-LD
• JSON Schema
• Schema.org
• Hydra
• Collection+JSON
• Siren

License

The project is licensed under the GPLv2.