用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/pluginagentmarketplace/custom-plugin-api-design --skill rest命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | rest |
| version | 2.0.0 |
| description | RESTful API design principles and best practices |
| sasmp_version | 1.3.0 |
| bonded_agent | 01-api-architect |
| bond_type | PRIMARY_BOND |
| atomic_design | {"single_responsibility":"REST API design patterns and conventions","boundaries":{"includes":["resource_design","http_methods","status_codes","pagination","filtering"],"excludes":["graphql","grpc","implementation_code"]}} |
| parameter_validation | {"schema":{"type":"object","properties":{"resource_name":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"http_method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE","OPTIONS","HEAD"]},"response_format":{"type":"string","enum":["json","xml","hal","jsonapi"]}}}} |
| retry_config | {"enabled":true,"max_attempts":3,"backoff":{"type":"exponential","initial_delay_ms":1000,"max_delay_ms":30000}} |
| logging | {"level":"INFO","fields":["resource","method","status_code","duration_ms"]} |
| dependencies | {"skills":["api-architecture"],"agents":["01-api-architect"]} |
Design RESTful APIs following industry best practices.
| Method | Action | Idempotent | Safe | Request Body | Response Body |
|---|---|---|---|---|---|
| GET | Read | Yes | Yes | No | Yes |
| POST | Create | No | No | Yes | Yes |
| PUT | Replace | Yes | No | Yes | Yes |
| PATCH | Update | No | No | Yes | Yes |
| DELETE | Delete | Yes | No | No | No |
| HEAD | Metadata | Yes | Yes | No | No |
| OPTIONS | Capabilities | Yes | Yes | No | Yes |
200 OK → GET, PUT, PATCH success
201 Created → POST success (include Location header)
202 Accepted → Async operation started
204 No Content → DELETE success
400 Bad Request → Validation failed
401 Unauthorized → Authentication required
403 Forbidden → Permission denied
404 Not Found → Resource doesn't exist
409 Conflict → State conflict (duplicate, etc.)
422 Unprocessable → Semantic errors
429 Too Many → Rate limit exceeded
500 Internal → Unexpected error
502 Bad Gateway → Upstream failed
503 Unavailable → Temporarily down
504 Timeout → Upstream timeout
# Collection operations
GET /api/v1/users → List (paginated)
POST /api/v1/users → Create
# Instance operations
{
"data": {
"id": "123",
"type": "user",
"attributes": {
"name": "John Doe",
"email": "john@example.com"
}
},
"meta": {
"requestId": "abc-123",
"timestamp": "2024-12-30T10:00:00Z",
"version": "1.0.0"
}
}
{
"type": "https://api.example.com/errors/validation",
"title": "Validation Failed",
"status": 400,
"detail": "One or more fields have validation errors",
"instance": "/api/v1/users",
"errors": [
{ "field": "email", "message": "Invalid email format" },
{ "field": "password", "message": "Minimum 12 characters" }
]
}
GET /api/v1/users?page=2&limit=20
Response:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 150,
"totalPages": 8,
"hasNext": true,
"hasPrev": true
}
}
GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20
Response:
{
"data": [...],
"pagination": {
"nextCursor": "eyJpZCI6MTIwfQ",
"prevCursor": "eyJpZCI6ODB9",
"hasNext": true,
"hasPrev": true
}
}
# Filtering
GET /api/v1/users?status=active&role=admin
GET /api/v1/users?created_at[gte]=2024-01-01
GET /api/v1/users?search=john
# Sorting
GET /api/v1/users?sort=created_at:desc
GET /api/v1/users?sort=-created_at,name # - prefix for desc
# Field selection
GET /api/v1/users?fields=id,name,email
# Embedding related resources
GET /api/v1/users?include=orders,profile
# Response headers
Cache-Control: public, max-age=3600
ETag: "abc123"
Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT
Vary: Accept-Encoding, Authorization
# Conditional requests
If-None-Match: "abc123"
If-Modified-Since: Wed, 21 Oct 2024 07:28:00 GMT
import { describe, it, expect } from 'vitest';
import request from 'supertest';
import app from './app';
describe('REST API - Users', () => {
describe('GET /api/v1/users', () => {
it('should return paginated users', async () => {
const res = await request(app)
.get('/api/v1/users?page=1&limit=10')
.expect(200);
expect(res.body).toHaveProperty('data');
expect(res.body).toHaveProperty('pagination');
expect(res.body.pagination.page).toBe(1);
});
it('should filter by status', async () => {
const res = await request(app)
.get('/api/v1/users?status=active')
.expect(200);
res.body.data.forEach(user => {
expect(user.status).toBe('active');
});
});
});
describe('POST /api/v1/users', () => {
it('should create user and return 201', async () => {
const res = await request(app)
.post('/api/v1/users')
.send({ email: 'test@example.com', name: 'Test' })
.expect(201);
expect(res.headers.location).toMatch(/\/api\/v1\/users\/\w+/);
expect(res.body.data.id).toBeDefined();
});
it('should return 400 for invalid data', async () => {
const res = await request(app)
.post('/api/v1/users')
.send({ email: 'invalid' })
.expect(400);
expect(res.body.type).toContain('validation');
});
});
describe('GET /api/v1/users/:id', () => {
it('should return 404 for non-existent user', async () => {
await request(app)
.get('/api/v1/users/non-existent-id')
.expect(404);
});
});
});
| Issue | Cause | Solution |
|---|---|---|
| 404 for valid resource | Trailing slash mismatch | Normalize URLs |
| CORS errors | Missing headers | Configure CORS middleware |
| Slow pagination | Large offset | Use cursor pagination |
| Cache not working | Missing Vary header | Add Vary: Authorization |