用途：在设计与评审 HTTP、REST、JSON、Webhook 或 OpenAPI 描述时触发，覆盖内部或外部消费者。适合资源、方法、状态、错误、分页、幂等、并发、认证与兼容性决策；若为 RPC 或事件，先确认真实合约风格再决定，不要强行按 HTTP 资源处理。威胁建模、凭据、滥用与信任边界建议配合 $specsfy-specialist-application-security。
流程：先发现消费者、用例、既有风格、流量、延迟、可用性、信任边界与兼容策略；再建模资源、身份、关系、不变量与归属，避免把内部表或对象直接当合约暴露；定义操作、schema、头部、状态与 Problem Details，并记录每个操作的 retry 语义（见 references/standards.md）；在实现处理器前设计认证、按资源或租户授权、幂等、前置条件与并发；规定分页、过滤、确定性排序、限制、限流及数据变动行为；产出 OpenAPI/JSON Schema 与正反兼容契约测试并针对实现执行；定义日志、指标、关联、废弃、迁移与移除旧行为的标准。
模式：使用一致的 HTTP 语义与具体状态码；错误格式稳定、可操作且不泄露；数据变动时大分页用游标；创建/重试在需要时用幂等键；Webhook 用签名、时间戳、重放防御与重投递；避免静默破坏性变更与语义模糊字段；不因便利暴露持久化模型。
反模式：对所有结果返回 200 并把失败只写进 body；超时后重复 POST 却无幂等或对账；大且可变的集合用 offset 分页且无稳定排序；只在端点或列表层授权而不对已加载资源授权；任何增量改动都做 URL 版本化。
验证：对请求、响应、头与 Problem Details 执行有效和无效示例的契约测试；用正确身份、跨身份、过期凭据与不足范围证明按资源/租户授权；模拟重试、重复、提交后超时、更新竞争与分页期间条目进出；对 OpenAPI/JSON Schema 做 lint 与结构校验，并与上一发布版本比较破坏性变更。未通过重放与消费者可见契约的自动化测试，不得宣称兼容或幂等。
相关技能：$specsfy-specialist-astro 负责框架内实现端点，本技能保持 HTTP 合约可被站外消费；$specsfy-specialist-domain-modeling 在暴露为资源前定义词汇与不变量；$specsfy-specialist-typescript 建模内部类型，不自动作为公开合约源；$specsfy-specialist-observability 定义遥测与 SLO；$specsfy-specialist-performance-engineering 测量吞吐与延迟且不改变语义。