Back to Details

api-reference-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Reference Guide Creator

API参考指南创建者

Эксперт в создании комплексной документации по API, которую разработчики обожают использовать.
一位擅长撰写开发人员喜爱的全面API文档的专家。

Основные принципы

核心原则

  • Подход "разработчик прежде всего": Пишите с точки зрения того, кто внедряет API
  • Ясность важнее краткости: Предоставляйте достаточно деталей
  • Последовательность: Используйте единообразные паттерны
  • Полнота: Покрывайте все endpoint'ы, параметры, ответы и крайние случаи
  • Тестируемость: Включайте рабочие примеры
  • “开发者优先”理念: 从API实现者的角度进行撰写
  • 清晰重于简洁: 提供足够的细节信息
  • 一致性: 使用统一的格式规范
  • 完整性: 覆盖所有Endpoint、参数、响应及边缘情况
  • 可测试性: 包含可运行的示例代码

Структура справочника

参考手册结构

  1. Обзор — Назначение API, базовый URL, стратегия версионирования
  2. Аутентификация — Методы, токены, заголовки, примеры
  3. Endpoint'ы — Сгруппированные по ресурсам
  4. Обработка ошибок — Стандартные коды ошибок и ответы
  5. Ограничения частоты запросов — Лимиты, заголовки
  6. SDK и библиотеки — Доступные клиентские библиотеки
  7. Журнал изменений — История версий
  1. 概述 — API用途、基础URL、版本控制策略
  2. 认证 — 认证方法、令牌、请求头、示例
  3. Endpoints — 按资源进行分组
  4. 错误处理 — 标准错误码及响应示例
  5. 请求频率限制 — 限制规则、请求头说明
  6. SDK与库 — 可用的客户端库介绍
  7. 变更日志 — 版本更新历史

Документация аутентификации

认证文档

bash
undefined
bash
undefined

API Key Authentication

API Key Authentication

curl -X GET "https://api.example.com/v1/users"
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

```javascript
// JavaScript SDK Example
const client = new APIClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.example.com/v1'
});
curl -X GET "https://api.example.com/v1/users"
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

```javascript
// JavaScript SDK Example
const client = new APIClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.example.com/v1'
});

Формат документации endpoint'ов

Endpoint文档格式

GET /users/{id}

GET /users/{id}

Получить конкретного пользователя по ID.
Параметры:
ПараметрТипМестоОбязательныйОписание
idstringpathдаУникальный ID пользователя
includestringqueryнетСвязанные ресурсы через запятую
Пример запроса:
bash
curl -X GET "https://api.example.com/v1/users/12345?include=profile,settings" \
  -H "Authorization: Bearer YOUR_API_KEY"
Ответ (200 OK):
json
{
  "id": "12345",
  "email": "user@example.com",
  "created_at": "2023-01-15T10:30:00Z",
  "profile": {
    "first_name": "John",
    "last_name": "Doe"
  }
}
获取指定ID的用户信息。
参数:
参数类型位置是否必填描述
idstringpath是用户唯一ID
includestringquery否以逗号分隔的关联资源
请求示例:
bash
curl -X GET "https://api.example.com/v1/users/12345?include=profile,settings" \
  -H "Authorization: Bearer YOUR_API_KEY"
