API设计规范
安装方式
先用 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 和附件仅在对应许可允许时开放。
文件浏览
---
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 收录的质量报告。
评分依据
面向开发者高频刚需场景,提供从 API 设计到实现的全流程闭环支持
评分依据
触发词覆盖合理,边界清晰,能有效匹配用户请求
评分依据
Phase 划分清晰(Step 0-7),包含端到端示例与完整输出格式
评分依据
覆盖主要异常场景(400/401/403/404/409/422/429/500)并定义标准错误响应
计算方式
取前四项原始分值的算术平均,四舍五入取整。可通过收录报告核对各项评分与说明,运行记录需单独查证。
权限与使用前检查
根据当前主文档自动整理,命中内容可能是示例或防护说明;不是实际权限声明,也未覆盖附件、外部依赖或运行行为。
-
账号、密钥或授权
使用专用、最小权限账号,不把密钥粘贴到公开内容或命令日志;核对接收数据的服务与租户。
主文档提及 · 第 111, 112, 136 行
文档引用的域名或地址
这些地址可能用于文档链接或示例,不是已批准的联网清单。使用前核对实际目的地及发送的数据。
- your-docs.com
安全评级与访问范围
risk · 静态证据核验,不代表运行安全保证。
使用前请由宿主核对并授权实际文件读写、外部服务和联网目的地;本站的核验不会授予任何运行权限。
用户讨论
还没有已核实的点评。