---
name: API Conventions
slug: api-conventions
category: AI Engineering
description: API Conventions defines REST URL naming, response shapes, status codes, and authentication rules for this project. Use it when designing or reviewing endpoints and request or response formats.
github: "https://github.com/huangjia2019/claude-code-engineering/tree/main/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions"
language: JavaScript
stars: 1077
forks: 379
install: "npx degit https://github.com/huangjia2019/claude-code-engineering/tree/main/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions ~/.claude/skills/api-conventions"
installs_to: ~/.claude/skills/api-conventions
source_path: 04-Skills/projects/01-reference-skill/.claude/skills/api-conventions/SKILL.md
collection_size: 13
category_size: 2451
collection_url: "https://dirskills.com/collections/huangjia2019/claude-code-engineering"
added: 2026-08-21T05:13:26.969Z
last_synced: 2026-08-21T05:13:26.969Z
canonical_url: "https://dirskills.com/skills/api-conventions"
---

# API Conventions

API Conventions defines REST URL naming, response shapes, status codes, and authentication rules for this project. Use it when designing or reviewing endpoints and request or response formats.

**Install:**

```bash
npx degit https://github.com/huangjia2019/claude-code-engineering/tree/main/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions ~/.claude/skills/api-conventions
```

## README

# 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