api-conventions
Scannednpx machina-cli add skill huangjia2019/claude-code-engineering/api-conventions --openclawFiles (1)
SKILL.md
1.7 KB
API Design Conventions
These are the API design standards for our project. Apply these conventions whenever working with API endpoints.
URL Naming
- Use plural nouns for resources:
/users,/orders,/products - Use kebab-case for multi-word resources:
/order-items,/user-profiles - Nested resources for belongsTo relationships:
/users/{id}/orders - Maximum two levels of nesting; beyond that, use query parameters
- Use query parameters for filtering:
/orders?status=active&limit=20
Response Format
All API responses must follow this structure:
{
"data": {},
"error": null,
"meta": {
"page": 1,
"limit": 20,
"total": 100
}
}
data: 成功时返回的业务数据error: 错误时返回错误对象{ code, message, details }，成功时为nullmeta: 分页和元信息，列表接口必须返回
HTTP Status Codes
- 200: 成功返回数据
- 201: 成功创建资源
- 400: 请求参数错误
- 401: 未认证
- 403: 无权限
- 404: 资源不存在
- 422: 业务逻辑错误
- 500: 服务器内部错误
Authentication
- All endpoints require Bearer token unless explicitly marked as public
- Public endpoints must be documented with
@publicannotation - Token format:
Authorization: Bearer <jwt-token>
Versioning
- API version in URL path:
/api/v1/users - Breaking changes require new version
Source
git clone https://github.com/huangjia2019/claude-code-engineering/blob/main/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions/SKILL.mdView on GitHub Overview
Defines consistent patterns for RESTful URL naming, response envelopes, error handling, authentication, and versioning. It guides when designing, reviewing, or updating APIs to ensure predictable, scalable interfaces.
How This Skill Works
URLs use plural nouns and kebab-case with limited nesting. All responses follow a standard envelope { data, error, meta } and appropriate HTTP status codes. Authentication uses Bearer tokens, public endpoints are annotated with @public, and API versioning lives in the URL path.
When to Use It
- When creating a new REST resource (e.g., /users, /orders)
- When auditing or reviewing existing endpoints for consistency
- When deciding URL naming, nesting, or filtering strategies (e.g., /orders?status=active)
- When defining the standard response envelope, error shapes, and meta fields
- When enforcing authentication and documenting public endpoints
Quick Start
- Step 1: Apply URL naming rules to new or existing endpoints (plural nouns, kebab-case, max two levels)
- Step 2: Wrap responses in the standard envelope and implement the error object schema (code, message, details)
- Step 3: Enforce Bearer token authentication and annotate public endpoints with @public; place API version in the URL path
Best Practices
- Use plural nouns for resources (e.g., /users)
- Use kebab-case for multi-word resources (e.g., /order-items, /user-profiles)
- Nest only up to two levels; beyond that, use query parameters to avoid deep hierarchies
- Return a standard envelope: { data, error, meta }; include error.code, error.message, error.details
- Apply consistent HTTP status codes (200, 201, 400, 401, 403, 404, 422, 500) and enforce Bearer token authentication
Example Use Cases
- GET /users with data and meta paging info in the response envelope
- GET /users/{id}/orders demonstrating two-level nesting
- POST /orders returning 201 with created resource in data
- GET /orders?status=active&limit=20 showcasing query-based filtering
- Unauthorized access returns 401 with a structured error object
Frequently Asked Questions
Add this skill to your agents
