Mike Swanson
dd0ef45645
- Split CODING_GUIDELINES.md into 19 indexed standards files under .claude/standards/ - 9 from CODING_GUIDELINES (conventions, powershell, security, api, git, gururmm) - 10 from session log tribal knowledge (syncro, ssh, gitea, python, client, gururmm) - Add .claude/standards/index.yml for cheap relevance-based lookup - Add /inject-standards command: load targeted standards per task instead of full guidelines - Add /shape-spec command: pre-implementation spec for GuruRMM features (plan.md, shape.md, references.md, standards.md) with mandatory out-of-scope gate - Add docs/tech-stack.md and docs/mission.md for ClaudeTools API - Add projects/msp-tools/guru-rmm/docs/tech-stack.md and mission.md for GuruRMM - Update CLAUDE.md commands table with /inject-standards and /shape-spec Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
---
|
|
name: response-format
|
|
description: RESTful plural nouns, consistent error format, pagination, OpenAPI documentation
|
|
applies-to: claudetools-api, gururmm
|
|
---
|
|
|
|
# API Standards
|
|
|
|
## URL structure
|
|
|
|
- RESTful with plural nouns: `/api/users`, `/api/agents`, `/api/clients`
|
|
- Nested resources for sub-items: `/api/agents/:id/checks`, `/api/sites/:id/channel`
|
|
- Use kebab-case for multi-word segments: `/api/policy-assignments`, `/api/check-results`
|
|
|
|
## Error format
|
|
|
|
All error responses use a consistent envelope:
|
|
|
|
```json
|
|
{
|
|
"detail": "Human-readable error description",
|
|
"error_code": "MACHINE_READABLE_CODE",
|
|
"status_code": 404
|
|
}
|
|
```
|
|
|
|
- `detail` — for humans; may be shown in UI
|
|
- `error_code` — for client code to switch on; use `UPPER_SNAKE` format
|
|
- `status_code` — redundant with HTTP status but helps clients that lose the HTTP layer
|
|
|
|
## Pagination
|
|
|
|
Paginate all list endpoints that can return more than ~50 items. Use cursor-based or offset-based pagination:
|
|
|
|
```json
|
|
{
|
|
"items": [...],
|
|
"total": 148,
|
|
"page": 1,
|
|
"per_page": 25
|
|
}
|
|
```
|
|
|
|
Do not return unbounded arrays from production endpoints.
|
|
|
|
## Documentation
|
|
|
|
- Document with OpenAPI — FastAPI generates this automatically from type annotations and docstrings
|
|
- For Axum/Rust endpoints, add route comments with request/response shapes until an OpenAPI generator is wired
|
|
|
|
## sqlx query style (GuruRMM server)
|
|
|
|
Use `sqlx::query()` (runtime) not `sqlx::query!()` (compile-time macro) for new queries. The compile-time macro requires `cargo sqlx prepare` after every schema change and rebuilding the `.sqlx/` cache. Runtime queries avoid this overhead.
|
|
|
|
The offline cache (`server/.sqlx/`) only needs updating when `query!()` macros change. When adding a new query, default to `sqlx::query()` unless there is a specific reason to use the proc macro.
|
|
|
|
## Migration discipline (GuruRMM)
|
|
|
|
- Never manually pre-apply migrations via psql without also recording the checksum in `_sqlx_migrations` — sqlx will fail on startup if it finds a missing row for a migration it doesn't recognize
|
|
- Use `ADD COLUMN IF NOT EXISTS` in all migrations so they are idempotent
|
|
- Apply migrations by letting the server binary run them on startup (`sqlx::migrate!()`)
|
|
- The correct sequence for a new migration: add SQL file → apply to DB (server startup) → `cargo sqlx prepare` → commit `.sqlx/` → rebuild
|