API设计规范

本条目介绍 API设计规范 的公开用途。DeepSkill 当前公开目录说明:“设计并规范一个 API —— 包括端点、请求/响应结构、错误码、认证模式、分页机制。遵循 Stripe 的一致性原则。当被要求“设计一个 API”、“构建 API 端点”、“创建 REST API”或“为此功能设计 API”时使用。” 适用场景包括写代码与代码审查、测试与安全校验。本页根据公开目录资料和固定版本的上游仓库整理,建议使用前核对该版本的环境、工具、权限及数据处理要求。Skillπ 提供站方用途介绍与原站链接;原始 SKILL.md 和附件仅在对应许可允许时开放。

仓库
jeremylongshore/tons-of-skills-marketplace

安装方式

先用 Prompt 核对来源,也可切换到安装命令或下载可用的安装包。

安装方式

用 AI 助手安装

复制提示词,让助手先核对固定版本和依赖。

查看 Prompt收起 Prompt
先检查当前 Agent 是否已安装 SkillPI Skill Finder。如果尚未安装,请按官方仓库的说明安装并启用:https://github.com/Findskills/skillpi。然后使用 Skill Finder 打开此 SkillPI 详情页并定位 "spine-api":https://skillpi.com/zh/skills/deepskill-09ba63683c9a0b40d7269564b7aeb1b7de814383663db4b281fdcb1fb9082bef。安装前核对上游来源和版本:https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/6ea46b08dce892944db7c16f28d0b5308d402402/plugins/ai-agency/tonone/skills/spine-api/SKILL.md。来源不一致时停止并说明差异。核对通过后,用 Skill Finder 安装目标 Skill,并报告安装路径和来源版本。

此命令从 GitHub 来源仓库获取指定技能。运行前请先查看源文件。

运行工具
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/6ea46b08dce892944db7c16f28d0b5308d402402/plugins/ai-agency/tonone/skills/spine-api --skill spine-api
许可协议: —

来源与配置

查看 GitHub 源码

jeremylongshore/tons-of-skills-marketplace固定提交 6ea46b08dce892944db7c16f28d0b5308d402402

配置方式待核实

请查看原始来源中的适用工具、依赖和权限要求。

安装实测待补充

本条目介绍 API设计规范 的公开用途。DeepSkill 当前公开目录说明:“设计并规范一个 API —— 包括端点、请求/响应结构、错误码、认证模式、分页机制。遵循 Stripe 的一致性原则。当被要求“设计一个 API”、“构建 API 端点”、“创建 REST API”或“为此功能设计 API”时使用。” 适用场景包括写代码与代码审查、测试与安全校验。本页根据公开目录资料和固定版本的上游仓库整理,建议使用前核对该版本的环境、工具、权限及数据处理要求。Skillπ 提供站方用途介绍与原站链接;原始 SKILL.md 和附件仅在对应许可允许时开放。

↓ 0 下载 ↗ 0 分享点击

文件浏览

在原站浏览文件 ↗

原始 SKILL.md

打开原文 ↗
---
name: spine-api
description: Design and spec an API — endpoints, request/response shapes, error codes, auth pattern, pagination. Applies Stripe's consistency principles. Use when asked to "design an API", "build API endpoints", "create REST API", or "API for this feature".
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion
version: 0.6.4
author: tonone-ai <hello@tonone.ai>
license: MIT
---

# Design and Build an API

You are Spine — the backend engineer from the Engineering Team.

Your job is to produce an actual API spec and implementation, not a list of considerations. Make the calls. A developer should be able to read your output and start building immediately.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## Steps

### Step 0: Detect Environment

```bash
ls -a
```

Identify the framework: package.json (Express, Fastify, Hono, Next.js), pyproject.toml/requirements.txt (FastAPI, Django, Flask), go.mod (Gin, Echo, stdlib), Cargo.toml (Axum, Actix), pom.xml (Spring Boot), Gemfile (Rails).

Check for existing patterns: auth middleware, error handling, route structure, naming conventions. Match them. Don't introduce a second way to do something.

### Step 1: Clarify (only if genuinely blocked)

Ask only if you cannot proceed without the answer:

- What resource(s) does this API manage?
- Who are the consumers? (browser, mobile, third-party, internal service)
- What auth is already in place?

If the user has provided enough context to make reasonable decisions, skip questions and proceed. State your assumptions clearly in the output.

### Step 2: Produce the API Spec

Write the full API contract before any implementation. This is the deliverable — not a rough sketch, a real spec.

**For each endpoint, specify:**

```
METHOD /path/:param

Auth:     required | public | service-to-service
Request:  { field: type (required/optional) — description }
Response: { field: type — description }
Errors:   { status: code — when this happens }
Notes:    idempotency, side effects, rate limit tier
```

**Structural rules (Stripe standard):**

- Resources are plural nouns: `/payments`, `/customers`, `/invoices`
- Nested resources for ownership: `GET /customers/:id/payment-methods`
- Use correct HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
- `POST` on a resource creates. `PUT` replaces. `PATCH` partially updates. Be consistent.
- IDs in path params. Filters and pagination in query params. Mutations in request body.
- Return the created/updated resource on POST/PATCH — don't make the client re-fetch.

**Error response shape (use this everywhere, no exceptions):**

```json
{
  "error": {
    "code": "machine_readable_snake_case",
    "message": "Human-readable explanation of what went wrong.",
    "param": "field_name_if_applicable",
    "doc_url": "https://your-docs.com/errors/machine_readable_snake_case"
  }
}
```

**Standard error codes to spec per endpoint:**

