api-design

01 前言 Front Matter

name

api-design

level

intermediate

agents

[ "backend-dev", "gis" ]

domain

architecture

source

Internal engineering practices, REST API conventions

status

draft

description

Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.

created_date

2026-04-27

validated_by

last_validated

03 SKILL.md 正文

API Design

Overview

Standards and patterns for designing consistent, well-documented RESTful APIs. Covers naming, HTTP methods, error handling, status codes, and documentation requirements.

Key Concepts

Naming Conventions

Plural nouns for resources: /users, /orders, /products
Kebab-case for multi-word: /user-profiles
Nest related resources: /users/{id}/orders
Query params for filtering: /users?role=admin&active=true

HTTP Methods

Method	Purpose	Idempotent	Response
GET	Read	Yes	200 + body
POST	Create	No	201 + body + Location
PUT	Replace	Yes	200 + body
PATCH	Partial update	No	200 + body
DELETE	Remove	Yes	204 (no body)

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}

Status Codes

200: Success — 201: Created — 204: No content
400: Bad request — 401: Unauthorized — 403: Forbidden
404: Not found — 409: Conflict — 422: Unprocessable
429: Rate limited — 500: Internal error

Decision Framework

Scenario	Method	Path	Status
List items	GET	/items	200
Get one item	GET	/items/{id}	200 / 404
Create item	POST	/items	201
Full update	PUT	/items/{id}	200 / 404
Partial update	PATCH	/items/{id}	200 / 404
Delete item	DELETE	/items/{id}	204 / 404
Search	GET	/items?q=term	200
Bulk action	POST	/items/batch	200 / 207

Documentation Requirements

Every endpoint must document:

HTTP method and path
Description
Request parameters (path, query, body) with types
Response schema with examples
Error codes and descriptions
Authentication requirements

Common Pitfalls

Using verbs in URLs — Use nouns: /users not /getUsers
Inconsistent error format — Use the same error schema everywhere
Missing pagination — Any list endpoint that can grow needs pagination
No versioning strategy — Decide early: URL (/v1/) or header-based

01 前言 Front Matter

02 资源文件 131

03 SKILL.md 正文

API Design

Overview

Key Concepts

Naming Conventions

HTTP Methods

Error Response Format

Status Codes

Decision Framework

Documentation Requirements

Common Pitfalls

04 同仓库更多 Skills

validation-diagnostics

security-analysis

release-notes

imagery-provider-adaptation

deterministic-scripts

dependency-update