PLIP: Deprecate Accept-Header-Based REST API Routing in Favor of /++api++/ URLs

[mamico]

PLIP (Plone Improvement Proposal)

Responsible Persons

Proposer: Mauro Amico @mamico

Seconder:

Abstract

This PLIP proposes to fully deprecate the REST API routing mechanism based on the Accept: application/json HTTP header.

While both header-based and URL-based (/++api++/) REST API access are currently supported, this proposal aims to make /++api++/ the only supported mechanism for REST API access in Plone.

The header-based behavior will be deprecated and eventually disabled by default, with an optional environment variable allowing legacy installations to re-enable it.

Motivation

Plone currently supports two parallel mechanisms for REST API access:

1. Implicit detection based on the Accept: application/json header
2. Explicit URL-based routing using the /++api++/ prefix

Maintaining both mechanisms introduces ambiguity and complexity in routing, caching, security, and deployment configurations. (i.e. plone/plone.rest#77)

The header-based mechanism in particular has several drawbacks:

• Implicit behavior depending on client headers rather than explicit URLs
• Increased complexity in traversal and middleware logic
• Difficulties in configuring reverse proxies and caching layers
• Harder to apply different security, rate-limiting, and caching policies

The /++api++/ prefix already provides a clear and explicit separation of concerns
and aligns with common best practices for API design.

Assumptions

• Both routing mechanisms are currently active and supported
• /++api++/ is considered the canonical and future-proof REST API entry point
• Legacy behavior must be explicitly opt-in once deprecated

Proposal & Implementation

1. Canonical REST API Entry Point

   • /++api++/ becomes the only supported REST API URL namespace

2. Legacy Opt-In via Environment Variable

   • An environment variable (e.g. PLONE_ENABLE_ACCEPT_HEADER_RESTAPI)
     can be used to re-enable the legacy behavior
   • This allows existing integrations more time to migrate

Implementation Notes

• Document the migration path for integrators and frontend applications
• Update tests to ensure no REST API view is reachable without /++api++/
  when the legacy flag is disabled

Deliverables

• plone.rest/plone.restapi changes to disable Accept-based routing by default
• Environment-variable-based legacy compatibility switch
• Updated documentation and upgrade notes
• Test coverage for both default and legacy modes

Risks

• Existing clients (eg. volto sites, volto addons, ...) relying on Accept: application/json will break

These risks are mitigated by:

• A clear deprecation phase
• An explicit opt-in legacy mechanism
• Early communication and documentation

Participants

[mamico]

Related Deprecations

As part of the same deprecation and cleanup effort, this PLIP also proposes to formally deprecate the behavior described in plone/plone.rest#185.

[krishi-agrawal]

hi, can i work on this?

[stevepiercy]

@krishi-agrawal no. Please read and follow First-time contributors, especially Things not to do, and Contributing to Plone.

[tisto]

I am undecided on this. Cleaning up and having one canonical way is a worthwhile goal. However, content negotiation has the advantage to support multiple formats. We might want to support other formats like plain text or markdown, which might become more important with the raise of AI. Just some food for thought...

[davisagli]

@tisto I understand @mamico's reasoning here and am cautiously in favor. We can still use the Accept header for content negotiation of different response formats, the proposal here is just to stop using it as a factor for how we enter "API mode" during traversal.

It would be a breaking change that can happen only in Plone 7 -- but adding a way to opt in to it earlier with an environment variable sounds okay to me.

[tisto]

@davisagli I understand. With the raise of AI I think that Markdown becomes increasingly important. Therefore I would like to have a discussion on that matter first, before we make a move in a certain direction that we might regret in the future.

[davisagli]

@tisto I think supporting Markdown is mostly a separate matter from this PLIP. This just means that you would have to send a request with an Accept: text/markdown header to /++api++/path/to/content instead of /path/to/content