Instruction file imported from bigeomaha/templates-spa-react-node (
.github/instructions/feature-apis.instructions.md). Copyright stays with the author.
Feature API requirements
Required flags block
FLAGS:
API_CHANGES = TRUE | FALSE
EXTERNAL_APIS = TRUE | FALSE
APPROVED = FALSE
Section 1 — Internal endpoints (if API_CHANGES=TRUE)
Required per endpoint:
### [METHOD] [full path]
Auth level: public | protected | protected/me | admin
Body: { field: type } | none
Params: { id: uuid } | none
Query: { field: type } | none
Schema: ZodSchemaName | none
Response 200: { success: true, data: IType }
Response 400: { success: false, error: { code: 'VALIDATION_ERROR' } }
[all error responses]
Rate limited: YES — n req/window per IP|user | NO — reason
Auth endpoints (/api/public/auth/*): always rate limited. Every endpoint documents ALL response codes — never happy path only. Auth level must match route folder exactly.
Section 2 — External APIs (if EXTERNAL_APIS=TRUE)
Required per service:
Service + docs URL
Auth: env var name (must be in .env.example)
Endpoint: METHOD + path
Request/response shapes (only fields we use)
Rate limits: limits + strategy + backoff
Cost: per-unit rate + expected volume
Error handling: every error code → action
Circuit breaker: threshold + behavior + client message
SDKs/packages: listed in feature.plan dependencies + audited in feature.security. External section = HTTP contracts only.
INVALID if:
- Any endpoint missing auth level or rate limiting decision
- Auth level doesn't match route folder
- Any endpoint happy path only
- Any external service missing error handling or circuit breaker
- External API key not in .env.example