Skill828 repo starsupdated 13d ago

api-conventions

The api-conventions skill provides standardized guidelines for API design including RESTful URL naming conventions using plural nouns and kebab-case, required response format with data/error/meta structure, HTTP status code usage, Bearer token authentication requirements, and API versioning in URL paths. Use this when designing new endpoints, writing API implementations, or reviewing API code to ensure consistency across the project.

View source Repository: claude-code-engineering

Install in Claude Code

Copy

git clone --depth 1 https://github.com/huangjia2019/claude-code-engineering /tmp/api-conventions && cp -r /tmp/api-conventions/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions ~/.claude/skills/api-conventions

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

# 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:

```json
{
  "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