new-endpoint - SKILL.md Agent Skill

name: new-endpoint description: Scaffold a new REST endpoint in headless-delivery-ext — guides through adding path/schema to rest-openapi.yaml, running buildREST, and implementing the generated method in the ResourceImpl disable-model-invocation: true

New Endpoint Scaffold

Before you start

Locate the impl module and impl class to edit:

find modules -name "rest-openapi.yaml" | head -3
find modules -name "*ResourceImpl.java" | head -5

Confirm the endpoint belongs to an existing resource (ContentStructureResource, ContentTemplateResource) or identify the correct impl class.

Step 1 — Add path + schema to rest-openapi.yaml

Open modules/headless-delivery-ext/headless-delivery-ext-impl/rest-openapi.yaml.

Under paths:, add the new path block:

Use {param:.+} (not {param}) for path parameters that may contain slashes
Match parameter names exactly between paths: and the Java method signature
Define any new request/response schemas under components/schemas:

Step 2 — Regenerate the REST Builder output

blade gw buildREST -p modules/headless-delivery-ext/headless-delivery-ext-impl

Check for errors. The generated interface appears in headless-delivery-ext-api/src/.

Step 3 — Verify post-generation patches applied

build.gradle post-processes generated code. Check the output of:

grep -r ":.+" modules/headless-delivery-ext/headless-delivery-ext-api/src/ | grep "@Path"

Regex-form path params ({param:.+}) must be present for any param that may contain slashes. If missing, check build.gradle patch logic.

Step 4 — Implement in ResourceImpl

Open the relevant *ResourceImpl.java in headless-delivery-ext-impl/src/main/java/.

Find the newly generated @Override method stub (it throws UnsupportedOperationException by default) and implement it.

Step 5 — Compile and verify

blade gw compileJava -p modules/headless-delivery-ext/headless-delivery-ext-impl

Fix any compilation errors. Then deploy and run the Postman smoke test:

blade gw deploy -p modules/headless-delivery-ext
newman run postman/headless-delivery-ext-integration-test.postman_collection.json \
  -e postman/liferay-localhost.postman_environment.json \
  --folder Structures --bail --timeout-request 5000