# PingCAP Account API 文档

## 说明

> 所有的 API 调用都有频率限制，未认证用户 30 次/分钟, 认证用户 100 次/分钟  
> i18n支持(zh-hans/en-us), 在请求 Header 中声明： Accept-Language: zh-hans  
> 当 cookie 中有 csrftoken 时, put|post|delete|patch 等请求需在 header 中声明: X-CSRFTOKEN

- [用户反馈信息收集](#用户反馈信息收集)
- [官网商业用户下载信息收集](#官网商业用户下载信息收集)
- [获取用户当前积分](#获取用户当前积分)
- [获取用户经验排行榜](#获取用户经验排行榜)
- [获取 AskTUG 徽章列表](#获取-AskTUG-徽章列表)
- [获取用户徽章数量排行榜](#获取用户徽章数量排行榜)


### 用户反馈信息收集

#### Requeest

- Method: **POST**
- URL: `/api/customer-support/contact-us`
- Content-Type: application/json
- 跨域时需额外设置 withCredentials
- Body:
  ```json
  {
    "page_url": "https://asktug.com/t/topic/2694",
    "spend_time": 500,   // 单位: 秒
    "name": "张三",
    "company": "公司",
    "department": "部门",
    "phone": "13600000000",
    "wechat_number": "",
    "body": {   // custom fileds
      "目前使用的 TiDB 版本号": "v4.0.0",
      // ....
    }
  }
  ```

### Response

- Success

  - HTTP/1.1 200
    ```json
    {
      "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params wrong",
      "errors": {
        "phone": ["invalid phone"],
        "body": ["invalid body, required json(object)"]
      }
    }
    ```


### 官网商业用户下载信息收集

#### Requeest

- Method: **POST**
- URL: `/api/customer-support/business-download-leads`
- Content-Type: application/json
- Body:
  ```json
  {
    "name": "张三",  // 必填, 最大长度 64
    "company": "公司",  // 必填, 最大长度 255
    "phone": "13600000000",  // 必填, 手机号长度 11 位
    "email": "xx@example.com",  // 必填, 邮箱
  }
  ```

### Response

- Success

  - HTTP/1.1 200
    ```json
    {
      "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params wrong",
      "errors": {
        "phone": ["invalid phone"],
      }
    }
    ```


### 获取用户当前积分

#### Requeest

- Method: **POST**
- URL: `/api/points/public/{username}`
- Content-Type: application/json


### Response

- Success

  - HTTP/1.1 200
    ```json
    {
      "user": {
        "username": "mock_user",
        "avatar_url": "https://www.gravatar.com/avatar/fcb8bb2d4c044660c192539e14e925af?d=identicon"
      },
      "current_level": 3,   // 当前等级
      "current_exp": 2371,  // 当前经验
      "level_desc": {
        "min_exp": 2000,     // 当前等级要求的最低经验
        "max_exp": 5000,     // 当前等级要求的最高经验
        "progress": 0.1236,   // 用户当前进度 
      }
    }
    ```

- Failed

  - HTTP/1.1 404

    ```json
    {
      "detail": "Not found"
    }
    ```


### 获取用户经验排行榜

#### Requeest

- Method: **POST**
- URL: `/api/points/top?limit=3&period=weekly`
- Params:
  | 参数名 | 类型 | 默认值 | 说明 |
  | ---- | ---- | ---- | ----- |
  | limit | int | 50 | 排行榜前多少名，合理范围 [1, 100]|
  | period | string | all | 周期，取值: all, weekly, monthly, yearly|
- Content-Type: application/json


### Response

- Success

  - HTTP/1.1 200
    ```json
    {
      "data": [
        {
          "ranking": 1, // 排名
          "user": {
            "username": "东北大胖子",
            "avatar_url": "https://www.gravatar.com/avatar/a35d7e100f8ff15a15c5d0cf0118acc6?d=identicon",
          },
          "exps": 14813,  // 经验值
        },
        {
          "ranking": 1, // 排名
          "user": {
            "username": "yilong",
            "avatar_url": "https://www.gravatar.com/avatar/a35d7e100f8ff15a15c5d0cf0118acc6?d=identicon",
          },
          "exps": 14811,  // 经验值
        },
        {
          "ranking": 1, // 排名
          "user": {
            "username": "GangShen",
            "avatar_url": "https://www.gravatar.com/avatar/a35d7e100f8ff15a15c5d0cf0118acc6?d=identicon",
          },
          "exps": 6155,  // 经验值
        }
      ],
      "limit": 3,       // 当前传入的参数，前 3 名
      "period": "all",  // 当前传入的参数，历史总榜
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "limit should between 1 ~ 100"
    }
    ```

### 获取 AskTUG 徽章列表

#### Requeest

- Method: **POST**
- URL: `/api/asktug/badges`
- Content-Type: application/json
- Permission: Authenticated user

### Response

- Success

  - HTTP/1.1 200

    ```json
    {
      "data": [
        {
          "id": 111,   // 徽章 ID
          "name": "Contributor",  // 徽章名称
          "image": "https://img2.pingcap.com/forms/3/5/35e40ac2a66e842044ecc4cb9b805450f066a1e3.png",  // 徽章图片, 可能为空, image 的展示优先级高于 icon
          "icon": "fa-certificate",    // 徽章 icon, 可能为空
          "has_badge": true   // 是否拥有该徽章
        },
        {
          "id": 133,
          "name": "高级贡献者",
          "image": "https://img2.pingcap.com/forms/9/7/97e13e292e488741bc6052bb57859e0cc2ef205a.png!thumb",
          "icon": "3",
          "has_badge": false
        }
      ]
    }
    ```

- Failed

  - HTTP/1.1 401

    ```json
    {
      "detail": "Authentication credentials were not provided"
    }
    ```


### 获取用户徽章数量排行榜

#### Requeest

- Method: **POST**
- URL: `/api/asktug/badges/top?limit=3&period=weekly`
- Params:
  | 参数名 | 类型 | 默认值 | 说明 |
  | ---- | ---- | ---- | ----- |
  | limit | int | 50 | 排行榜前多少名，合理范围 [1, 100]|
  | period | string | all | 周期，取值: all, weekly, monthly, yearly|
- Content-Type: application/json


### Response

- Success

  - HTTP/1.1 200
    ```json
    {
      "data": [
        {
          "ranking": 1, // 排名
          "user": {
            "username": "东北大胖子",
            "avatar_url": "https://www.gravatar.com/avatar/a35d7e100f8ff15a15c5d0cf0118acc6?d=identicon",
          },
          "count": 17,  // 徽章数量
        },
        {
          "ranking": 1, // 排名
          "user": {
            "username": "yilong",
            "avatar_url": "https://www.gravatar.com/avatar/a35d7e100f8ff15a15c5d0cf0118acc6?d=identicon",
          },
          "count": 16,  // 徽章数量
        },
        {
          "ranking": 1, // 排名
          "user": {
            "username": "GangShen",
            "avatar_url": "https://www.gravatar.com/avatar/a35d7e100f8ff15a15c5d0cf0118acc6?d=identicon",
          },
          "count": 15,  // 徽章数量
        }
      ],
      "limit": 3,       // 当前传入的参数，前 3 名
      "period": "all",  // 当前传入的参数，历史总榜
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "limit should between 1 ~ 100"
    }
    ```