webapi
/webapi
Contract-first generator for Magento 2 REST / Web-API surfaces. Use to expose an existing entity over REST: add an endpoint, service contract, repository, or custom action. Generates webapi.xml, Api/ + Api/Data interfaces, a repository, di.xml, acl.xml, and API tests. Goes beyond magento2-tools:module-create's webapi stubs with SearchCriteria, per-route auth scopes, and extension attributes. Assumes the entity model already exists (from magento2-tools:module-create).
- Author
- muon-m2 ↗
- Repository
- magento2-tools ↗
- Licence
- MIT
- Last repository change
- 04.10.2026
Assessment and security
- Files in this package
- 15
- Scripts
- 5
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 5 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: templates/data-interface.php, templates/repository.php, templates/search-results-interface.php, templates/service-contract-interface.php, templates/test-webapi-functional.php
What it does and when to use it
Contract-first generator for Magento 2 REST / Web-API surfaces. Use to expose an existing entity over REST: add an endpoint, service contract, repository, or custom action. Generates webapi.xml, Api/ + Api/Data interfaces, a repository, di.xml, acl.xml, and API tests. Goes beyond magento2-tools:module-create's webapi stubs with SearchCriteria, per-route auth scopes, and extension attributes. Assumes the entity model already exists (from magento2-tools:module-create).
Original author description
Contract-first generator for Magento 2 REST / Web-API surfaces. Use to expose an existing entity over REST: add an endpoint, service contract, repository, or custom action. Generates webapi.xml, Api/ + Api/Data interfaces, a repository, di.xml, acl.xml, and API tests. Goes beyond magento2-tools:module-create's webapi stubs with SearchCriteria, per-route auth scopes, and extension attributes. Assumes the entity model already exists (from magento2-tools:module-create).
How it works
- Core Rules
- Workflow
- Inputs
- Outputs
- Reference Files
- Templates
- Acceptance Criteria
- Related Skills
SKILL.md preview
---
name: webapi
version: 1.0.3
description: >-
Contract-first generator for Magento 2 REST / Web-API surfaces. Use to expose an existing entity
over REST: add an endpoint, service contract, repository, or custom action. Generates webapi.xml,
Api/ + Api/Data interfaces, a repository, di.xml, acl.xml, and API tests. Goes beyond
magento2-tools:module-create's webapi stubs with SearchCriteria, per-route auth scopes, and
extension attributes. Assumes the entity model already exists (from magento2-tools:module-create).
---
# Magento 2 Web API Create
Contract-first REST / Web-API generation for an **existing** entity. Produces:
- `etc/webapi.xml` with CRUD routes (+ optional custom-action routes), each with an auth scope
- `Api/{Entity}RepositoryInterface` service contract (CRUD + any custom-action methods)
- `Api/Data/{Entity}Interface` + `Api/Data/{Entity}SearchResultsInterface` DTOs
- `Model/{Entity}Repository` full implementation (`SearchCriteria` via `CollectionProcessor`)
- `etc/di.xml` preferences and `etc/acl.xml` resources
- A Web-API functional test (`WebapiAbstract`) covering the GET/POST/PUT/DELETE round-trip
## Core Rules
- **Contract-first.** Decide the endpoint surface, DTO shape, and auth scope before writing the
implementation. The `Api/` interface is the contract; everything else implements it.
- **Assumes the entity exists.** This skill operates on the model / resource-model / `db_schema`
produced by `module-create`. If the entity model is absent, stop and run
`module-create` first — do **not** scaffold persistence here.
- **Auth on every route.** Each route declares a `<resources>` scope. ACL-protected is the
default; `self` for customer-scoped data; `anonymous` requires explicit justification (it
exposes the route publicly).
- **Throw framework exceptions.** Map failures to the right framework exception so the Web API
returns the correct HTTP status (`NoSuchEntityException` → 404, `CouldNotSaveException` → 400,
`LocalizedException` → 400). See `references/error-handling.md`.
- **Append, don't replace.** When `etc/webapi.xml`, `di.xml`, or `acl.xml` already exist (e.g.
module-create stubs), append/extend rather than overwrite. Report what is reused.
- **Literal `entity_id` PK.** The module-create entity uses the literal `entity_id` primary key;
this skill matches it (not the token `{entity}_id` used by the adminhtml form/listing pairing).
- **Coding style.** Generated PHP follows PER-CS 3.0 as the baseline, with the Magento 2 coding
standard taking precedence on any conflict; `--standard=Magento2` PHPCS is the gate. See
`context/references/php-coding-style.md`.
- **Source of truth.** Generate from templates → shared references → baked-in Magento 2 knowledge
→ official Magento/Adobe docs (live-fetched only when uncertain). Do NOT read, grep, or "study"
other modules under `app/code`/`vendor/*`/Magento core to infer conventions, entity shapes,
naming, or wiring. Narrow exceptions: the target module/class of this operation, and the specific
contract of a module this code explicitly depends on. Affirm sources in the final report. See
`context/references/source-of-truth.md`.
## Workflow
### Phase 0 — Context Resolution
Invoke `context` (vendor, runner, Magento root, version). Then detect the target entity:
- Locate `Model/{Entity}`, `Model/ResourceModel/{Entity}`, and any existing `Api/Data/{Entity}Interface`.
- If the entity **model is absent**, stop: instruct the user to run `module-create` first.
- Detect existing `etc/webapi.xml`, `etc/di.xml`, `etc/acl.xml`, `etc/extension_attributes.xml`,
and any partial `Api/` surface — these are **reused/extended**, not overwritten.
### Phase 1 — Contract Plan
Ask the user:
- Entity: the existing model being exposed.
- CRUD surface: confirm the five baseline routes (always generated):
`GET :id` → `getById`, `GET` → `getList`, `POST` → `save`, `PUT :id` → `save`,
`DELETE :id` → `deleteById`.
- Custom actions (optional): for each — name, HTTP method, URL, service method, auth scope.
e.g. `POST /V1/{route}/:entityId/activate → activate(int $entityId): {Entity}Interface`.
- Auth scope per route: `anonymous` | `self` | ACL-protected (default). See `references/auth-scopes.md`.
Produce the route table. See `references/service-contracts.md`.
### Phase 2 — DTO & Repository Plan
For the DTO and repository, decide:
- **Data interface** fields (constants + typed getters/setters) and extension-attribute accessors.
See `references/extension-attributes.md`.
- **Search-results interface** — narrowed `getItems()` returning `{Entity}Interface[]`.
- **Repository wiring** — resource model, collection factory, `CollectionProcessorInterface`,
`SearchResultsFactory`, entity factory. See `references/search-criteria.md`.
- **Custom-action bodies** — delegate non-trivial logic to a domain service; never bury business
logic in the repository.
Present the plan. Wait for approval.
### Phase 3 — Generate
- `Api/{Entity}RepositoryInterface.php` (CRUD + custom-action signatures).
- `Api/Data/{Entity}Interface.php`, `Api/Data/{Entity}SearchResultsInterface.php`.
- `Model/{Entity}Repository.php` (full implementation).
- `etc/webapi.xml` (routes + per-route `<resources>`), appended if the file exists.
- `etc/di.xml` — three preferences: `{Entity}Interface` → model, `{Entity}RepositoryInterface`
→ repository, `{Entity}SearchResultsInterface` → `Magento\Framework\Api\SearchResults`.
- `etc/acl.xml` — the resource tree the routes reference.
- `Test/Api/{Entity}RepositoryTest.php` (`WebapiAbstract` functional test).
### Phase 4 — Verify
- `php -l` on each generated `.php`; `xmllint --noout` on each generated XML.
- **Apply the shared module-hygiene baseline (required).** After generating or modifying PHP files, run
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/add-license-headers.sh {ctx.magento_root}/app/code/{Vendor}/{Module} {Vendor}`
to stamp the standard copyright header onto every new `.php` (idempotent — it skips files that already
carry it). When adding a `composer.json` `require` entry, resolve a **bounded** constraint via
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/resolve-dep-constraint.sh <vendor/package>` —
never `"*"`. See `context/references/module-hygiene.md`.
- Run `review --diff` on the module. **Gate: zero Critical/High.**
- Where a running Magento is available, suggest `setup:di:compile` as a smoke check (not required).
### Phase 5 — Report
Brief Markdown:
- Endpoints added (method, URL, service method, auth scope).
- Custom actions added.
- DTO fields + extension-attribute decisions.
- Test coverage delta and the run command.
- `review` verdict.
> **Docs may now be stale.** This change modified module code. Run
> `docs --module={Vendor}_{Module}` to refresh the module's README,
> CHANGELOG, and `docs/*.md` (technical reference, guides, and API references as
> applicable).
## Inputs
```
/webapi [--module=<Vendor>_<Module>] [--entity=<Entity>] [--auth=anonymous|self|acl]
```
Interactive flow drives the rest.
## Outputs
```
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/webapi.xml # created or appended
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/di.xml # created or merged
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/acl.xml # created or merged
{ctx.magento_root}/app/code/{Vendor}/{Module}/Api/{Entity}RepositoryInterface.php # new
{ctx.magento_root}/app/code/{Vendor}/{Module}/Api/Data/{Entity}Interface.php # new
{ctx.magento_root}/app/code/{Vendor}/{Module}/Api/Data/{Entity}SearchResultsInterface.php # new
{ctx.magento_root}/app/code/{Vendor}/{Module}/Model/{Entity}Repository.php # new
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Api/{Entity}RepositoryTest.php # new
```
## Reference Files
- `references/service-contracts.md` — repository pattern, `@api`, why interfaces live in `Api/`.
- `references/search-criteria.md` — `CollectionProcessor`, filter/sort/pagination, `SearchResultsFactory`.
- `references/auth-scopes.md` — anonymous / self / ACL scopes, integration tokens, when anonymous is OK.
- `references/error-handling.md` — exception → HTTP-status mapping; throw the right framework exception.
- `references/extension-attributes.md` — `extension_attributes.xml` and the generated extension interface.
- `references/webapi-testing.md` — `WebapiAbstract`, REST vs SOAP adapters, asserting status codes.
- `context/references/source-of-truth.md` — source-of-truth hierarchy + the
no-unrelated-module-scanning rule (allowed reads, live-doc fetch protocol, report affirmation).
## Templates
- `templates/service-contract-interface.php`
- `templates/data-interface.php`
- `templates/search-results-interface.php`
- `templates/repository.php`
- `templates/webapi.xml`
- `templates/di.xml`
- `templates/acl.xml`
- `templates/test-webapi-functional.php`
## Acceptance Criteria
- `webapi.xml` routes resolve to real service-contract methods; each route has a `<resources>` scope.
- The service contract is an `@api` interface under `Api/`; the DTO under `Api/Data/`.
- `getList` processes `SearchCriteria` through `CollectionProcessorInterface` (filters/sort/pagination).
- Failures throw the framework exception that maps to the correct HTTP status.
- Anonymous routes carry an explicit justification.
- The generated repository has at least one functional test (GET/POST/PUT/DELETE round-trip).
## Related Skills
| Phase | Skill |
|-------|-------|
| 0 | `context` |
| (prerequisite) | `module-create` (entity + persistence) |
| (after Phase 3) | `review --diff` |
| (after Phase 3) | `test-generate --types=api` |
| (caller) | `feature` Phase 5 (A* / API tasks) |
| (sibling) | `graphql` (GraphQL surface for the same entity) |
Files in this package (15)
- SKILL.md 10 KB
- references/auth-scopes.md 3 KB
- references/error-handling.md 3 KB
- references/extension-attributes.md 2 KB
- references/search-criteria.md 3 KB
- references/service-contracts.md 3 KB
- references/webapi-testing.md 3 KB
- templates/acl.xml 1 KB
- templates/data-interface.php 2 KB
- templates/di.xml 1 KB
- templates/repository.php 5 KB
- templates/search-results-interface.php 1 KB
- templates/service-contract-interface.php 3 KB
- templates/test-webapi-functional.php 4 KB
- templates/webapi.xml 3 KB
Versions
The database has no other skills named webapi.
Database snapshot: 13.11.2026 · package version 9be53e99c1cf (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100magento-api
Build Magento 2 REST and GraphQL APIs — webapi.xml, schema.graphqls, resolvers, authentication, and ACL. Use when creating custom API endpoints, extending the GraphQL schema, or integrating external systems. - 90magento-service-contracts
Implement Magento 2 service contracts — repository interfaces, data interfaces, SearchCriteria, and the repository pattern. Use when building module APIs, data access layers, or integrating with Magento's Web API. - 100indexer
Scaffold a custom Magento 2 indexer + materialized view (mview) on an existing module — `indexer.xml`, `mview.xml` subscriptions, an `ActionInterface` indexer (executeFull/executeList/executeRow) + Mview `ActionInterface` (execute), delegating to a batched action class. Use for… - 100system-config
Add admin store configuration to an existing module — system.xml section/group/field, config.xml defaults, ACL, optional source/backend models, plus a typed Config reader (ScopeConfigInterface wrapper with store-aware getters). Use for 'add a config field/toggle/API-key setting'… - 95add-ai-webapi
Integrates Power Pages generative-AI summarization APIs (PREVIEW) into a Single Page Application (SPA) site — the Search Summary API and the Data Summarization API — on any record-detail or list page. Generates per-target service code (CSRF-handled) and AI site settings;… - 86add-resource
Add a REST resource to this NestJS API end to end, as a feature module with its controller, service, DTOs, unit spec and contract tests. Use when asked for a new resource, endpoint, route or feature module.