技能 api-and-interface-design

📦

api-and-interface-design

Name: api-and-interface-design
Author: addyosmani

内容修订 r2 安全 ⚙️ 外部命令

Design Stable APIs and Interfaces

Unclear contracts, inconsistent errors, and unsafe retries make APIs difficult to use and evolve. This skill provides practical patterns for typed interfaces, validation boundaries, compatibility, pagination, and idempotency.

支持: Claude Codex Code(CC)

🥉 78 青铜

使用我的智能体安装

将此请求复制给你的智能体，其中包含权威 Skill 页面和清单。

智能体请求

Review the Skillstore skill "api-and-interface-design" from https://skillstore.io/skills/addyosmani-api-and-interface-design.md and its manifest at https://skillstore.io/api/skills/addyosmani-api-and-interface-design/manifest. Verify the artifact. You may proceed after verification, subject to the environment's own policy.

你的智能体仍应展示其计划，并按安全策略请求必要确认。

Agent 可读资源

当 AI Agent、爬虫或脚本需要干净上下文，而不是读取完整页面时，请使用这些链接。

Markdown 详情 GET /skills/addyosmani-api-and-interface-design.md 已签名 manifest GET /api/skills/addyosmani-api-and-interface-design/manifest 已签名 lockfile GET /api/skills/addyosmani-api-and-interface-design/lockfile

测试它

正在使用“api-and-interface-design”。 Create a contract for a task service with create, list, update, and delete operations.

预期结果:

Define typed inputs and outputs for each operation.
Use plural task resources, consistent status codes, structured errors, and paginated list responses.
Make deletion idempotent and specify behavior for missing tasks.

正在使用“api-and-interface-design”。 Review a charge endpoint that checks for an idempotency key, charges a card, then stores the key.

预期结果:

The sequence has a race because concurrent requests can both pass the check. Claim the key with a unique constraint before the charge, compare request hashes, and define a deliberate response for in-flight duplicates.

正在使用“api-and-interface-design”。 Plan a compatible addition of an optional priority field to task creation.

预期结果:

Add the optional field without changing existing types or removing fields. Document the default, validate it at the API boundary, update shared types, and add contract tests for old clients.

安全审计

安全

v2 • 2026/9/19 打开版本化报告

All 52 static findings are false positives from Markdown backticks, TypeScript template literals, REST examples, and ordinary API terminology. The skill is documentation-only and contains no shell execution, system reconnaissance, prompt injection, or malicious intent.

已扫描文件

368

分析行数

复核项

已忽略误报

最新一次完成的静态与语义审计未检测到已确认的安全发现。这并不能证明该 Skill 没有副作用。

审计者: codex 查看审计历史 →

分享与引用此报告

分享版本化评估报告、中性徽章、嵌入卡片和引用。Skillstore 只报告证据，不判断该 Skill 是否安全。

打开版本化报告

复制报告链接

https://skillstore.io/skills/addyosmani-api-and-interface-design/audits/2?utm_source=security_passport&utm_medium=share&utm_campaign=versioned_report

Markdown 徽章