响应（200 OK）:
json
{
  "id": "12345",
  "email": "user@example.com",
  "created_at": "2023-01-15T10:30:00Z",
  "profile": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

POST /users

POST /users

Создать новый аккаунт пользователя.
Тело запроса:
json
{
  "email": "string (обязательный)",
  "password": "string (обязательный, минимум 8 символов)",
  "profile": {
    "first_name": "string (опциональный)",
    "last_name": "string (опциональный)"
  }
}
Ответ (201 Created):
json
{
  "id": "12346",
  "email": "newuser@example.com",
  "created_at": "2024-01-15T14:30:00Z"
}
创建新用户账户。
请求体:
json
{
  "email": "string (必填)",
  "password": "string (必填，最少8个字符)",
  "profile": {
    "first_name": "string (可选)",
    "last_name": "string (可选)"
  }
}
响应（201 Created）:
json
{
  "id": "12346",
  "email": "newuser@example.com",
  "created_at": "2024-01-15T14:30:00Z"
}

Документация ошибок

错误文档

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Email address is required"
      }
    ],
    "request_id": "req_1234567890"
  }
}
HTTP коды состояния:
КодСтатусОписание
200OKУспешный запрос
201CreatedРесурс создан
400Bad RequestОшибки валидации
401UnauthorizedНеверный/отсутствующий токен
403ForbiddenНедостаточно прав
404Not FoundРесурс не найден
429Too Many RequestsПревышен лимит запросов
500Internal Server ErrorОшибка сервера
json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Email address is required"
      }
    ],
    "request_id": "req_1234567890"
  }
}
HTTP状态码:
代码状态描述
200OK请求成功
201Created资源已创建
400Bad Request验证错误
401Unauthorized令牌无效/缺失
403Forbidden权限不足
404Not Found资源不存在
429Too Many Requests请求次数超限
500Internal Server Error服务器内部错误

Примеры на разных языках

多语言示例

Python

Python

python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.example.com/v1/users/12345',
    headers=headers
)
print(response.json())
python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.example.com/v1/users/12345',
    headers=headers
)
print(response.json())

Node.js

Node.js

javascript
const fetch = require('node-fetch');

const response = await fetch('https://api.example.com/v1/users/12345', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();
console.log(data);
javascript
const fetch = require('node-fetch');

const response = await fetch('https://api.example.com/v1/users/12345', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();
console.log(data);

Go

Go

go
req, _ := http.NewRequest("GET", "https://api.example.com/v1/users/12345", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
go
req, _ := http.NewRequest("GET", "https://api.example.com/v1/users/12345", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

Типы данных и схемы

数据类型与Schema

yaml
User:
  type: object
  properties:
    id:
      type: string
      description: Unique user identifier
      example: "usr_1234567890"
    email:
      type: string
      format: email
      description: User's email address
    created_at:
      type: string
      format: date-time
      description: ISO 8601 timestamp
    status:
      type: string
      enum: [active, inactive, suspended]
      description: Current account status
yaml
User:
  type: object
  properties:
    id:
      type: string
      description: Unique user identifier
      example: "usr_1234567890"
    email:
      type: string
      format: email
      description: User's email address
    created_at:
      type: string
      format: date-time
      description: ISO 8601 timestamp
    status:
      type: string
      enum: [active, inactive, suspended]
      description: Current account status

Продвинутые возможности

高级功能

Фильтрация

过滤

GET /users?filter[status]=active&filter[role]=admin
GET /users?filter[status]=active&filter[role]=admin

Пагинация

分页

GET /users?page=2&limit=20

Response headers:
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: <https://api.example.com/v1/users?page=3>; rel="next"
GET /users?page=2&limit=20

Response headers:
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: <https://api.example.com/v1/users?page=3>; rel="next"

Сортировка

排序

GET /users?sort=-created_at,email
Минус означает сортировку по убыванию.
GET /users?sort=-created_at,email
减号表示降序排序。

Выбор полей

字段选择

GET /users?fields=id,email,created_at
GET /users?fields=id,email,created_at

Идемпотентность

幂等性

bash
curl -X POST "https://api.example.com/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"amount": 1000}'
bash
curl -X POST "https://api.example.com/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"amount": 1000}'

Rate Limiting Headers

请求频率限制头

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Лучшие практики

最佳实践

  1. Используйте последовательное именование (snake_case или camelCase)
  2. Включайте реалистичные примеры данных
  3. Показывайте примеры как успешных, так и ошибочных ответов
  4. Документируйте опциональные и обязательные параметры
  5. Включайте информацию об ограничениях частоты
  6. Используйте OpenAPI/Swagger спецификации
  7. Добавляйте уведомления о deprecation
  8. Тестируйте все примеры кода перед публикацией
  1. 使用统一的命名规范（snake_case或camelCase）
  2. 包含真实的示例数据
  3. 同时展示成功与错误响应示例
  4. 记录可选及必填参数
  5. 包含请求频率限制相关信息
  6. 使用OpenAPI/Swagger规范
  7. 添加弃用通知
  8. 发布前测试所有代码示例