diff --git a/.sdlc/features/add-hello-endpoint/spec.md b/.sdlc/features/add-hello-endpoint/spec.md new file mode 100644 index 0000000..00efdad --- /dev/null +++ b/.sdlc/features/add-hello-endpoint/spec.md @@ -0,0 +1,60 @@ +# Feature: Add /hello endpoint to API service + +## Problem Statement + +The API service currently lacks a simple, unauthenticated endpoint that can be used for: +1. Basic connectivity testing by clients during development and debugging +2. Quick verification that the API is reachable and responding correctly +3. A minimal example endpoint for onboarding new developers to the codebase patterns + +While `/api/v1/health` exists, it is designed for infrastructure health checks (liveness/readiness probes) rather than application-level connectivity testing by end users or client applications. + +## User Stories + +- As a **frontend developer**, I want a simple `/hello` endpoint so that I can quickly verify my client is correctly configured to call the API +- As a **new team member**, I want to see a minimal handler implementation so that I can understand the codebase patterns before building more complex endpoints +- As a **QA engineer**, I want a simple endpoint that returns predictable data so that I can use it in integration test smoke checks + +## Acceptance Criteria + +- [ ] `GET /api/v1/hello` returns HTTP 200 with a JSON response +- [ ] Response body follows the standard `{data, meta}` envelope pattern +- [ ] Response `data` contains at minimum a `message` field with value `"Hello, World!"` +- [ ] Endpoint does NOT require authentication (public route) +- [ ] Endpoint is documented in OpenAPI spec with appropriate tags and response schema +- [ ] Handler follows the `app.Wrap()` pattern for error-returning handlers +- [ ] Handler has unit tests with at least one happy-path test case +- [ ] Response includes `request_id` in meta (automatically via middleware) + +## Technical Constraints + +- Must follow existing patterns in `services/api/internal/api/handlers/` +- Must use `httpresponse.OK()` for the response (not bare `json.Encoder`) +- OpenAPI spec must be updated in `services/api/internal/api/spec.go` +- Route must be registered in `services/api/internal/api/routes.go` +- No new dependencies required + +## Dependencies + +- Existing `pkg/app`, `pkg/httpresponse`, and `pkg/openapi` packages (already in place) +- API service scaffold (already exists at `services/api/`) + +## Out of Scope + +- Parameterized greeting (e.g., `/hello/{name}`) - keep it simple +- Localization of the greeting message +- Rate limiting specific to this endpoint +- Any database or external service calls +- Authentication variants (authenticated hello) + +## Open Questions + +1. **Response payload**: Should the response include additional fields beyond `message`? For example: + - `timestamp` - current server time + - `version` - API version string + + _Recommendation: Keep it minimal with just `message` to match the feature's purpose as a simple connectivity check._ + +2. **Tag grouping**: Should this endpoint have its own OpenAPI tag (e.g., "Hello") or be grouped under "Health"? + + _Recommendation: Use a dedicated "Hello" tag to distinguish it from infrastructure health checks._