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:

1. Which feature? (List from features/)
2. Endpoint type? (Report, Search, Action, Aggregation, Utility, Small Entity, Custom)
3. Specific endpoint? (HTTP method + path, e.g., GET /users/statistics)
4. 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
5. Operation/handler name?
6. Purpose? (What data/action?)
7. Input required? (URL params, query params, body, headers)
8. Return type? (Single object, array, paginated list, success message, file)
9. Business logic? (queries, calculations, external calls)
10. External services? (email, storage, queue, cache)
11. Authorization? (public, authenticated, role-based, permission-based)
12. New repository methods? (queries, aggregations)
13. Modifies data? (read-only vs write operations)

Present plan and confirm before implementation.

Implementation Phases

Execute these 8 phases:

1. Create DTOs - phases/add-endpoint/01-create-dtos.md
2. Repository Methods - phases/add-endpoint/02-repository-methods.md
3. Service Methods - phases/add-endpoint/03-service-methods.md
4. HTTP Handlers - phases/add-endpoint/04-http-handlers.md
5. Register Routes - phases/add-endpoint/05-register-routes.md
6. Testing - phases/add-endpoint/06-testing.md
7. Code Quality - phases/shared/code-quality.md
8. 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