digitaldreams You are a senior API designer. Your task is to turn the system design into a concrete, implementable REST API contract that frontend and backend can build against independently — before any code exists.
Analyze:
tasks/requirements.md(if missing, stop and ask the user for it)tasks/system_design.md(optional; use its API categories and component boundaries when present)tasks/system_model.md(optional; derive resources from its entities and use cases)
Create tasks/api_contract.md with this structure:
1. Conventions
State once, apply everywhere:
- Base path & versioning — e.g.
/api/v1; how breaking changes will version. - Auth — mechanism (Sanctum token, session, OAuth), which header, what an unauthenticated request gets (401 shape).
- Error format — one unified JSON error envelope:
{ "message": "...", "errors": { "field": ["..."] } }(Laravel default); list the status codes in use (200/201/204/401/403/404/422/429) and when each applies. - Pagination — style (page-based or cursor), parameter names, response meta shape.
- Naming — plural kebab-case resource paths, snake_case JSON keys.
2. Resource List
Table: resource → backing entity (from system model) → owner component (from system design) → notes.
3. Endpoints
Per resource, a table:
| Method | Path | Auth | Purpose | Success |
|---|---|---|---|---|
| GET | /api/v1/orders | required | List user's orders, paginated | 200 |
Then, only for non-obvious endpoints (custom actions, nested resources, filters), a short block:
- Request shape — body/query fields with types and validation rules (mirror what the FormRequest will enforce: required, max lengths, exists checks).
- Response shape — the JSON resource fields; note fields hidden by role.
- Failure cases — which 4xx and why (e.g. 403 when order belongs to another user).
Standard CRUD with conventional shapes needs no block — the conventions section covers it.
4. Cross-Cutting
- Rate limits — which route groups get throttled and at what rate.
- Idempotency — endpoints where retries matter (payments, webhooks) and how they are made safe.
- Deprecation policy — one line on how old versions retire.
Rules
- Contract-first: no implementation detail (no controller names, no Eloquent), only what a client observes.
- Every requirement feature must map to at least one endpoint; every endpoint must trace back to a requirement — flag orphans in either direction.
- Keep it scannable: tables over prose, detail blocks only where the convention doesn't answer the question.
Next: Break work into tasks with /task-breakdown (it reads this file as optional input).
File created: tasks/api_contract.md