Repository navigation
Description
Description
Add a clean v2 REST surface for reading and writing dotCMS file assets (.vtl, .dotsass, .css, .js, …) in place, addressable by host-qualified path (//host/application/...) or identifier.
The current v1 path forces clients through a multipart workflow endpoint plus a separate search to resolve the content-type inode — a search that fails for some extensions (e.g. .dotsass) — and raw reads hit content-negotiation and file-size edges. A purpose-built v2 endpoint removes that friction.
/api/v1/assets stays untouched: it backs the dotCMS CLI, so its contract is a rollback-unsafe API surface we will not change. v2 reuses the same underlying helper logic — no business logic is duplicated or moved.
Acceptance Criteria
- Read a file asset's raw content by host-qualified path or identifier via a single GET
- Write (create or update) a file asset's content, with separate working-save and publish operations
- Path/identifier and publish intent expressed in the URL, not request-body flags
- Works for all file-asset extensions, including ones that fail today (e.g.
.dotsass) - Handles large files without truncation or content-negotiation errors
-
/api/v1/assetsAPI contract is unchanged
Contract guarantees (public, must hold)
- Working-save preserves the live version — saving a draft over a published asset creates/updates the working version and leaves the currently-live version live and serving its bytes; only publish promotes the new version
- Identifier reads enforce READ permission — a user without permission on the asset is rejected (403), never served the bytes; identifier and path addressing select the same version with identical defaults (working, default language)
- Zero-byte writes are rejected — both a missing
filepart and a present, zero-bytefilepart return 400 with distinct, clear messages. v2 surfaces core's existing 0-length checkin reject (DotContentletStateException,ESContentletAPIImpl#handleBinaries, defaultCONTENT_ALLOW_ZERO_LENGTH_FILES=false) as a clean 400 — never a 500. Empty-file scaffolding is explicitly out of scope (see Decisions locked). - Writes return stored
fileSize— the write response includes the persisted byte length (fileSize/metaData.length) so a caller can assert what actually landed without a second read. Eliminates the silent-success failure mode (write reports success while writing wrong/empty bytes). - Language handling — omitted/blank language defaults to the site default; a non-blank unknown language is rejected (400)
Error handling
Every failure returns a correct, meaningful HTTP status (not a generic 500):
- Unknown host → 404
- Path or identifier not found / not a file asset → 404
- Missing asset, or requested language/version unavailable on read → 404
- Invalid request (missing-or-conflicting path/id, missing file part, zero-byte file part, unknown language, path points at a folder) → 400
- File exceeds max upload size → 400
- Insufficient permission on target folder → 403
Testing & docs
- Java integration tests cover the contract guarantees above (v1 unchanged, working-save preserves live, identifier READ enforcement, default/version selection, filename mismatch, temp cleanup + rollback, multipart validation, missing-file-part and zero-byte-file-part both → 400,
fileSizereturned in the write response) - OpenAPI spec and Postman coverage added, including the error-status cases above
Decisions locked
Resolved during planning/brainstorm; recorded so implementation doesn't re-litigate or revert them:
- Empty-file writes are out of scope. Earlier drafts treated zero-byte files as valid (scaffold-then-fill). Reversed: it is not a real agent workflow (an agent emits complete files; a
fileSize: 0result is indistinguishable from the silent-failure mode that caused an outage). v2 honors core's existing 0-length reject on both/saveand/publish, surfaced as a 400. If a human draft-empty workflow is ever needed, the path is a route-scopedContentlet.VALIDATE_EMPTY_FILE=falseon/saveonly (never/publish) — not built now. - v2 checkin always creates a new version. Verified:
WebAssetHelpercheckin hardcodescreateNewVersion=true; there is no instance env var that defeats it (the only lever is the programmaticDONT_VALIDATE_ME, which v2 does not set). So writes are always rollback-able. - The real cause of the 0-byte outage was a null binary, not core writing empty. Core rejects a true 0-length checkin; the prior
template.vtl → 0 bytescorruption came from a malformed multipart where no binary part attached (the 0-length check is skipped when the file is null). The "missingfilepart → 400" validation is what closes that specific hole. - Verify the exception mapping before build: confirm
DotContentletStateExceptionmaps to 400 via an existing JAX-RSExceptionMapper. If none exists, the v2 resource catches it and rethrowsBadRequestException.
Additional Context
Motivated by the dotCMS MCP server using these endpoints for AI-assisted editing of file assets — an agent driving read → edit → publish entirely through REST. The MCP tooling itself is a separate effort; this issue covers only the endpoint.
Evidence behind the design: a full a11y fix session on demo.dotcms.com run entirely through the MCP surfaced v1's undocumented multipart contract (≈6 trial attempts to find the working shape), a silent-success write that published template.vtl as 0 bytes and took the home page down, and read-path friction (POST-to-read, stInode Lucene lookup failing for .dotsass, 406s, large-file overflow). v2 removes the cause (un-mis-buildable flat multipart, intent-in-route, GET reads, fileSize in the response), not just the symptom.
Priority: High
Metadata
Metadata
Assignees
Type
Projects
- StatusShow more project fieldsDone
Activity
github-actions commentedon Jun 10, 2026
PRs linked to this issue
feat(rest): add /api/v2/assets endpoint for reading and writing file …
feat(rest): add GET /api/v1/page/_render-sources/{uri} to locate a pa…
fmontes commentedon Jun 17, 2026
#36112 (comment)