Skip to content
Skills Library
Programming · Building & coding

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).

Licence
MIT
Last repository change
04.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
5
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Core Rules
  2. Workflow
  3. Inputs
  4. Outputs
  5. Reference Files
  6. Templates
  7. Acceptance Criteria
  8. Related Skills
Original SKILL.md headings · 174 lines, 1,058 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.