# REST API Validator

> Validates Alfresco v1 Public REST API resources for correct annotations (@EntityResource / @RelationshipResource), required @WebApiDescription on every action method, a single @UniqueId on the model POJO, paged collection returns, and absence of classic Web Script anti-patterns. Trigger automatically after generating or editing files under a rest/ package or any class annotated @EntityResource / @RelationshipResource.

- Skill: `aborroy/rest-api-validator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aborroy/rest-api-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aborroy/rest-api-validator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aborroy (https://skillmd.com/u/aborroy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aborroy/rest-api-validator

---


# REST API Validator

Validate the given Alfresco v1 Public REST API resources against these rules. This is the
modern annotation-based framework (`org.alfresco.rest.framework`), not classic Web Scripts.

## Annotation Validation
- Every entity resource class must be annotated `@EntityResource(name = "...", title = "...")`.
- Every relationship resource class must be annotated
  `@RelationshipResource(name = "...", entityResource = X.class, title = "...")`, and its
  `entityResource` must reference an existing `@EntityResource`-annotated class in the project.
- The `name` on both annotations must be **plural, kebab-case** (e.g. `vendor-contracts`,
  `payments`) and contain no verbs.

## Action Method Validation
- The resource class must implement at least one interface from
  `org.alfresco.rest.framework.resource.actions.interfaces` —
  `EntityResourceAction.Read` / `ReadById` / `Create` / `Update` / `Delete`, or
  `RelationshipResourceAction.Read` / `Create` / `Update` / `Delete`.
- **FLAG as ERROR** any public action method (`readAll`, `readById`, `create`, `update`,
  `delete`) that is **missing `@WebApiDescription`**.
  - **Why it breaks**: the framework only maps annotated methods. An unannotated action method
    is silently unreachable and the operation returns `405 Method Not Allowed`.
  - **Fix**: add `@WebApiDescription(title = "…")` to every action method.
- A `readAll` method must return `CollectionWithPagingInfo<T>` — **FLAG as ERROR** a raw
  `List<T>` / `Collection<T>` return (bypasses the paging envelope).

## Model POJO Validation
- The returned/consumed model POJO must have **exactly one** getter annotated `@UniqueId`.
  - **FLAG as ERROR** zero `@UniqueId` getters (framework cannot build `readById` / serialise id).
  - **FLAG as ERROR** more than one `@UniqueId` getter (ambiguous identifier).
- The POJO should be a plain JavaBean: public no-arg constructor, getters/setters, no Alfresco
  service fields.

## Forbidden Patterns
- **FLAG as ERROR** a resource class that `extends DeclarativeWebScript` — that is the classic
  framework and will not be discovered by `ResourceLookupDictionary`.
- **FLAG as ERROR** `@Autowired` — use setter injection wired in `webscript-context.xml`.
- **WARN** if `@PostConstruct` or `@Transactional` appears on a resource class.

## Spring Registration Validation
- Each resource should be registered as a `<bean>` in `webscript-context.xml`
  (bean id `{prefix}.{entity}EntityResource` / `{prefix}.{entity}{Relationship}RelationshipResource`),
  and `webscript-context.xml` should be imported from `module-context.xml`.
- A resource bean needs **no parent bean** — flag a `parent="..."` on a resource bean as
  likely incorrect.

## Output
Report all violations with file path, line number, rule violated, and suggested fix. If no
violations found, confirm the REST API resources are valid.