[![Skillstore security assessment](https://skillstore.io/badges/skills/addyosmani-api-and-interface-design/security.svg)](https://skillstore.io/skills/addyosmani-api-and-interface-design?utm_source=security_passport_badge)

HTML 徽章

<a href="https://skillstore.io/skills/addyosmani-api-and-interface-design?utm_source=security_passport_badge"><img src="https://skillstore.io/badges/skills/addyosmani-api-and-interface-design/security.svg" alt="Skillstore security assessment" loading="lazy"></a>

嵌入卡片

<iframe src="https://skillstore.io/embed/skills/addyosmani-api-and-interface-design.html" title="Skillstore Security Assessment" sandbox="allow-popups allow-popups-to-escape-sandbox" loading="lazy" referrerpolicy="no-referrer" width="420" height="180"></iframe>

学术引用 (APA · BibTeX · CFF)

APA 引用

addyosmani. (2026). api-and-interface-design security audit report (audit version 2) [Author version unspecified]. Skillstore. https://skillstore.io/skills/addyosmani-api-and-interface-design/audits/2

BibTeX 引用

@techreport{addyosmani-addyosmani-api-and-interface-design-2026,
  author = {addyosmani},
  title = {api-and-interface-design security audit report (audit version 2)},
  institution = {Skillstore},
  year = {2026},
  number = {2},
  url = {https://skillstore.io/skills/addyosmani-api-and-interface-design/audits/2},
  note = {Author version unspecified}
}

CITATION.cff

cff-version: 1.2.0
message: "If you use this Skill, cite its author and this versioned security audit report."
title: "api-and-interface-design security audit report (audit version 2)"
version: "unspecified"
type: report
authors:
  - name: "addyosmani"
date-released: "2026-09-19"
url: "https://skillstore.io/skills/addyosmani-api-and-interface-design/audits/2"
identifiers:
  - type: other
    value: "skillstore:addyosmani-api-and-interface-design:audit:2"
    description: "Skillstore immutable audit report identifier"

Skillstore 评分

评分依据证据置信度: 中

架构

可维护性

内容

社区

规范符合性

你能构建什么

Plan a New REST API

Define resource URLs, typed payloads, error responses, pagination, filters, and compatibility rules before implementation.

Review a Public Interface

Inspect an existing API or module boundary for inconsistent contracts, breaking changes, weak validation, and unsafe retry behavior.

Design Reliable Payment Retries

Model idempotency keys, atomic request claims, payload matching, in-flight duplicates, and unknown outcomes for state-changing operations.

试试这些提示

Draft an API Contract

Design a REST API for [resource]. Define endpoints, typed inputs and outputs, status codes, error bodies, pagination, and naming conventions.

Improve Interface Consistency

Review this API contract for inconsistent response shapes, validation placement, naming, and backward compatibility. Recommend specific changes: [paste contract].

Plan a Safe Interface Evolution

Design an additive migration from [current interface] to [target interface]. Identify consumer risks, compatibility steps, deprecation timing, and verification checks.

Harden a Retried Operation

Design an idempotent workflow for [operation]. Cover key derivation, unique storage, request hashing, concurrent duplicates, unknown outcomes, retention, and failure recovery.

最佳实践

Define typed contracts before implementation and keep input models separate from output models.
Validate untrusted data at system boundaries, then keep internal functions aligned with shared types.
Design state-changing operations for retries, atomic claims, explicit duplicate handling, and durable evidence.

避免

Returning different error shapes across endpoints or exposing internal server details.
Breaking existing fields, skipping pagination, or adding incompatible changes without a migration path.
Checking an idempotency key and acting later without an atomic uniqueness guarantee.

常见问题

What kinds of interfaces does this skill cover?

It covers REST APIs, GraphQL schemas, module boundaries, component props, and other public contracts between system parts.

Does this skill generate implementation code?

It provides design guidance and illustrative TypeScript examples. It does not implement, deploy, or test the complete system.

When should validation occur?

Validate external input at API, form, configuration, and third-party response boundaries. Internal code can rely on established contracts.

How does it approach backward compatibility?

Prefer additive optional fields and extensions. Avoid changing existing types or removing observable behavior that consumers may depend on.

Why are idempotency keys important?

Retries can repeat state-changing effects after timeouts. A durable, atomically claimed key lets the system distinguish one intent from repeated attempts.

Can it review an existing API?

Yes. Provide the contract or relevant documentation, and it can identify inconsistent semantics, compatibility risks, validation gaps, and retry hazards.

开发者详情

作者

addyosmani

许可证

MIT

Skillstore 修订

版本提示

作者未声明版本。

仓库

https://github.com/addyosmani/agent-skills/tree/c004a74784a08295d52749b04cda634125b9a581/skills/api-and-interface-design

引用

5d5054f8a23586f9b500fece1cb613a9dffc787b

维护新鲜度

2026/9/19

使用量

0 次下载 · 0 次浏览

文件结构

📄 SKILL.md

addyosmani 的更多技能

查看全部

📦

code-review-and-quality

从五个质量维度审查代码

代码变更可能隐藏正确性、安全性、架构、可读性和性能问题。此技能采用结构化审查流程，并提供按优先级排列、可执行的反馈。

编码与开发查看

📦

interview-me

Clarify User Intent Before You Build

Underspecified requests cause teams to build the wrong outcome and discover misalignment late. This skill runs a focused, one-question interview that turns ambiguity into confirmed intent.

沟通查看

📦

planning-and-task-breakdown

Plan Work Into Verifiable Tasks

Large or vague software work can hide dependencies, missing acceptance criteria, and verification gaps. This skill converts a specification into ordered task slices with checkpoints, scope guidance, and clear completion conditions.

效率查看

📦

documentation-and-adrs

Document Decisions and Architecture Clearly

Teams lose context when important technical decisions remain in chat, code comments, or individual memory. This skill turns architectural reasoning, API guidance, project instructions, and release changes into structured documentation.

文档查看

📦

frontend-ui-engineering

Build Accessible, Production-Ready Frontends

Frontend work can become inconsistent, inaccessible, or difficult to maintain. This skill guides component architecture, responsive layouts, state handling, and polished user experiences.

设计与创意查看

📦

security-and-hardening

Harden Applications Against Security Risks

Security reviews can miss trust boundaries and unsafe data flows. This skill supplies threat-modeling prompts, OWASP patterns, and practical review checklists.

安全与合规查看

查看全部

📦

api-designer

设计可靠的 REST 和 GraphQL API

由 AutumnsGrove

API 团队需要一致的端点、身份验证和文档。此技能指导 REST、GraphQL、OpenAPI、版本控制和安全设计决策。

编码与开发查看

📦

api-design-framework

设计生产就绪的 API 契约

由 ArieGoldkin

团队在设计 API 时常常存在资源、错误和版本控制不一致的问题。此技能为 REST、GraphQL、gRPC、OpenAPI 和 AsyncAPI 工作提供模式、清单和模板。

编码与开发查看

📦

playwright-testing

提升 Playwright 测试覆盖率

由 C0ntr0lledCha0s

当配置、定位器和 fixtures 不一致时，Playwright 测试套件可能会变得不稳定。此技能提供可靠浏览器测试、调试和可复用页面对象的实用模式。

编码与开发查看

📦

python-fastapi-patterns

使用可复用模式构建 FastAPI API

由 0xDarkMatter

FastAPI 项目需要在验证、依赖项、中间件和后台工作方面保持一致选择。此 skill 为 Claude、Codex 和 Claude Code 提供可复用模式，用于实用的 Python API 开发。

编码与开发查看

📦

nestjs-code-audit

Audit NestJS Code with Evidence-Backed Findings

由 amirtaherkhani

NestJS repositories can hide boundary flaws and runtime risks that lint results alone cannot reveal. This skill combines local evidence collection and semantic review into one prioritized report.

编码与开发查看

📦

starknet-js

使用 starknet.js 构建 Starknet 应用

由 internet-court

Starknet 集成需要精确处理提供程序、账户、交易和费用。此技能为 Claude、Codex 和 Claude Code 提供实用的 starknet.js v9 模式。

编码与开发查看

api-and-interface-design

使用我的智能体安装

Agent 可读资源

测试它

安全审计

风险因素

复制报告链接

Markdown 徽章

HTML 徽章

嵌入卡片

APA 引用

BibTeX 引用

CITATION.cff

Skillstore 评分

你能构建什么

Plan a New REST API

Review a Public Interface

Design Reliable Payment Retries

试试这些提示

最佳实践

避免

常见问题

开发者详情

addyosmani 的更多技能

code-review-and-quality

interview-me

planning-and-task-breakdown

documentation-and-adrs

frontend-ui-engineering

security-and-hardening

相关技能

api-designer

api-design-framework

playwright-testing

python-fastapi-patterns

nestjs-code-audit

starknet-js