add-api-endpoint

Create complete API layer: usecase interactors, proto definitions, gRPC handlers, and DI registration.

Prerequisites

• Domain entity created (use add-domain-entity skill first)
• Repository interface and implementation ready
• SQLBoiler models generated (make migrate.up)

Workflow Overview

1. Usecase Input/Output  -->  internal/usecase/input/, output/
2. Interactor Interface  -->  internal/usecase/{actor}_{entity}.go
3. Interactor Impl       -->  internal/usecase/{actor}_{entity}_impl.go
4. Proto Definition      -->  schema/proto/rapid/{actor}_api/v1/
5. Generate Proto        -->  make generate.buf
6. Handler Marshaller    -->  handler/{actor}/marshaller/{entity}.go
7. Handler Methods       -->  handler/{actor}/{entity}.go
8. Update Handler Struct -->  handler/{actor}/handler.go
9. Register in DI        -->  dependency/dependency.go
10. Generate & Test      -->  make generate.mock && make test

Step 1: Create Usecase Input/Output

Location: internal/usecase/input/{actor}_{entity}.go

Create input structs for each operation (Create, Get, List, Update, Delete). Each struct needs a Validate() method.

See: references/usecase-patterns.md

Location: internal/usecase/output/{actor}_{entity}.go

Create output struct only for List operations (returns slice + count).

See: references/usecase-patterns.md

Step 2: Create Interactor Interface

Location: internal/usecase/{actor}_{entity}.go

Define interface with //go:generate directive for mock generation.

See: references/usecase-patterns.md

Step 3: Implement Interactor

Location: internal/usecase/{actor}_{entity}_impl.go

Implement CRUD methods following transaction patterns:

• Create: Validate -> Create entity -> RWTx -> Get with Preload
• Get: Validate -> Get with Preload
• List: Validate -> List + Count with Preload
• Update: Validate -> RWTx(Get ForUpdate -> Update) -> Get with Preload
• Delete: Validate -> RWTx(Get ForUpdate -> Delete)

See: references/usecase-patterns.md

Step 4: Define Protocol Buffers

Create two files:

• Model/Enum: schema/proto/rapid/{actor}_api/v1/model_{entity}.proto
• Request/Response: schema/proto/rapid/{actor}_api/v1/api_{entity}.proto

Then add RPCs to: schema/proto/rapid/{actor}_api/v1/api.proto

See: references/proto-patterns.md

Step 5: Generate Proto Code

make generate.buf

Step 6: Create Handler Marshaller

Location: internal/infrastructure/grpc/internal/handler/{actor}/marshaller/{entity}.go

Convert between domain models and proto messages.

See: references/handler-patterns.md

Step 7: Create Handler Methods

Location: internal/infrastructure/grpc/internal/handler/{actor}/{entity}.go

Implement gRPC handler methods that delegate to interactors.

See: references/handler-patterns.md

Step 8: Update Handler Struct

Location: internal/infrastructure/grpc/internal/handler/{actor}/handler.go

Add new interactor field and constructor parameter.

See: references/handler-patterns.md

Step 9: Register in DI

Location: internal/infrastructure/dependency/dependency.go

1. Add interactor field to Dependency struct
2. Initialize repository and interactor in Inject() method
3. Update grpc/run.go to pass interactor to handler constructor

See: references/handler-patterns.md

Step 10: Generate Mocks & Test

make generate.mock
make test

Checklist

• [ ] Input structs with Validate() method
• [ ] Output struct for List operation
• [ ] Interactor interface with //go:generate
• [ ] Interactor implementation with proper transaction handling
• [ ] Proto model/enum definitions
• [ ] Proto request/response messages with openapiv2_schema
• [ ] Proto service RPCs with HTTP annotations
• [ ] Proto code generated (make generate.buf)
• [ ] Handler marshaller (both directions + enums)
• [ ] Handler methods
• [ ] Handler struct updated
• [ ] DI configuration updated
• [ ] Mocks generated (make generate.mock)
• [ ] Tests passing (make test)

Common Errors

| Error | Solution | |-------|----------| | undefined: pb.Example | Run make generate.buf | | undefined: mock_usecase.MockAdminExampleInteractor | Run make generate.mock | | Handler method not found | Check handler struct field name and interface registration |