Skip to content

feat(rest): add /api/v2/assets endpoint for reading and writing file assets #35928

Description

@fmontes

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/assets API 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 file part and a present, zero-byte file part return 400 with distinct, clear messages. v2 surfaces core's existing 0-length checkin reject (DotContentletStateException, ESContentletAPIImpl#handleBinaries, default CONTENT_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, fileSize returned 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: 0 result is indistinguishable from the silent-failure mode that caused an outage). v2 honors core's existing 0-length reject on both /save and /publish, surfaced as a 400. If a human draft-empty workflow is ever needed, the path is a route-scoped Contentlet.VALIDATE_EMPTY_FILE=false on /save only (never /publish) — not built now.
  • v2 checkin always creates a new version. Verified: WebAssetHelper checkin hardcodes createNewVersion=true; there is no instance env var that defeats it (the only lever is the programmatic DONT_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 bytes corruption came from a malformed multipart where no binary part attached (the 0-length check is skipped when the file is null). The "missing file part → 400" validation is what closes that specific hole.
  • Verify the exception mapping before build: confirm DotContentletStateException maps to 400 via an existing JAX-RS ExceptionMapper. If none exists, the v2 resource catches it and rethrows BadRequestException.

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

Activity

  1. self-assigned this
    on Jun 4, 2026
  2. added theissue type on Jun 4, 2026
  3. github-actions commented on Jun 10, 2026

    @github-actions
    Contributor
  4. added 2 commits that reference this issue on Jun 16, 2026
    c99165b
    1223da3
  5. fmontes commented on Jun 17, 2026

    @fmontes
    MemberAuthor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions