Build RESTful APIs with Plone and plone.restapi

Plone is a powerful CMS built on Python. It offers robust features for content management. With plone.restapi, you can extend Plone to build RESTful APIs.

This guide will walk you through the process. You'll learn how to set up, configure, and use plone.restapi effectively.

Why Use plone.restapi?

plone.restapi is a modern RESTful hypermedia API for Plone. It provides easy integration with frontend frameworks. It also supports JSON-based interactions.

The API is designed to be flexible and extensible. It works well with custom content types and existing Plone features. You can learn more about content types in our Custom Content Models in Plone guide.

Installation and Setup

First, ensure you have Plone installed. Then add plone.restapi to your buildout configuration:

[instance]
eggs =
    Plone
    plone.restapi

After updating buildout, restart your Plone instance. The API will be available at /Plone/@api.

Basic API Endpoints

plone.restapi provides several default endpoints. These include content operations, user management, and site configuration.

Here's how to retrieve site content:

GET /Plone/@api

The response will be in JSON format. It includes links to available endpoints and services.

Working with Content

To create content, use the POST method. Here's an example for adding a new page:

import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
}

data = {
    "@type": "Document",
    "title": "My New Page",
    "description": "API-created content"
}

response = requests.post(
    'http://localhost:8080/Plone/@api/content',
    headers=headers,
    json=data
)

For more on content operations, see our Plone Traversal System Guide.

Authentication

plone.restapi supports multiple authentication methods. These include Basic Auth, JWT tokens, and OAuth2.

To get a JWT token:

POST /@login
Content-Type: application/json

{
    "login": "admin",
    "password": "secret"
}

The response includes a token for authenticated requests.

Custom Endpoints

You can extend the API with custom endpoints. Create a new Python package and register your service.

Here's a basic example:

from plone.restapi.services import Service
from zope.interface import implementer
from zope.publisher.interfaces import IPublishTraverse

@implementer(IPublishTraverse)
class HelloService(Service):
    
    def reply(self):
        return {
            "message": "Hello World",
            "service": "hello"
        }

Register this in ZCML:

Now you can access it at /@hello.

Performance Considerations

For large sites, API performance matters. Use the Plone Catalog & Indexing for Efficient Queries techniques.

Always limit returned fields when possible. Use batched requests for large result sets.

Error Handling

The API returns standard HTTP status codes. 200 for success, 400 for bad requests, 401 for unauthorized access.

Error responses include detailed messages:

{
    "type": "Unauthorized",
    "message": "Login failed"
}

Conclusion

plone.restapi brings modern API capabilities to Plone. It's perfect for headless CMS implementations.

With this guide, you can start building powerful RESTful services. Combine it with Plone's robust content management for great results.

For more advanced topics, explore our Plone for Python Developers guide.