[Spike] ES Search: backend API audit

[hmoreras]

Goal

Audit the existing backend endpoints consumed by ES-Search and determine whether the Angular portlet can consume them as-is, or if API changes are needed (new endpoints, @Schema fixes, error-shape normalization, Swagger coverage, versioning).

Scope of audit

Endpoints:

• GET/POST /api/es/search (ESContentResourcePortlet#search, #searchPost)
• GET/POST /api/es/raw (ESContentResourcePortlet#searchRaw)
• POST /api/portlet/es-search/render (legacy JSP render — confirm NOT consumed by Angular)

For each endpoint, document:

Aspect	Finding
Current request shape	body, query params
Current response shape	JSON structure, key fields
@Schema annotation	accurate? missing?
Error shape	HTTP status + body on invalid ES DSL, auth failure, license denial
Versioning	is there a /api/v1/... equivalent? should we migrate?
Swagger coverage	present in OpenAPI? Correct?
Authorization	@RequiresAnyRole / license gate implementation

Known gap (pre-validated)

A live fetch of https://demo.dotcms.com/api/openapi.json on 2026-04-17 confirmed that /api/es/search and /api/es/raw are absent from the OpenAPI spec. Only the tag Elasticsearch Content Search exists with zero paths attached. No ESSearchResults, ESSearchResponse, or related schemas are published.

Fixing this is a mandatory deliverable of this spike, not a speculative finding. The spike therefore has two outcomes:

1. Document current behavior (reverse-engineered from ESContentResourcePortlet.java + runtime calls)
2. Produce a PR (or child issue under Dojo to Angular: Backend API Updates #34292) that adds the missing @Schema, @Operation, and @ApiResponse annotations so these endpoints appear in the OpenAPI spec

Deliverable

A section in this issue's body (edited directly) with:

1. Per-endpoint table as above
2. Before / after comparison: OpenAPI spec diff after the annotation PR lands
3. Child issues filed under Dojo to Angular: Backend API Updates #34292 for any non-annotation BE work (e.g. error-shape normalization if it is messy)

Acceptance Criteria

• All 4 endpoints audited against both source code and live OpenAPI spec
• OpenAPI spec re-fetched from http://localhost:8080/api/openapi.json after changes; /api/es/search and /api/es/raw appear with complete request/response schemas
• ESSearchResults and SearchResponse-equivalent schema components are defined in components/schemas
• Error shape documented (what the Angular FE must handle: 4xx on bad JSON, 401/403 on auth, 402/451 on license)
• Any non-annotation changes filed as child issues under Dojo to Angular: Backend API Updates #34292 and linked here
• No BE behavior changed — annotations only (behavior changes filed separately)

Out of scope

• Do NOT implement any BE behavior fix in this spike (file child issues instead)
• Do NOT specify Angular service shape (handled in the FE implementation spec sub-task)

Parent

#34733

[hmoreras]

Backend API Audit — Findings

Sources: ESContentResourcePortlet.java, portlet.xml, render.jsp, openapi.yaml (local build)
Pre-existing annotation work: PR #34778 (March 3 2026)
Parent epic: #34733

---

Endpoint 1 — GET /api/es/search (intentionally hidden)

Aspect	Finding
Request shape	Body = ES JSON string (non-standard GET-with-body); query params: depth (0–3 or null), live (bool), allCategoriesInfo (bool)
Response shape	{ "contentlets": [...], "esresponse": [{ ...raw SearchResponse... }] }
@Schema annotation	@Hidden / @Operation(hidden = true) — intentionally excluded from spec
Error shape	400 on invalid JSON or invalid depth; exception message string on processing failure
Versioning	No /v1/ equivalent
Swagger coverage	Intentionally hidden — GET-with-body is non-standard REST; POST variant covers the public surface
Authorization	webResource.init(null, true, ...) — requires authenticated user

---

Endpoint 2 — POST /api/es/search

Aspect	Finding
Request shape	Body = ES JSON string; query params: depth (string, 0–3 or null), live (bool, default false), allCategoriesInfo (bool, default false)
Response shape	{ "contentlets": [ { ...contentlet fields + identifier + inode + type... } ], "esresponse": [ { ...raw ES SearchResponse... } ] }
@Schema annotation	Was generic type: object — updated to ESSearchResponseView
Error shape	400: ExceptionMapperUtil.createResponse(e, BAD_REQUEST) → { "error": "..." }. Processing exception: responseResource.responseError(msg) → plain string. 401: thrown by webResource.init. No 403 or 402 (license gap — see §Gap analysis)
Versioning	No /v1/ equivalent; endpoint predates versioning convention
Swagger coverage	Present in OpenAPI after PR #34778. @RequestBody annotation and typed schema added in this spike
Authorization	webResource.init(null, true, false, false, null) — authenticated user required; anonymous → mode.showLive

---

Endpoint 3 — GET /api/es/raw (intentionally hidden)

Aspect	Finding
Request shape	Body read via IOUtils.toString(request.getInputStream()) — no JAX-RS body parameter
Response shape	Direct Elasticsearch SearchResponse.toString() — raw JSON
@Schema annotation	@Hidden / @Operation(hidden = true) — intentionally excluded
Error shape	Exception message string via responseResource.responseError(msg)
Versioning	No /v1/ equivalent
Swagger coverage	Intentionally hidden
Authorization	webResource.init(null, true, ...) — requires authenticated user

---

Endpoint 4 — POST /api/es/raw

Aspect	Finding
Request shape	Body = ES JSON string (read via IOUtils.toString(request.getInputStream())); no query params
Response shape	Direct esSearchRaw(...) result — raw ES SearchResponse JSON (hits, took, timed_out, aggregations, suggest, _shards)
@Schema annotation	Was generic type: object — updated to ESRawSearchResponseView
Error shape	Exception message string via responseResource.responseError(msg). No 403 or 402 (license gap)
Versioning	No /v1/ equivalent
Swagger coverage	Present in OpenAPI after PR #34778, but requestBody was absent. Added requestBody with description and example in this spike
Authorization	webResource.init(null, true, ...) — requires authenticated user

---

Endpoint 5 — POST /api/portlet/es-search/render (legacy JSP)

Consumed by Angular? ❌ No. This is the old Dojo full-page form submit handler. The Angular portlet calls POST /api/es/search directly and must not use this endpoint.

---

Gap analysis

Gap	Status	Action taken
Endpoints absent from OpenAPI spec	✅ Fixed in PR #34778	POST variants now visible
GET variants hidden	✅ Correct / intentional	Non-standard GET-with-body; POST variants cover public surface
@RequestBody missing on POST /es/raw	✅ Fixed in this spike	Added requestBody annotation + YAML
@RequestBody undescribed on POST /es/search	✅ Fixed in this spike	Added description + example
Response schemas generic type: object	✅ Fixed in this spike	ESSearchResponseView + ESRawSearchResponseView created
ESSearchResults / SearchResponse absent from components/schemas	✅ Fixed in this spike	Both view classes added to components
403 / 402 responses absent from both POST endpoints	✅ Fixed in this spike	Documented in @ApiResponses + YAML
@SwaggerCompliant not applied	✅ Fixed in this spike	Added @SwaggerCompliant(value = "Elasticsearch search tool APIs", batch = 3)
"Elasticsearch Content Search" absent from DotRestApplication global tags	✅ Fixed in this spike	Added alphabetically
License check not enforced at REST API level	⚠️ Behavior change — filed as #35385	JSP enforces STANDARD minimum; REST endpoints do not

---

Error shape reference for Angular FE

HTTP status	Trigger	Body shape
400	Invalid ES DSL JSON or invalid depth param	{ "error": "..." } via ExceptionMapperUtil
401	No authenticated session	JSON error from webResource.init
403	Permission denied on content (post-auth check)	JSON error — not currently documented at API level; can surface from content permission checks
402	License below STANDARD — currently not enforced at API level (filed as #35385)	To be added in #35385
5xx	Processing / ES cluster failure	Plain string via responseResource.responseError(msg)

---

Before / After comparison

Before PR #34778 (and before this spike)

tags:
- name: Elasticsearch Content Search  # tag existed but zero paths attached
paths: {}                              # /es/search and /es/raw absent
components/schemas: {}                 # ESSearchResults / SearchResponse not defined

After PR #34778 only

/es/search:
  post:
    requestBody: { schema: { type: string } }   # body type only, no description
    responses:
      "200": { schema: { type: object, description: "..." } }  # generic
      "400": {}
      "401": {}
/es/raw:
  post:
    # requestBody: MISSING
    responses:
      "200": { schema: { type: object, description: "..." } }  # generic
      "400": {}
      "401": {}

After this spike

/es/search:
  post:
    requestBody:
      description: "Elasticsearch DSL JSON query..."
      required: true
      content: { application/json: { schema: { type: string, example: "..." } } }
    responses:
      "200": { schema: { $ref: '#/components/schemas/ESSearchResponseView' } }
      "400": {}
      "401": {}
      "402": {}
      "403": {}
/es/raw:
  post:
    requestBody:
      description: "Elasticsearch DSL JSON query..."
      required: true
      content: { application/json: { schema: { type: string, example: "..." } } }
    responses:
      "200": { schema: { $ref: '#/components/schemas/ESRawSearchResponseView' } }
      "400": {}
      "401": {}
      "402": {}
      "403": {}
components:
  schemas:
    ESSearchResponseView:
      properties:
        contentlets: array of contentlet field maps
        esresponse: array of raw SearchResponse metadata
    ESRawSearchResponseView:
      properties:
        hits, took, timed_out, aggregations, suggest, _shards

---

API surface summary for Angular FE spec

POST /api/es/search
  Body:     Elasticsearch DSL JSON (string)
  Params:   ?depth=0|1|2|3  ?live=true|false  ?allCategoriesInfo=true|false
  200:      { contentlets: [...], esresponse: [{ hits, took, aggregations, suggest }] }
  Errors:   400 bad query | 401 no session | 403 perm denied | 402 license (pending #35385)

POST /api/es/raw
  Body:     Elasticsearch DSL JSON (string)
  200:      { hits, took, timed_out, aggregations, suggest, _shards }
  Errors:   400 bad query | 401 no session | 403 perm denied | 402 license (pending #35385)

Legacy endpoint NOT consumed by Angular:
  POST /api/portlet/es-search/render  → Dojo JSP form submit only

---

Child issues filed

• [Task] Add license check (STANDARD minimum) to /api/es/search and /api/es/raw #35385 — [Task] Add license check (STANDARD minimum) to /api/es/search and /api/es/raw (filed under Dojo to Angular: Backend API Updates #34292)

Files changed in this spike

File	Change
dotCMS/src/main/java/com/dotcms/rest/elasticsearch/ESContentResourcePortlet.java	@SwaggerCompliant, @RequestBody on both POST methods, typed @Schema impl, 403 + 402 responses
dotCMS/src/main/java/com/dotcms/rest/elasticsearch/ESSearchResponseView.java	New — search response schema class
dotCMS/src/main/java/com/dotcms/rest/elasticsearch/ESRawSearchResponseView.java	New — raw response schema class
dotCMS/src/main/java/com/dotcms/rest/config/DotRestApplication.java	Add "Elasticsearch Content Search" to global @OpenAPIDefinition tags
dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml	Updated ES endpoint sections + new schema components

---

Acceptance criteria check

• All 4 endpoints audited against both source code and openapi.yaml
• /api/es/search and /api/es/raw appear with complete request/response schemas
• ESSearchResponseView and ESRawSearchResponseView defined in components/schemas
• Error shape documented (400/401/403/402 — 402 enforcement filed as [Task] Add license check (STANDARD minimum) to /api/es/search and /api/es/raw #35385)
• Non-annotation change (license check) filed as [Task] Add license check (STANDARD minimum) to /api/es/search and /api/es/raw #35385 under Dojo to Angular: Backend API Updates #34292
• No BE behavior changed in this spike — annotations only