2026-10-13 16:47:41 +08:00
|
|
|
---
|
|
|
|
|
name: api-design
|
|
|
|
|
description: >
|
2026-10-30 12:40:16 +08:00
|
|
|
Design or modify API routes, validated request/response schemas, error contracts, and API documentation within the existing project stack.
|
|
|
|
|
scope: global
|
2026-10-13 16:47:41 +08:00
|
|
|
---
|
|
|
|
|
|
2026-10-30 12:40:16 +08:00
|
|
|
# API design
|
2026-10-13 16:47:41 +08:00
|
|
|
|
2026-10-30 12:40:16 +08:00
|
|
|
1. Inspect the existing transport, schema library, auth, and error conventions.
|
|
|
|
|
Keep domain logic independent of HTTP/framework request objects where practical.
|
|
|
|
|
2. Define inputs, outputs, status codes, authorization, and meaningful payload limits.
|
|
|
|
|
Use runtime validation at untrusted boundaries; TypeScript interfaces alone do
|
|
|
|
|
not validate requests. Derive limits from product needs and resource budgets.
|
|
|
|
|
3. Implement the route using existing services and data access patterns. Reuse
|
|
|
|
|
existing dependency injection; do not introduce layers or repositories by default.
|
|
|
|
|
4. Preserve HTTP semantics and the project's error shape. Use Problem Details
|
|
|
|
|
when adopting that format; otherwise document the existing structured contract.
|
|
|
|
|
Serialize timestamps consistently with explicit timezone information.
|
|
|
|
|
5. Verify changed contracts and failure behavior under
|
|
|
|
|
[shared verification](../../protocols/workflow.md#verification).
|
2026-10-13 16:47:41 +08:00
|
|
|
|
2026-10-30 12:40:16 +08:00
|
|
|
Read [security guidance](../app-security/SKILL.md) for affected untrusted boundaries,
|
|
|
|
|
not as a mandatory second audit. Validation and authorization failures reject the
|
|
|
|
|
request. A dependency fallback requires an explicit behavior contract; never infer
|
|
|
|
|
"fail open" merely because an endpoint is internal.
|
