Api conventions

Skill huangjia2019/claude-code-engineering/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions

This repository demonstrates how to use Claude Code to do real engineering work, not just writing code. 本项目是极客时间专栏《Claude Code 工程化实战》的官方配套示例仓库，目标就是： 👉 把 Claude Code 从“对话式编码工具”，变成可设计、可复用、可治理的工程系统。

Install

npx -y skills add huangjia2019/claude-code-engineering --skill api-conventions

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

1.7 KB, as published. Nobody here has run it

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