3.8 KiB
3.8 KiB
description
| description |
|---|
| Add lightweight endpoint without full entity infrastructure |
Add Endpoint/Handler
Add new HTTP endpoints to an existing feature without creating full entity infrastructure.
When to Use
Use this when:
- Adding report/analytics endpoints (statistics, dashboards)
- Adding search/filter endpoints (advanced search, autocomplete)
- Adding action endpoints (approve, cancel, activate)
- Adding aggregation endpoints (totals, counts, summaries)
- Adding small entities without full CRUD (comments, tags, notes)
- Adding utility endpoints (export, import, validate)
Don't use when:
- Creating new feature → Use
/venturo-go:new-feature - Adding full entity with CRUD → Use
/venturo-go:add-entity
Workflow
Interactive Discovery
Ask these questions:
- Which feature? (List from
features/) - Endpoint type? (Report, Search, Action, Aggregation, Utility, Small Entity, Custom)
- Specific endpoint? (HTTP method + path, e.g.,
GET /users/statistics) - Related to entity or feature-general?
- Entity-specific (user statistics) → Add to existing handler
- Feature-general (dashboard) → Create new handler
- Operation-specific (bulk import) → Dedicated handler
- Operation/handler name?
- Purpose? (What data/action?)
- Input required? (URL params, query params, body, headers)
- Return type? (Single object, array, paginated list, success message, file)
- Business logic? (queries, calculations, external calls)
- External services? (email, storage, queue, cache)
- Authorization? (public, authenticated, role-based, permission-based)
- New repository methods? (queries, aggregations)
- Modifies data? (read-only vs write operations)
Present plan and confirm before implementation.
Implementation Phases
Execute these 8 phases:
- Create DTOs -
phases/add-endpoint/01-create-dtos.md - Repository Methods -
phases/add-endpoint/02-repository-methods.md - Service Methods -
phases/add-endpoint/03-service-methods.md - HTTP Handlers -
phases/add-endpoint/04-http-handlers.md - Register Routes -
phases/add-endpoint/05-register-routes.md - Testing -
phases/add-endpoint/06-testing.md - Code Quality -
phases/shared/code-quality.md - Documentation -
phases/shared/documentation.md
Common Endpoint Patterns
Report/Analytics:
GET /users/statistics?from_date=...&to_date=...
GET /dashboard/summary
- Query parameters for filters
- Aggregated data response
- Read-only, often cached
Search/Filter:
GET /products/search?q=keyword&category=...
POST /orders/advanced-filter
- Search criteria in query or body
- Paginated results
Action/Command:
POST /orders/:id/cancel
POST /users/:id/activate
- URL parameter for resource ID
- Body for action parameters
- Modifies state, idempotent
Aggregation:
GET /sales/totals?group_by=month
GET /inventory/summary
- Computed/derived data
- Grouping and filtering
Utility:
POST /users/export (returns file)
POST /products/import (accepts file)
- File upload/download
- Batch operations
Example
User: /venturo-go:add-endpoint
Claude: Which feature?
User: user_management
Claude: Endpoint type?
User: Report/Analytics
Claude: Specific endpoint?
User: GET /users/statistics
Claude: Related to user entity or feature-general?
User: Entity-specific (user)
Claude: What data should statistics return?
User: Total users, active users, new registrations this month, users by role
[Presents plan, proceeds with phases]
Tips
- Keep it focused (one endpoint = one responsibility)
- Reuse existing repository/service methods
- Validate input with binding tags
- Consider caching for expensive operations
- Think about performance and scale
- Apply proper authentication
- Test edge cases