Skip to content
cccskills
FreePublished on GitHub

api-conventions

API design patterns and conventions for this project. Covers RESTful URL naming, response format standards, error handling, and authentication requirements. Use when writing or reviewing API endpoints, designing new APIs, or making decisions about request/response formats.

The English summary is being prepared. Showing the original description.

See how to install

Files included (1)

  • SKILL.md1.7 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

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 },成功时为 null
  • meta: 分页和元信息,列表接口必须返回

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 @public annotation
  • Token format: Authorization: Bearer <jwt-token>

Versioning

  • API version in URL path: /api/v1/users
  • Breaking changes require new version

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

Generate API documentation from code. Use when the user wants to document APIs, create API reference, generate endpoint documentation, or needs help with OpenAPI/Swagger specs.

The English summary is being prepared. Showing the original description.

huangjia2019/claude-code-engineering1.1KUpdated Jul 23, 2026

Generate API endpoint documentation from Express route files. Use when the user asks to generate, update, or review API docs for Express.js routes.

The English summary is being prepared. Showing the original description.

huangjia2019/claude-code-engineering1.1KUpdated Jul 23, 2026

Generate API endpoint code and documentation from specifications. Use when the user wants to create new API endpoints, generate route handlers, scaffold REST APIs, or produce OpenAPI/Swagger specs from code.

The English summary is being prepared. Showing the original description.

huangjia2019/claude-code-engineering1.1KUpdated Jul 23, 2026

Perform a comprehensive code health check on a directory. Use when the user asks to analyze code quality, find issues, or get a health report.

The English summary is being prepared. Showing the original description.

huangjia2019/claude-code-engineering1.1KUpdated Jul 23, 2026

Review code for quality, security, and best practices. Use when the user asks for code review, wants feedback on their code, mentions reviewing changes, or asks about code quality.

The English summary is being prepared. Showing the original description.

huangjia2019/claude-code-engineering1.1KUpdated Jul 23, 2026

Generate an interactive tree visualization of your codebase. Use when exploring a new repo or understanding project structure.

The English summary is being prepared. Showing the original description.

huangjia2019/claude-code-engineering1.1KUpdated Jul 23, 2026

See all skills by huangjia2019

Report a problem with this skill