REST API

A RESTful API for Plone.

Table of Contents

• Introduction
  • Content Negotiation
• Usage
  • Authentication
  • Batching
  • Content Manipulation
  • Customizing the API
  • Expansion
  • Explore the API using Postman
  • i18n: internationalization of screen messages
  • Serialization
  • Types Schema
  • Volto Blocks support
• Endpoints
  • Add-ons
  • Aliases
  • Breadcrumbs
  • Comments
  • Content Types
  • Content Rules
  • Context Navigation
  • Control Panels
  • Copy and Move
  • Database
  • Email Notification
  • Email Send
  • Groups
  • History
  • Link Integrity
  • Locking
  • Navigation
  • Navigation root
  • Portal Actions
  • Portraits
  • Principals
  • Querystring
  • Querystring Search
  • Registry
  • Relations
  • Roles
  • Search
  • Sharing
  • Site
  • System
  • Transactions
  • Translations
  • TUS resumable upload
  • Types
  • Upgrade
  • Users
  • User schema
  • Vocabularies and Sources
  • Workflow
  • Working Copy
• Upgrade Guide
  • Upgrading to plone.restapi 9.x
  • Upgrading to plone.restapi 8.x
  • Upgrading to plone.restapi 7.x
  • Upgrading to plone.restapi 6.x
  • Upgrading to plone.restapi 5.x
  • Upgrading to plone.restapi 4.x
  • Upgrading to plone.restapi 3.x
  • Upgrading to plone.restapi 2.x
  • Upgrading to plone.restapi 1.0b1
  • Upgrading to plone.restapi 1.0a25
  • Upgrading to plone.restapi 1.0a17
• Contribute to plone.restapi
  • Prerequisites
  • Set up development environment
  • Generate documentation examples
  • Conventions
  • Code formatting and testing

Introduction

plone.restapi is a RESTful hypermedia API for Plone.

Documentation

https://plonerestapi.readthedocs.io/en/latest/

Getting started

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

https://demo.plone.org/

An example GET request on the portal root is the following.

curl -i https://demo.plone.org/++api++ -H "Accept: application/json"

An example POST request to create a new document is the following.

curl -i -X POST https://demo.plone.org/++api++ \
    -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. You will also need to first obtain a basic authorization token. We recommend using Postman which makes it easier to obtain a basic authorization token.

Installation

Install plone.restapi by adding it to your buildout.

[buildout]

# ...

eggs =
    plone.restapi

…and then running bin/buildout.

Python / Plone Compatibility

plone.restapi 9 requires Python 3 and works with Plone 5.2 and Plone 6.x.

plone.restapi 8 entered "maintenance" mode with the release of plone.restapi 9 (September 2023). It is not planned to backport any features to this version and we highly recommend to upgrade to plone.restapi 9.

Python versions that reached their end-of-life, including Python 3.6 and Python 3.7 are not supported any longer.

Use plone.restapi 7 if you are running Python 2.7 or Plone versions below 5.2.

Contribute

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

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

• Documentation: https://plonerestapi.readthedocs.io/en/latest

Examples

plone.restapi has been used in production since its first alpha release. It can be seen in action at the following sites:

• Zeelandia GmbH & Co. KG: https://www.zeelandia.de (by kitconcept GmbH)

• VHS-Ehrenamtsportal: https://vhs-ehrenamtsportal.de (by kitconcept GmbH)

• German Physical Society: https://www.dpg-physik.de (by kitconcept GmbH)

Support

If you are having issues, please let us know via the issue tracker.

If you require professional support, here is a list of Plone solution providers that contributed significantly to plone.restapi in the past.

• kitconcept GmbH (Germany)

• 4teamwork (Switzerland)

• CodeSyntax (Spain)

License

The project is licensed under the GPLv2.

Appendix and Glossary

• HTTP Status Codes
• Glossary

Index

• Index