api-constraints-exhibit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API 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

快速开始

  1. Gather OpenAPI/Swagger spec, auth docs, rate-limit page, changelog
  2. Run Pre-Draft Intake to confirm scope and posture
  3. Build Source Register (version-lock every source)
  4. Extract constraints into structured tables
  5. Draft exhibit sections with
    [BRACKETED]
    placeholders
  6. Generate Traceability Matrix and Risk/Gap Log
  7. Run Post-Draft Alignment with user
  1. 收集OpenAPI/Swagger规范、身份验证文档、速率限制页面、变更日志
  2. 执行起草前信息收集,确认范围和立场
  3. 构建来源登记册(锁定所有来源的版本)
  4. 将约束提取到结构化表格中
  5. [BRACKETED]
    占位符起草附件章节
  6. 生成可追溯矩阵和风险/缺口日志
  7. 和用户执行起草后对齐确认

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):
ParameterDefault
Exhibit typeAPI Access & Constraints Schedule
API scopeSingle API, current GA version
PostureProvider (outbound)
Commitment levelDescriptive/as-is
CategoriesAuth, rate limits, data fields
Output modeFull 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:
IDSource TypeURL/FileVersion/CommitRetrieved (UTC)Owner
S-1OpenAPI specEng
S-2Auth docsEng
S-3Rate limitsEng/Support
S-4ChangelogPM
S-5Error codesEng
Checklist:
  • Version and timestamp locked for each source
  • servers[].url
    and environment labels captured
  • components.securitySchemes
    and operation-level security identified
锁定所有来源的版本和获取时间戳:
ID来源类型URL/文件版本/提交ID获取时间(UTC)负责人
S-1OpenAPI规范工程团队
S-2身份验证文档工程团队
S-3速率限制文档工程/支持团队
S-4变更日志产品团队
S-5错误码文档工程团队
检查清单:
  • 每个来源的版本和时间戳已锁定
  • 已捕获
    servers[].url
    和环境标签
  • 已识别
    components.securitySchemes
    和操作级安全规则

2. Technical-to-Legal Crosswalk

2. 技术-法律映射表

Spec ElementExampleLegal Significance
info.version
v2.1.0Versioning & sunset terms
servers[].url
https://api.example.comData residency
paths.{path}.{method}
GET /v1/widgetsScope of access grant
components.securitySchemes
OAuth2 client credentialsSecurity obligations
Rate limit docs1000/minUsage caps / SLA
规范元素示例法律意义
info.version
v2.1.0版本管理与停用条款
servers[].url
https://api.example.com数据驻留
paths.{path}.{method}
GET /v1/widgets访问授权范围
components.securitySchemes
OAuth2客户端凭证安全义务
速率限制文档1000次/分钟使用上限/SLA

3. Extraction Tables

3. 提取表格

API Constraints:
MethodPathSummaryAuth Type/ScopesRate LimitKey FieldsErrors
Data Field Inventory:
SchemaFieldTypeRequiredClassification
Auth Profile:
CategoryDetails
MethodsAPI key, OAuth2, mTLS, JWT
Credential placementHeader, query, cookie
Scopes/roles(list)
Token lifecycleExpiry, refresh, rotation
Rate Limit Profile:
DimensionLimitBurstHeadersEnforcementTiering
API约束:
请求方法路径摘要身份验证类型/权限范围速率限制关键字段错误信息
数据字段清单:
schema字段类型是否必填分类
身份验证配置:
分类详情
验证方式API key、OAuth2、mTLS、JWT
凭证传递位置请求头、查询参数、Cookie
权限范围/角色(列表)
令牌生命周期过期、刷新、轮换规则
速率限制配置:
维度限制突发容忍度响应头执行规则分层规则

4. Draft Exhibit

4. 附件起草

Produce exhibit with these sections:
  1. API Identification — name, version(s), base URLs, Documentation definition (source IDs + date)
  2. Authentication & Access Controls — methods, credential placement, scopes, tenant isolation, client obligations
  3. Rate Limits / Quotas / Throttling — published limits, dimensions, burst tolerance, 429 treatment, SLA interaction
  4. Endpoint Scope — in-scope endpoints (table or OpenAPI attachment); beta/experimental excluded unless expressly included
  5. Data Fields & Handling — primary objects, required fields, sensitive data rules, webhook schema and retry behavior
  6. Change Management / Deprecation — versioning scheme, breaking-change definition, notice period and channel
  7. Error Handling — error format, retriable vs. non-retriable errors
  8. Support & Incidents — cross-reference to SLA/Support exhibit
  9. Order of Precedence — Option A: schedule controls for express commitments only; Option B: schedule controls in full
生成包含以下章节的附件:
  1. API标识 — 名称、版本、基础URL、文档定义(来源ID+日期)
  2. 身份验证与访问控制 — 验证方式、凭证传递位置、权限范围、租户隔离、客户端义务
  3. 速率限制/配额/限流 — 公开限制、维度、突发容忍度、429错误处理、SLA关联规则
  4. 端点范围 — 纳入范围的端点(表格或OpenAPI附件);测试版/实验版端点除非明确说明否则排除
  5. 数据字段与处理 — 核心对象、必填字段、敏感数据规则、webhook schema和重试规则
  6. 变更管理/弃用规则 — 版本管理规则、破坏性变更定义、通知周期和渠道
  7. 错误处理 — 错误格式、可重试/不可重试错误区分
  8. 支持与事件处理 — 交叉引用SLA/支持附件
  9. 优先级规则 — 选项A:明细表仅对明确承诺的内容生效;选项B:明细表完全生效

5. Traceability Matrix

5. 可追溯矩阵

Every numeric limit, auth requirement, and scope boundary must have a row:
Exhibit SectionStatementSource IDSpec Path/AnchorConfidenceNotes
每个数值限制、身份验证要求、范围边界都必须对应一行记录:
附件章节陈述内容来源ID规范路径/锚点可信度备注

6. Risk/Gap Log

6. 风险/缺口日志

IDIssueImpactProposed FixOwnerStatus
ID问题影响修复建议负责人状态

Post-Draft Alignment

起草后对齐确认

Ask after delivering the draft:
  1. Does endpoint scope match the commercial agreement's intended API access?
  2. Should any constraints be elevated from descriptive/as-is to binding?
  3. Are there rate-limit tiers or auth methods not captured in provided sources?
  4. Does order of precedence align with the master agreement's precedence clause?
交付草稿后向用户确认:
  1. 端点范围是否与商业协议约定的API访问范围一致?
  2. 是否需要将任何约束从描述性/按现状提供升级为绑定条款?
  3. 是否有提供的来源中未涵盖的速率限制层级或身份验证方式?
  4. 优先级规则是否与主协议的优先级条款一致?

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
    [BRACKETED]
    placeholders clearly marked
  • 每个数值限制在可追溯矩阵中都有对应的来源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
    [VERIFY]
    for legal/engineering review
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
    tags
    field
    : Not part of the required frontmatter spec
  • 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行,同时保留了所有核心领域的表格、检查清单和法律风险防控条款