Page API path params could use special character encoding #30290
Description
Parent Issue
No response
Problem Statement
While working on some Page API endpoints in the API Playground, I noticed that in cases (such as api/v1/page/render/... or api/v1/page/json/...) where a page path is required as a path param, attempting to fetch a page in a subfolder was failing with a 400 status. This is because Swagger was automatically encoding the / characters. See:
This outcome is repeatable in curl, as well:
curl -X 'GET' 'http://localhost:8084/api/v1/page/render/a%2Faffa' -H 'accept: application/json' -H "Authorization: $BASIC"
<!doctype html><html lang="en"><head><title>HTTP Status 400 – Bad Request</title><style type="text/css">body {font-family:Tahoma,Arial,sans-serif;} h1, h2, h3, b {color:white;background-color:#525D76;} h1 {font-size:22px;} h2 {font-size:16px;} h3 {font-size:14px;} p {font-size:12px;} a {color:black;} .line {height:1px;background-color:#525D76;border:none;}</style></head><body><h1>HTTP Status 400 – Bad Request</h1></body></html>%
As far as the Playground end goes: Swagger has an allowReserved property that, when set to true, is supposed to permit reserved characters to go unencoded. However, as seen below:
- https://swagger.io/specification/#parameter-object
- https://javadoc.io/static/io.swagger.core.v3/swagger-annotations/2.2.0/io/swagger/v3/oas/annotations/Parameter.html#allowReserved--
...this property only works for query params, and not path params. This is not purely a fault of Swagger; it's simply implementing the OpenAPI spec, which does not itself include this behavior. You can see this in several discussions:
- Optional and multi-segment path parameters OAI/OpenAPI-Specification#2653
- 3.1 Request - allowReserved in path OAI/OpenAPI-Specification#1840
- Support for path parameters which can contain slashes OAI/OpenAPI-Specification#892 (etc)
The result is that the 4.0 Open API Specification (codenamed Moonwalk) will implement the more complete URI template scheme of RFC 6570.
However, in the meantime, we're unable to successfully call path params with slashes in the API Playground.
Steps to Reproduce
Either:
- Open the API Playground
- Choose a Page API endpoint that expects a URI path param
- Enter a path that includes a subfolder
- See 400 result
Or:
- Perform a curl call for a Page API endpoint that expects a URI path param
- Encode subfolder slashes as
%2F - See 400 result
Acceptance Criteria
Page API should be able to accept URI path params either with special character literals, or with URL-encoded specials (e.g., / and %2F as interchangeable). This preserves backwards compatibility, while enabling greater overall permissiveness to inputs.
dotCMS Version
Current trunk: dotcms-core 1.0.0-SNAPSHOT (October 08, 2024 3:48 PM)
Proposed Objective
Core Features
Proposed Priority
Priority 3 - Average
External Links... Slack Conversations, Support Tickets, Figma Designs, etc.
Discussion that led to this issue here
Assumptions & Initiation Needs
No response
Quality Assurance Notes & Workarounds
No response
Sub-Tasks & Estimates
No response