Repository: lopeztech/home-plant-tracker
Author: lopeztech
## Summary
Expose a documented public REST API with API key authentication, allowing Pro users to integrate plant data with external tools (home automation, custom dashboards, irrigation systems).
## Target users
- **Tech-savvy home growers** who want to integrate with Home Assistant, smart irrigation controllers, or custom dashboards
- **Landscapers** who want to connect with their existing business tools (CRM, invoicing, scheduling software)
## Motivation
API access is a proven monetisation lever for SaaS products. It opens integration possibilities without requiring first-party development, and positions the app as a platform rather than a standalone tool. It's also low-effort to implement since the internal API already exists — this is primarily about auth, rate limiting, and documentation.
## Proposed work
### API key management
- New routes:
- `POST /api-keys` — generate a new API key (max 3 per user)
- `GET /api-keys` — list active API keys (masked)
- `DELETE /api-keys/:id` — revoke an API key
- API keys stored as hashed values in Firestore: `users/{userId}/apiKeys/{keyId}`
- Auth: accept `x-api-key` header on all public API routes (in addition to existing JWT auth)
### Public API surface
Expose a subset of existing routes for external consumption:
- `GET /api/v1/plants` — list plants
- `GET /api/v1/plants/:id` — get plant details
- `POST /api/v1/plants/:id/water` — log a watering event
- `GET /api/v1/plants/:id/care-score` — get care score
- `GET /api/v1/plants/:id/watering-recommendation` — get watering recommendation
- `GET /api/v1/notifications` — get recent notifications (for polling)
### Rate limiting
- Free: no API access
- Home Pro: 100 requests/hour
- Landscaper Pro: 1,000 requests/hour
### Documentation
- Auto-generated OpenAPI 3.0 spec from route definitions
- Hosted API docs page (Swagger UI or Redoc) at `/docs`
- Code examples in cURL, Python, JavaScript, and Home Assistant YAML
## Acceptance criteria
- [ ] API key generation, listing, and revocation works
- [ ] API key auth accepted on all public API routes
- [ ] Tier-based rate limiting enforced
- [ ] OpenAPI 3.0 spec auto-generated and accurate
- [ ] API docs page accessible at `/docs`
- [ ] Code examples work as documented
- [ ] Unit tests for API key auth, rate limiting, and all public routes
## Technical notes
- API key format: `pt_live_{32 random chars}` (prefix for easy identification in logs)
- Store SHA-256 hash of key in Firestore, not the plaintext — key is only shown once at creation time
- Rate limiting: use `express-rate-limit` with Firestore or Redis backing (Firestore simpler, Redis faster)
- Versioned API path (`/api/v1/`) to allow breaking changes in future versions
- Consider webhook support (future): push events to user-defined URLs on watering, health change, etc.
- Home Assistant integration: a custom component that polls the API would be a great community contribution / marketing asset
- Depends on: Stripe billing, feature gating