SuperAPI AI 工具集

api-design

编程与开发

查看项目

更新于 10-16 07:14

技能介绍

用途:这是一套语言无关的 REST API 设计指导,关注 API 契约本身,即设计成什么样;具体实现由语言相关技能处理。参考 Google API 设计指南(AIP)、Microsoft Azure REST API 指南、Zalando 指南、Stripe 设计模式、RFC 9457 与 OWASP API 安全十大风险(2023)。

主要能力: 1)资源与 URL:集合用复数名词,层级嵌套最多两层,自定义方法用 :action,过滤排序放查询参数,资源 ID 用 UUID,统一标准字段 id、created_at、updated_at。 2)HTTP 语义:GET 无副作用,PUT 整体替换,PATCH 用 JSON Merge Patch(RFC 7396),DELETE 幂等(重复删除返回 204)。 3)状态码:区分 200/201/204/304/400/401/403/404/409/412/422/429/503,不以 500 作为契约一部分。 4)错误格式:采用 RFC 9457 Problem Details,Content-Type 为 application/problem+json,含 type、title、status、detail、instance,并可扩展字段级校验错误、doc_url、request_id;不泄露内部实现。 5)分页:统一使用游标分页,参数 limit 与 cursor,响应含 data、has_more、next_cursor;服务端强制上限,游标不透明。 6)过滤、排序与字段选择:?status=active、?sort=created_at:desc、?fields=、?expand= 等,跨端点保持一致。 7)版本与演进:优先做加法变更,必要时用路径版本(/v1/)或日期请求头版本;配合 OpenAPI 弃用标记、Deprecation/Sunset 头与迁移观察期。 8)幂等性:非幂等操作使用 Idempotency-Key 请求头,服务端缓存键与响应,同键不同参数返回 422。 9)安全:Bearer 令牌放 Authorization 头,OAuth 2.0 + PKCE,区分 API Key 与应用/用户身份;默认拒绝、先鉴权后存在性检查、防范 BOLA/BOPLA 等;审计记录含 actor、action、resource、request_id 等且不可篡改。 10)传输与缓存:仅 HTTPS、HSTS、CORS 白名单、限流返回 429 与 Retry-After、请求体与超时限制;ETag 用于带宽节省与乐观并发,配合 If-None-Match/If-Match 与 Cache-Control。

使用方式:作为 API 设计评审与规范制定的参考清单,在实现前对 API 设计进行同行评审;可结合 OpenAPI 描述落地。

适用场景:面向开发者的 REST API 契约设计、评审与治理。

限制:面向 REST 风格;浏览器侧安全(CSRF、CSP、Cookie 加固等)与领域建模由其他技能覆盖;资料未提供具体安装命令、编程语言示例或收费信息。