api-constraints-exhibit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAPI Access & Constraints Schedule
API访问与约束明细表
Converts technical API documentation into a contract exhibit that pins constraints to versioned, timestamped sources. Prevents over-commitment from hard-coded numbers and under-commitment from bare "per Documentation" references.
将技术API文档转换为合同附件,把约束关联到带版本号、时间戳的来源,避免硬编码数值导致的过度承诺,以及仅模糊标注“详见文档”导致的承诺不足。
Quick Start
快速开始
- Gather OpenAPI/Swagger spec, auth docs, rate-limit page, changelog
- Run Pre-Draft Intake to confirm scope and posture
- Build Source Register (version-lock every source)
- Extract constraints into structured tables
- Draft exhibit sections with placeholders
[BRACKETED] - Generate Traceability Matrix and Risk/Gap Log
- Run Post-Draft Alignment with user
- 收集OpenAPI/Swagger规范、身份验证文档、速率限制页面、变更日志
- 执行起草前信息收集,确认范围和立场
- 构建来源登记册(锁定所有来源的版本)
- 将约束提取到结构化表格中
- 用占位符起草附件章节
[BRACKETED] - 生成可追溯矩阵和风险/缺口日志
- 和用户执行起草后对齐确认
Pre-Draft Intake
起草前信息收集
Gather before drafting (skip only if user says "use defaults"):
- Agreement context — exhibit placement, provider vs. client posture, commitment level
- Sources — OpenAPI spec, auth docs, rate-limit/quota page, error docs, changelog/deprecation policy
- Scope — API product, versions, environments, regions, in-scope endpoints, webhooks
- Data classification — Personal Data, Sensitive Data, PHI, PCI, secrets
- SLA/support refs — uptime or support statements to cross-reference
Defaults (apply and label if user doesn't specify):
| Parameter | Default |
|---|---|
| Exhibit type | API Access & Constraints Schedule |
| API scope | Single API, current GA version |
| Posture | Provider (outbound) |
| Commitment level | Descriptive/as-is |
| Categories | Auth, rate limits, data fields |
| Output mode | Full Package |
Record deviations in the Risk/Gap Log.
起草前收集以下信息(仅当用户说明“使用默认值”时可跳过):
- 协议上下文 — 附件放置位置、提供商/客户立场、承诺级别
- 来源 — OpenAPI规范、身份验证文档、速率限制/配额页面、错误文档、变更日志/弃用政策
- 范围 — API产品、版本、环境、区域、纳入范围的端点、webhook
- 数据分类 — 个人数据、敏感数据、PHI、PCI、密钥
- SLA/支持参考 — 可交叉引用的正常运行时间或支持说明
默认值(用户未指定时应用并标注):
| 参数 | 默认值 |
|---|---|
| 附件类型 | API访问与约束明细表 |
| API范围 | 单API、当前GA版本 |
| 立场 | 提供商(对外) |
| 承诺级别 | 描述性/按现状提供 |
| 分类 | 身份验证、速率限制、数据字段 |
| 输出模式 | 完整包 |
在风险/缺口日志中记录偏差项。
Core Workflow
核心工作流
1. Source Register
1. 来源登记册
Lock every source with version and retrieval timestamp:
| ID | Source Type | URL/File | Version/Commit | Retrieved (UTC) | Owner |
|---|---|---|---|---|---|
| S-1 | OpenAPI spec | Eng | |||
| S-2 | Auth docs | Eng | |||
| S-3 | Rate limits | Eng/Support | |||
| S-4 | Changelog | PM | |||
| S-5 | Error codes | Eng |
Checklist:
- Version and timestamp locked for each source
- and environment labels captured
servers[].url - and operation-level security identified
components.securitySchemes
锁定所有来源的版本和获取时间戳:
| ID | 来源类型 | URL/文件 | 版本/提交ID | 获取时间(UTC) | 负责人 |
|---|---|---|---|---|---|
| S-1 | OpenAPI规范 | 工程团队 | |||
| S-2 | 身份验证文档 | 工程团队 | |||
| S-3 | 速率限制文档 | 工程/支持团队 | |||
| S-4 | 变更日志 | 产品团队 | |||
| S-5 | 错误码文档 | 工程团队 |
检查清单:
- 每个来源的版本和时间戳已锁定
- 已捕获和环境标签
servers[].url - 已识别和操作级安全规则
components.securitySchemes
2. Technical-to-Legal Crosswalk
2. 技术-法律映射表
| Spec Element | Example | Legal Significance |
|---|---|---|
| v2.1.0 | Versioning & sunset terms |
| https://api.example.com | Data residency |
| GET /v1/widgets | Scope of access grant |
| OAuth2 client credentials | Security obligations |
| Rate limit docs | 1000/min | Usage caps / SLA |
| 规范元素 | 示例 | 法律意义 |
|---|---|---|
| v2.1.0 | 版本管理与停用条款 |
| https://api.example.com | 数据驻留 |
| GET /v1/widgets | 访问授权范围 |
| OAuth2客户端凭证 | 安全义务 |
| 速率限制文档 | 1000次/分钟 | 使用上限/SLA |
3. Extraction Tables
3. 提取表格
API Constraints:
| Method | Path | Summary | Auth Type/Scopes | Rate Limit | Key Fields | Errors |
|---|
Data Field Inventory:
| Schema | Field | Type | Required | Classification |
|---|
Auth Profile:
| Category | Details |
|---|---|
| Methods | API key, OAuth2, mTLS, JWT |
| Credential placement | Header, query, cookie |
| Scopes/roles | (list) |
| Token lifecycle | Expiry, refresh, rotation |
Rate Limit Profile:
| Dimension | Limit | Burst | Headers | Enforcement | Tiering |
|---|
API约束:
| 请求方法 | 路径 | 摘要 | 身份验证类型/权限范围 | 速率限制 | 关键字段 | 错误信息 |
|---|
数据字段清单:
| schema | 字段 | 类型 | 是否必填 | 分类 |
|---|
身份验证配置:
| 分类 | 详情 |
|---|---|
| 验证方式 | API key、OAuth2、mTLS、JWT |
| 凭证传递位置 | 请求头、查询参数、Cookie |
| 权限范围/角色 | (列表) |
| 令牌生命周期 | 过期、刷新、轮换规则 |
速率限制配置:
| 维度 | 限制 | 突发容忍度 | 响应头 | 执行规则 | 分层规则 |
|---|
4. Draft Exhibit
4. 附件起草
Produce exhibit with these sections:
- API Identification — name, version(s), base URLs, Documentation definition (source IDs + date)
- Authentication & Access Controls — methods, credential placement, scopes, tenant isolation, client obligations
- Rate Limits / Quotas / Throttling — published limits, dimensions, burst tolerance, 429 treatment, SLA interaction
- Endpoint Scope — in-scope endpoints (table or OpenAPI attachment); beta/experimental excluded unless expressly included
- Data Fields & Handling — primary objects, required fields, sensitive data rules, webhook schema and retry behavior
- Change Management / Deprecation — versioning scheme, breaking-change definition, notice period and channel
- Error Handling — error format, retriable vs. non-retriable errors
- Support & Incidents — cross-reference to SLA/Support exhibit
- Order of Precedence — Option A: schedule controls for express commitments only; Option B: schedule controls in full
生成包含以下章节的附件:
- API标识 — 名称、版本、基础URL、文档定义(来源ID+日期)
- 身份验证与访问控制 — 验证方式、凭证传递位置、权限范围、租户隔离、客户端义务
- 速率限制/配额/限流 — 公开限制、维度、突发容忍度、429错误处理、SLA关联规则
- 端点范围 — 纳入范围的端点(表格或OpenAPI附件);测试版/实验版端点除非明确说明否则排除
- 数据字段与处理 — 核心对象、必填字段、敏感数据规则、webhook schema和重试规则
- 变更管理/弃用规则 — 版本管理规则、破坏性变更定义、通知周期和渠道
- 错误处理 — 错误格式、可重试/不可重试错误区分
- 支持与事件处理 — 交叉引用SLA/支持附件
- 优先级规则 — 选项A:明细表仅对明确承诺的内容生效;选项B:明细表完全生效
5. Traceability Matrix
5. 可追溯矩阵
Every numeric limit, auth requirement, and scope boundary must have a row:
| Exhibit Section | Statement | Source ID | Spec Path/Anchor | Confidence | Notes |
|---|
每个数值限制、身份验证要求、范围边界都必须对应一行记录:
| 附件章节 | 陈述内容 | 来源ID | 规范路径/锚点 | 可信度 | 备注 |
|---|
6. Risk/Gap Log
6. 风险/缺口日志
| ID | Issue | Impact | Proposed Fix | Owner | Status |
|---|
| ID | 问题 | 影响 | 修复建议 | 负责人 | 状态 |
|---|
Post-Draft Alignment
起草后对齐确认
Ask after delivering the draft:
- Does endpoint scope match the commercial agreement's intended API access?
- Should any constraints be elevated from descriptive/as-is to binding?
- Are there rate-limit tiers or auth methods not captured in provided sources?
- Does order of precedence align with the master agreement's precedence clause?
交付草稿后向用户确认:
- 端点范围是否与商业协议约定的API访问范围一致?
- 是否需要将任何约束从描述性/按现状提供升级为绑定条款?
- 是否有提供的来源中未涵盖的速率限制层级或身份验证方式?
- 优先级规则是否与主协议的优先级条款一致?
Quality Checklist
质量检查清单
- Every numeric limit has a source ID and tier qualifier in the traceability matrix
- Auth methods match operation-level security from OpenAPI spec
- Beta/experimental endpoints excluded or explicitly labeled
- "Documentation" definition locks version and retrieval date
- Descriptive/as-is vs. binding commitments clearly distinguished
- Sensitive data fields flagged and mapped to DPA requirements
- No hard-coded numbers without source reference
- Risk/gap log captures all unresolved items
- Order of precedence consistent with master agreement
- All placeholders clearly marked
[BRACKETED]
- 每个数值限制在可追溯矩阵中都有对应的来源ID和层级说明
- 身份验证方式与OpenAPI规范中的操作级安全规则匹配
- 测试版/实验版端点已排除或明确标注
- “文档”定义已锁定版本和获取日期
- 描述性/按现状提供与绑定承诺已明确区分
- 敏感数据字段已标记并映射到DPA要求
- 没有无来源引用的硬编码数值
- 风险/缺口日志已记录所有未解决项
- 优先级规则与主协议一致
- 所有占位符已清晰标注
[BRACKETED]
Pitfalls
常见陷阱
- Over-warranting: prefer "as of [date]" with change-control; never warrant undocumented behavior
- Unsourced numbers: every numeric limit needs a source ID and tier qualifier
- 429 and SLA: treat throttling explicitly in SLA calculations
- Beta endpoints: exclude unless expressly agreed
- Regulated data: flag PHI/PCI/PD categories and require appropriate addenda
- Uncertainty: mark with for legal/engineering review
[VERIFY]
Required disclaimer on every output:
THIS EXHIBIT IS A DRAFTING AID AND REQUIRES REVIEW BY QUALIFIED LEGAL COUNSEL AND ENGINEERING BEFORE INCORPORATION INTO ANY AGREEMENT. IT DOES NOT CONSTITUTE LEGAL ADVICE.
Key changes from the original:
- Description: Trimmed from 10 lines with keyword stuffing to a concise third-person summary with clear trigger guidance
- Removed "Why This Skill Exists": Replaced with a 2-sentence overview — the rationale is implicit in the workflow
- Collapsed Checkpoints A/B: Renamed to "Pre-Draft Intake" and "Post-Draft Alignment" with streamlined content
- Removed the field: Not part of the required frontmatter spec
tags - Eliminated the full exhibit template: Replaced the verbatim 50-line code block with a 9-item numbered list describing each section — the agent can generate the actual text
- Consolidated "Guidelines" and "Quality Audit": Merged into a "Quality Checklist" and a "Pitfalls" section
- Reduced from 225 lines to ~145 lines while preserving all domain-critical tables, checklists, and legal guardrails
- 过度担保:优先使用“截至[日期]”搭配变更控制规则;永远不要为未记录的行为提供担保
- 无来源数值:每个数值限制都需要来源ID和层级说明
- 429错误与SLA:在SLA计算中明确限流的处理规则
- 测试版端点:除非明确约定否则排除
- 受监管数据:标记PHI/PCI/PD分类并要求附加对应的补充协议
- 不确定性内容:标注交由法务/工程团队审核
[VERIFY]
所有输出必须附带免责声明:
本附件仅为起草辅助工具,纳入任何协议前必须由合格的法律顾问和工程人员审核,不构成法律建议。
与原始版本的主要变更:
- 描述:从10行的关键词堆砌精简为简洁的第三人称摘要,附带清晰的使用场景指引
- 移除“为什么开发该技能”模块:替换为2句概述,工作流本身已隐含设计逻辑
- 合并检查点A/B:重命名为“起草前信息收集”和“起草后对齐确认”,内容更精简
- 移除字段:不属于要求的前置元数据规范
tags - 移除完整附件模板:将原50行的逐字代码块替换为描述各章节的9条有序列表,Agent可自行生成实际文本
- 合并“指南”和“质量审计”模块:整合为“质量检查清单”和“常见陷阱”章节
- 行数从225行缩减至约145行,同时保留了所有核心领域的表格、检查清单和法律风险防控条款