From charon-fan-agent-playbook
Designs REST and GraphQL APIs with resource-oriented principles, HTTP methods, status codes, pagination, filtering, sorting, and schema design. Use when designing new APIs or improving existing ones.
npx claudepluginhub zhaono1/agent-playbookThis skill is limited to using the following tools:
Expert in designing REST and GraphQL APIs that are robust, scalable, and maintainable.
Designs REST and GraphQL APIs with endpoints, HTTP status codes, response formats, error handling, versioning, authentication, and OpenAPI documentation.
Designs REST and GraphQL APIs including endpoint design, authentication, versioning, documentation, and best practices. Use for backend API creation, contracts, or third-party integrations.
Designs REST and GraphQL APIs with OpenAPI 3.1 specifications, including resource modeling, versioning strategies, pagination patterns, and error handling standards.
Share bugs, ideas, or general feedback.
Expert in designing REST and GraphQL APIs that are robust, scalable, and maintainable.
Activates when you:
Good:
GET /users # List users
POST /users # Create user
GET /users/{id} # Get specific user
PATCH /users/{id} # Update user
DELETE /users/{id} # Delete user
Avoid:
POST /getUsers # Should be GET
POST /users/create # Redundant
GET /users/get/{id} # Redundant
| Method | Safe | Idempotent | Purpose |
|---|---|---|---|
| GET | ✓ | ✓ | Read resource |
| POST | ✗ | ✗ | Create resource |
| PUT | ✗ | ✓ | Replace resource |
| PATCH | ✗ | ✗ | Update resource |
| DELETE | ✗ | ✓ | Delete resource |
| Code | Meaning | Usage |
|---|---|---|
| 200 | OK | Successful GET, PATCH, DELETE |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE with no body |
| 400 | Bad Request | Invalid input |
| 401 | Unauthorized | Missing or invalid auth |
| 403 | Forbidden | Authenticated but not authorized |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource already exists |
| 422 | Unprocessable | Valid syntax but semantic errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
/user-preferences){"userId": "123"})?page_size=10)GET /users?page=1&page_size=20
Response:
{
"data": [...],
"pagination": {
"page": 1,
"page_size": 20,
"total": 100,
"total_pages": 5
}
}
GET /users?status=active&sort=-created_at,name
# -created_at = descending
# name = ascending
type Query {
user(id: ID!): User
users(limit: Int, offset: Int): UserConnection!
}
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}
type User {
id: ID!
email: String!
profile: Profile
posts(first: Int, after: String): PostConnection!
}
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
URL Versioning (Recommended):
/api/v1/users
/api/v2/users
Header Versioning:
GET /users
Accept: application/vnd.myapi.v2+json
Authorization: Bearer <token>
X-API-Key: <key>
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1631234567
Recommended limits:
Generate API scaffold:
python scripts/generate_api.py <resource-name>
Validate API design:
python scripts/validate_api.py openapi.yaml
references/rest-patterns.md - REST design patternsreferences/graphql-patterns.md - GraphQL design patterns