# 字体元数据 REST API（维护中）

> 适合谁看：想用程序查询文风字体目录（字体列表、详情、分类、厂商）的开发者。只想在网页里用字体的，不需要这个 API，看[《快速开始：一行代码用上中文网页字体》](https://docs.cocobook.com/link/647)。

> **维护中：** 这组接口目前暂时无法访问。下面按现有程序整理，接口恢复后会再核对一遍字段和示例。网页字体的 CSS 引用不受影响。

## 基本约定

- 基址：`https://app.windfonts.com/api`
- 只介绍查询类接口，全部是 `GET`。
- 返回 JSON，外层结构固定：

```json
{
  "code": 200,
  "message": "…",
  "data": { }
}
```

`code` 为 200 表示成功。

旧接口 `POST /api/fonts/list` 已经下线，请改用下面的 `GET /api/fonts`。

## 认证和额度

- 不带密钥也能调用，但每天有基础额度（100 次）。超过后返回 429。
- 需要更高额度请联系文风。拿到密钥后，任选一种方式放在请求头里：

```
X-API-Key: 你的密钥
Authorization: Bearer 你的密钥
```

- 不要把密钥写进公开网页的前端代码。
- 不要在每次打开页面时都去拉整份字体列表。列表可以在构建网站时拉一次存下来，详情按需再查。

## 字体列表

```
GET /api/fonts
```

| 参数 | 说明 |
|---|---|
| `page` | 页码，从 1 开始，默认 1 |
| `size` | 每页条数，默认 20，最大 100 |
| `categoryId` | 分类 ID，见下面「分类」 |
| `brandId` | 厂商 ID，见下面「厂商」 |
| `search` | 关键词，也可以写成 `q` |
| `tags` | 标签，多个用英文逗号分隔 |
| `sort` | 排序字段：`name`、`createdAt`、`viewCount`、`downloadCount` |
| `order` | `asc` 或 `desc` |

示例：

```
GET https://app.windfonts.com/api/fonts?page=1&size=20&sort=viewCount&order=desc
```

`data` 的结构：

| 字段 | 说明 |
|---|---|
| `total` | 符合条件的字体总数 |
| `page` | 当前页 |
| `pageTotal` | 总页数 |
| `dataList` | 本页字体，每项是一款字的元数据，并带上所属分类和厂商 |

## 单款字体

```
GET /api/fonts/{id 或目录名}
```

路径里可以写字体 ID，也可以写目录名（字体页网址最后一段），例如 `/api/fonts/xwwk`。

同一款字还有两个附加接口：

| 接口 | 说明 |
|---|---|
| `GET /api/fonts/{id 或目录名}/analysis` | 字符覆盖分析。没有分析数据时返回 404 |
| `GET /api/fonts/{id 或目录名}/estimate?subset=full` | 各子集的体积预估。`subset` 可取 `en`、`zh-common`、`zh`、`full` |

## 分类和厂商

```
GET /api/categories
GET /api/brands
```

分别返回全部分类、全部厂商（品牌）。拿到的 ID 可以用在字体列表的 `categoryId`、`brandId` 参数里。

## 出错时

出错时返回：

```json
{ "code": 429, "errorCode": "rate_limited", "message": "…" }
```

| HTTP 状态 | `errorCode` | 含义 |
|---|---|---|
| 401 | `invalid_api_key_format` | 密钥格式不对 |
| 403 | `domain_blocked` | 来源网站被拒绝访问 |
| 429 | `rate_limited` | 超过当天额度 |
| 500 | `internal_error` | 服务端出错 |

## 不要依赖的字段

`dataList` 和单款详情里会带不少字段。除了上面写到的，其余字段可能随时调整，接口恢复后会再核对并在[《更新记录》](https://docs.cocobook.com/link/654) 里说明。

## 接下来读什么

- [《开发常见问题》](https://docs.cocobook.com/link/653)
- [《更新记录》](https://docs.cocobook.com/link/654)