RESTful API design best practices. Use when designing endpoints, request/response schemas, error handling, and API versioning.
RESTful API design best practices. Use when designing endpoints, request/response schemas, error handling, and API versioning.
npx skills add https://github.com/aiyuekuang/LLMProxy --skill api-design复制此命令并粘贴到 Claude Code 中以安装该技能
Perform thorough code reviews with security, performance, and quality checks. Use when reviewing PRs, auditing code changes, or finding potential bugs.
Database design and optimization. Use for schema design, queries, migrations, indexing, and performance tuning.
Systematic debugging methodology for finding and fixing bugs. Use when investigating issues, tracing errors, or fixing production problems.
Docker and containerization best practices. Use for Dockerfile creation, docker-compose, multi-stage builds, and container optimization.
Technical documentation best practices. Use for writing READMEs, API docs, code comments, and project documentation.
Git and GitHub workflow best practices. Use for commits, branches, PRs, merging, and version control operations.
| name | api-design |
| description | RESTful API design best practices. Use when designing endpoints, request/response schemas, error handling, and API versioning. |
RESTful API design principles and patterns for building robust, scalable APIs.
# ✅ Good: Plural nouns, lowercase, hyphens
GET /api/v1/users
GET /api/v1/users/{id}
POST /api/v1/users
PUT /api/v1/users/{id}
DELETE /api/v1/users/{id}
GET /api/v1/api-keys
GET /api/v1/model-providers
# ❌ Bad: Verbs, camelCase, underscores
GET /api/v1/getUsers
POST /api/v1/createUser
GET /api/v1/api_keys
# User's API keys
GET /api/v1/users/{userId}/api-keys
POST /api/v1/users/{userId}/api-keys
# Model's versions
GET /api/v1/models/{modelId}/versions
| Method | Usage | Idempotent |
|---|---|---|
| GET | Retrieve resource(s) | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove resource | Yes |
{
"success": true,
"data": {
"id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"createdAt": "2024-01-15T10:30:00Z"
}
}
{
"success": true,
"data": [
{ "id": "1", "name": "Item 1" },
{ "id": "2", "name": "Item 2" }
],
"meta": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": [
{
"field": "email",
"message": "Invalid email format"
},
{
"field": "password",
"message": "Password must be at least 8 characters"
}
]
},
"requestId": "req_abc123"
}
| Code | Usage |
|---|---|
| 200 OK | General success, GET/PUT/PATCH |
| 201 Created | Resource created (POST) |
| 204 No Content | Success with no body (DELETE) |
| Code | Usage |
|---|---|
| 400 Bad Request | Invalid request format/data |
| 401 Unauthorized | Missing/invalid authentication |
| 403 Forbidden | Authenticated but not authorized |
| 404 Not Found | Resource doesn't exist |
| 409 Conflict | Resource conflict (duplicate) |
| 422 Unprocessable | Validation errors |
| 429 Too Many Requests | Rate limit exceeded |
| Code | Usage |
|---|---|
| 500 Internal Server Error | Unexpected server error |
| 502 Bad Gateway | Upstream service error |
| 503 Service Unavailable | Service temporarily down |
| 504 Gateway Timeout | Upstream timeout |
GET /api/v1/users?status=active&role=admin
GET /api/v1/models?provider=openai&type=chat
GET /api/v1/users?sort=createdAt:desc
GET /api/v1/users?sort=name:asc,createdAt:desc
# Offset-based (simple but slower for large datasets)
GET /api/v1/users?page=2&pageSize=20
# Cursor-based (better for large datasets)
GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20
GET /api/v1/users?fields=id,name,email
GET /api/v1/users?include=profile,settings
GET /api/v1/users?q=john
GET /api/v1/users?search=john@example
GET /api/v1/models
Authorization: Bearer sk-xxxxxxxxxxxxx
GET /api/v1/models?api_key=sk-xxxxxxxxxxxxx
GET /api/v1/users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
/api/v1/users
/api/v2/users
GET /api/users
API-Version: 2024-01-15
GET /api/users?version=2
openapi: 3.0.3
info:
title: LLMProxy API
version: 1.0.0
description: API for managing LLM proxy services
servers:
- url: https://api.llmproxy.io/v1
paths:
/models:
get:
summary: List all models
tags: [Models]
parameters:
- name: provider
in: query
schema:
type: string
enum: [openai, anthropic, azure]
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: List of models
content:
application/json:
schema:
$ref: '#/components/schemas/ModelListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
Model:
type: object
required: [id, name, provider]
properties:
id:
type: string
example: "model_123"
name:
type: string
example: "gpt-4"
provider:
type: string
enum: [openai, anthropic, azure]
ModelListResponse:
type: object
properties:
success:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Model'
meta:
$ref: '#/components/schemas/PaginationMeta'
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Retry-After: 60