add-api-endpoint

name	add-api-endpoint
description	Create API layer components for a new entity. Includes usecase interactors (internal/usecase/), proto definitions (schema/proto/), gRPC handlers (internal/infrastructure/grpc/), and DI registration. Use when adding CRUD endpoints or Step 3 of CRUD workflow (after add-domain-entity).

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