API 設計

來源狀態

可用來源

原始名稱: api-and-interface-design

原始作者: Addy Osmani

這是第三方 Community Skill；2lus 收錄不代表已完整安全審計或保證安全。

資源類型

Skill

與類似 Skill 有什麼不同？

• 程式碼變更審查

  Code Review 檢查實際程式修改；API Design 專注公開 contract、錯誤模型與消費端向後相容性。

來源描述的能力

這些是來源描述的可能操作，不代表 2lus 已授予權限或已測試。

尚未列出能力，請審查原始來源。

這個 Skill 是什麼？

檢查公開介面的可預期行為及消費端風險。

可以做什麼？何時適合使用？

• 建立 REST 資源契約
• 統一分頁與錯誤回應
• 評估 breaking change
• 規劃既有介面的穩定演進與邊界驗證

如何使用

1. 提供現有契約和消費端限制
2. 檢視命名、HTTP method、status 與冪等行為
3. 列出向後相容方案及待驗證假設
4. 先寫契約與錯誤語意，再於輸入邊界驗證並評估消費端依賴

使用前你需要準備

• Controller 或 endpoint 程式
• Request／Response Model
• API Specification（選填）

你可以替換：

[framework]、[API endpoint]、[consumer]

環境與相依需求

• 需要 OpenAPI、型別或請求回應範例；保留來源共用 references。

使用範例與 Prompt

以下是 2lus 撰寫的示範需求；請替換為你有權處理的檔案與專案，不代表已執行或保證結果。

入門

Review 這份任務 API 的 resource naming、HTTP status 與 error response，列出具體修改建議。

實務

為有新增資料的訂單列表設計 cursor pagination，說明重複與漏項風險。

進階

評估付款重試契約：同 key 異 payload、並行請求與結果未知時該如何回應；提出不破壞舊客戶端的版本策略。

實用提醒

• 考慮 Hyrum’s Law：消費端可能依賴未文件化行為。
• 遵守單一版本的可理解契約；變更欄位前盤點實際消費端。

限制與注意事項

• 契約檢視不能保證既有客戶端不受影響。

安全注意事項

• 遮蔽 token 與個資；設計 API 不代表允許呼叫正式端點。

使用與設定

此條目不提供已確認的通用安裝指令；請依官方文件與 Agent 版本操作。

支援平台

未確認特定 Agent 相容性

來源與授權

來源查核日期（非安全認證）: 2026-10-01

MIT

相關 Skills

• 程式碼變更審查
• 資料庫設計

Source status

Active source

Original name: api-and-interface-design

Original author: Addy Osmani

This is a third-party community skill. Inclusion by 2lus is not a complete security audit or safety guarantee.

Resource type

Skill

How is this different from similar skills?

• Code Review

  Code Review examines concrete code changes; API Design focuses on public contracts, errors and consumer compatibility.

Documented capabilities

These are operations described upstream, not permissions granted or tested by 2lus.

Capabilities not declared here; review the original source.

What is this skill?

Examine predictable public interfaces and consumer risk.

Use cases and when to use it

• Design REST resources
• Unify pagination and errors
• Assess breaking changes
• Evolve an existing interface while validating its boundaries

How to use it

1. Supply contracts and consumer constraints
2. Review naming, methods, status and idempotency
3. Document compatible options and unresolved assumptions
4. Write the contract and error semantics first, then validate at boundaries and inspect consumer dependencies

What you need

• Controller or endpoint code
• Request/response models
• API specification (optional)

You can replace:

[framework], [API endpoint], [consumer]

Environment and dependencies

• Provide OpenAPI, types or request/response samples; keep upstream shared references.

Usage and prompt examples

These example requests were written by 2lus. Substitute files and projects you may use; examples are not executed results or guarantees.

Beginner

Review this task API for resource naming, HTTP status and error response consistency; propose specific changes.

Practical

Design cursor pagination for orders receiving concurrent inserts; discuss duplicates and omissions.

Advanced

Review payment retries with reused keys, changed payloads, concurrency and unknown outcomes; propose a backward-compatible versioning strategy.

Tips

• Hyrum’s Law includes dependencies on undocumented behavior.
• Keep one understandable contract version and inventory real consumers before changing fields.

Limitations

• Contract review does not prove every existing client remains compatible.

Security notes

• Redact tokens and personal data; API design does not authorize production calls.

Usage and setup

No verified universal installation command is provided for this entry. Follow the official documentation for your agent version.

Supported agents

Specific agent compatibility unknown

Sources and license

Source check date (not a safety certification): 2026-10-01

MIT

Related skills

• Code Review
• Database Design