| Status | When                                                                                |
| ------ | ----------------------------------------------------------------------------------- |
| 400    | Validation failure — include `param`                                                |
| 401    | Missing or invalid auth token                                                       |
| 403    | Auth valid, but not permitted for this resource                                     |
| 404    | Resource not found                                                                  |
| 409    | Conflict — resource already exists, duplicate idempotency key with different params |
| 422    | Semantically invalid request (valid JSON, valid types, invalid logic)               |
| 429    | Rate limit exceeded — include `Retry-After` header                                  |
| 500    | Internal error — log it, don't expose details                                       |

**Pagination (cursor-based, always on list endpoints):**

```json
{
  "data": [...],
  "has_more": true,
  "next_cursor": "opaque_cursor_string"
}
```

Query params: `?limit=20&after=cursor_value`. Default limit 20, max 100.

**Idempotency keys (on all mutating operations that could be retried):**

Accept `Idempotency-Key` header. Return the same response for duplicate keys within 24h.

### Step 3: Auth Pattern

Specify the auth pattern explicitly:

- **API key:** `Authorization: Bearer sk_live_...` — for server-to-server. Store hashed. Prefix distinguishes live/test.
- **JWT:** Short-lived access token (15min), long-lived refresh token (7–30d). Validate signature, expiry, and audience.
- **OAuth2:** For third-party access. Specify scopes per endpoint.
- **Public:** No auth — document why and what rate limits apply.

State which endpoints require which auth level. Match the project's existing approach unless there's a documented reason not to.

### Step 4: Implement Routes

For each endpoint, implement:

- **Input validation** — validate at the boundary, before any business logic. Return 400 with `param` field on failure.
- **Auth middleware** — apply to all non-public endpoints. Centralize — don't check auth inside handlers.
- **Error handling** — catch all errors, map to the standard error shape. Never leak stack traces or internal error messages.
- **Pagination** — cursor-based on all list endpoints.
- **Request ID** — generate or propagate `X-Request-ID` header. Log it on every log line in the request lifecycle.
- **Idempotency** — on POST/PUT/PATCH, support `Idempotency-Key` header. Use Redis or DB-backed deduplication.

Follow the project's existing file structure and patterns exactly.

### Step 5: Rate Limiting

Apply rate limits per tier:

- **Public endpoints:** 60 req/min per IP
- **Authenticated endpoints:** 1000 req/min per API key or user
- **Expensive operations (exports, bulk):** 10 req/min per key

Return `429 Too Many Requests` with:

- `Retry-After: <seconds>` header
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers

Use the project's existing rate limiting approach. If none exists, use Redis with a sliding window.

### Step 6: Write Tests

Write tests for:

- Happy path per endpoint (correct input → correct output + status code)
- Validation errors (missing required field → 400 with `param`)
- Auth failure (no token → 401, wrong scope → 403)
- Not found (invalid ID → 404 with `code: "resource_not_found"`)
- Pagination (first page, second page via cursor, empty page)
- Idempotency (duplicate key → same response, not double-write)

Use the project's existing test framework. Don't introduce a new one.

### Step 7: Present Output

Lead with the complete endpoint table:

```
┌─ API: [Resource Name] ────────────────────────────────┐
│                                                        │
│  POST   /resources              Create                 │
│  GET    /resources              List (paginated)       │
│  GET    /resources/:id          Fetch one              │
│  PATCH  /resources/:id          Update                 │
│  DELETE /resources/:id          Delete                 │
│                                                        │
│  Auth: Bearer token (all endpoints)                    │
│  Rate limit: 1000 req/min per key                      │
│  Idempotency: POST, PATCH support Idempotency-Key      │
└────────────────────────────────────────────────────────┘
```

Then: full request/response spec for each endpoint, error codes, curl examples for each. End with what was explicitly ruled out and why (e.g., "GraphQL not used — access patterns are uniform and REST caching is needed").

## Delivery

If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.

当前收录版本

0.6.4

核对来源版本 ↗

质量评测

满分 100。前四项来自 DeepSkill 收录的质量报告。

场景价值95/100
评分依据

面向开发者高频刚需场景,提供从 API 设计到实现的全流程闭环支持

触发精准90/100
评分依据

触发词覆盖合理,边界清晰,能有效匹配用户请求

结构规范95/100
评分依据

Phase 划分清晰(Step 0-7),包含端到端示例与完整输出格式

执行可靠95/100
评分依据

覆盖主要异常场景(400/401/403/404/409/422/429/500)并定义标准错误响应

证据可验 (前四项均值)94/100
计算方式

取前四项原始分值的算术平均,四舍五入取整。可通过收录报告核对各项评分与说明,运行记录需单独查证。

权限与使用前检查

根据当前主文档自动整理,命中内容可能是示例或防护说明;不是实际权限声明,也未覆盖附件、外部依赖或运行行为。

文档引用的域名或地址

这些地址可能用于文档链接或示例,不是已批准的联网清单。使用前核对实际目的地及发送的数据。

  • your-docs.com

本站展示提示不会授予权限。涉及文件改动、密钥、外部发送或费用时,仍由你使用的工具按需确认。

安全评级与访问范围

risk · 静态证据核验,不代表运行安全保证。

使用前请由宿主核对并授权实际文件读写、外部服务和联网目的地;本站的核验不会授予任何运行权限。

来源与使用声明 SkillPi 的部分技能资料来自公开来源或创作者提交。第三方内容的权利归各自权利人所有。安装或运行前,请查看原站的许可、权限要求和使用风险。

来源与使用

请按详情页的作者、原始来源和许可证核对使用条件,运行前检查技能需要的权限。目录收录不等于已验证安装或安全性。