ZacharyZhang-NY
e74dafcd36
Three independently ugly bugs that all fed the same log flood:
* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
to stderr via `console.error`. When the worker fans a second
agent-event past a reloading renderer, we produced thousands of
identical lines and stalled the main loop on stderr I/O. Added a
`mainFrame.detached` guard so the send is short-circuited before
Electron's own catch block fires, and installed a targeted filter in
`suppress-warnings.ts` (now actually imported from the entry point)
so the specific `console.error("Error sending from webFrameMain:"…)`
noise never reaches the terminal. Any other payload still surfaces.
* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
target when an agent replied to `__board__` — `wakeAgentIfPossible`
then called `db.getAgent("__board__")`, threw, and the dispatcher
kept repeating on every send. Strip `HUMAN_SENDER_ID` at
`resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
heartbeat so a stray caller (future automation fan-out) cannot
reintroduce the crash.
* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
diverges from its parent directory. The four bundled `my-writing-style`
copies declared `name: writing-style-skill`, so every install emitted
a warning and dropped the skill. They also lived as orphan gitlinks
(mode 160000 without .gitmodules), and the global `*.md` gitignore
hid every other SKILL.md from version control. Fixed the frontmatter
to match the dir, converted the dangling submodules to plain trees,
and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
catalogue instead of silently losing it.
156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# API Design Checklist
|
|
|
|
## Pre-Implementation Review
|
|
|
|
### Resource Design
|
|
|
|
- [ ] Resources are nouns, not verbs
|
|
- [ ] Plural names for collections
|
|
- [ ] Consistent naming across all endpoints
|
|
- [ ] Clear resource hierarchy (avoid deep nesting >2 levels)
|
|
- [ ] All CRUD operations properly mapped to HTTP methods
|
|
|
|
### HTTP Methods
|
|
|
|
- [ ] GET for retrieval (safe, idempotent)
|
|
- [ ] POST for creation
|
|
- [ ] PUT for full replacement (idempotent)
|
|
- [ ] PATCH for partial updates
|
|
- [ ] DELETE for removal (idempotent)
|
|
|
|
### Status Codes
|
|
|
|
- [ ] 200 OK for successful GET/PATCH/PUT
|
|
- [ ] 201 Created for POST
|
|
- [ ] 204 No Content for DELETE
|
|
- [ ] 400 Bad Request for malformed requests
|
|
- [ ] 401 Unauthorized for missing auth
|
|
- [ ] 403 Forbidden for insufficient permissions
|
|
- [ ] 404 Not Found for missing resources
|
|
- [ ] 422 Unprocessable Entity for validation errors
|
|
- [ ] 429 Too Many Requests for rate limiting
|
|
- [ ] 500 Internal Server Error for server issues
|
|
|
|
### Pagination
|
|
|
|
- [ ] All collection endpoints paginated
|
|
- [ ] Default page size defined (e.g., 20)
|
|
- [ ] Maximum page size enforced (e.g., 100)
|
|
- [ ] Pagination metadata included (total, pages, etc.)
|
|
- [ ] Cursor-based or offset-based pattern chosen
|
|
|
|
### Filtering & Sorting
|
|
|
|
- [ ] Query parameters for filtering
|
|
- [ ] Sort parameter supported
|
|
- [ ] Search parameter for full-text search
|
|
- [ ] Field selection supported (sparse fieldsets)
|
|
|
|
### Versioning
|
|
|
|
- [ ] Versioning strategy defined (URL/header/query)
|
|
- [ ] Version included in all endpoints
|
|
- [ ] Deprecation policy documented
|
|
|
|
### Error Handling
|
|
|
|
- [ ] Consistent error response format
|
|
- [ ] Detailed error messages
|
|
- [ ] Field-level validation errors
|
|
- [ ] Error codes for client handling
|
|
- [ ] Timestamps in error responses
|
|
|
|
### Authentication & Authorization
|
|
|
|
- [ ] Authentication method defined (Bearer token, API key)
|
|
- [ ] Authorization checks on all endpoints
|
|
- [ ] 401 vs 403 used correctly
|
|
- [ ] Token expiration handled
|
|
|
|
### Rate Limiting
|
|
|
|
- [ ] Rate limits defined per endpoint/user
|
|
- [ ] Rate limit headers included
|
|
- [ ] 429 status code for exceeded limits
|
|
- [ ] Retry-After header provided
|
|
|
|
### Documentation
|
|
|
|
- [ ] OpenAPI/Swagger spec generated
|
|
- [ ] All endpoints documented
|
|
- [ ] Request/response examples provided
|
|
- [ ] Error responses documented
|
|
- [ ] Authentication flow documented
|
|
|
|
### Testing
|
|
|
|
- [ ] Unit tests for business logic
|
|
- [ ] Integration tests for endpoints
|
|
- [ ] Error scenarios tested
|
|
- [ ] Edge cases covered
|
|
- [ ] Performance tests for heavy endpoints
|
|
|
|
### Security
|
|
|
|
- [ ] Input validation on all fields
|
|
- [ ] SQL injection prevention
|
|
- [ ] XSS prevention
|
|
- [ ] CORS configured correctly
|
|
- [ ] HTTPS enforced
|
|
- [ ] Sensitive data not in URLs
|
|
- [ ] No secrets in responses
|
|
|
|
### Performance
|
|
|
|
- [ ] Database queries optimized
|
|
- [ ] N+1 queries prevented
|
|
- [ ] Caching strategy defined
|
|
- [ ] Cache headers set appropriately
|
|
- [ ] Large responses paginated
|
|
|
|
### Monitoring
|
|
|
|
- [ ] Logging implemented
|
|
- [ ] Error tracking configured
|
|
- [ ] Performance metrics collected
|
|
- [ ] Health check endpoint available
|
|
- [ ] Alerts configured for errors
|
|
|
|
## GraphQL-Specific Checks
|
|
|
|
### Schema Design
|
|
|
|
- [ ] Schema-first approach used
|
|
- [ ] Types properly defined
|
|
- [ ] Non-null vs nullable decided
|
|
- [ ] Interfaces/unions used appropriately
|
|
- [ ] Custom scalars defined
|
|
|
|
### Queries
|
|
|
|
- [ ] Query depth limiting
|
|
- [ ] Query complexity analysis
|
|
- [ ] DataLoaders prevent N+1
|
|
- [ ] Pagination pattern chosen (Relay/offset)
|
|
|
|
### Mutations
|
|
|
|
- [ ] Input types defined
|
|
- [ ] Payload types with errors
|
|
- [ ] Optimistic response support
|
|
- [ ] Idempotency considered
|
|
|
|
### Performance
|
|
|
|
- [ ] DataLoader for all relationships
|
|
- [ ] Query batching enabled
|
|
- [ ] Persisted queries considered
|
|
- [ ] Response caching implemented
|
|
|
|
### Documentation
|
|
|
|
- [ ] All fields documented
|
|
- [ ] Deprecations marked
|
|
- [ ] Examples provided
|
|
- [ ] Schema introspection enabled
|