Fever API 中文文档-机翻

# 公开测试版 API

## 信息

目前它是[http://www.feedafever.com/api](http://www.feedafever.com/api)的副本，但格式为 Markdown 文件。

在本文档的末尾，有一些 API 的未记录内容。

## 描述

Fever 1.14 引入了新的 Fever API。这个 API 目前处于公开测试阶段，支持基本的同步和内容消费。后续更新将允许添加、编辑和删除订阅源及分组。API 的主要关注点是在远程 Fever 安装中维护本地数据缓存。

我在[征求反馈](http://www.feedafever.com/contact)，因此测试版 API 可能会根据这些反馈进行扩展。当前的 API 尚未完整但稳定。现有功能可能会扩展，但不会被删除或修改。可能会添加新功能。

我创建了一个简单的 [HTML 小部件](http://www.feedafever.com/gateway/public/api-widget.html.zip)，允许你查询 Fever API 并查看响应。

# 认证

不多说，Fever API 端点 URL 如下所示：

`http://yourdomain.com/fever/?api`

所有请求必须通过 `POST` 提交的 `api_key` 进行认证。`api_key` 的值应为 Fever 账户的电子邮件地址和密码连同冒号一起的 md5 校验和。使用 PHP 的原生 `md5()` 函数的 `api_key` 的有效值示例：

```php
$email  = 'you@yourdomain.com';
$pass   = 'b3stp4s4wd3v4';
$api_key = md5($email.':'.$pass);
```

用户可以指定使用 `https` 连接到他们的 Fever 安装以增加安全性，但你不应假设所有 Fever 安装都支持 `https`。

默认响应是一个包含两个成员的 JSON 对象：

* `api_version` 包含响应的 API 版本（正整数）
* `auth` 是否成功认证请求（布尔整数）

API 也可以通过如下方式传递 `xml` 作为 `api` 参数的可选值来返回 XML：

`http://yourdomain.com/fever/?api=xml`

最顶层的 XML 元素名为 `response`。

每个成功认证的请求的响应将设置 `auth` 为 `1` 并至少包括一个附加成员：

* `last_refreshed_on_time` 包含最近刷新（不是*更新*）的订阅源的时间（Unix 时间戳/整数）

当从 Fever API 读取时，你需要将参数添加到 API 端点 URL 的查询字符串中。如果你尝试 `POST` 这些参数（及其可选值），Fever 将不识别请求。

## 组

`http://yourdomain.com/fever/?api&groups`

带有 groups 参数的请求将返回两个附加成员：

* `groups` 包含一组 `group` 对象的数组
* `feeds_groups` 包含一组 `feeds_group` 对象的数组

一个 `group` 对象具有以下成员：

* `id`（正整数）
* `title`（utf-8 字符串）

`feeds_group` 对象在“Feeds/Groups Relationships”下有记录。

不包括在此响应中的“Kindling”超级组，它由所有 `is_spark` 等于 `0` 的订阅源组成。不包括在此响应中的“Sparks”超级组，它由所有 `is_spark` 等于 `1` 的订阅源组成。

## 订阅源

`http://yourdomain.com/fever/?api&feeds`

带有 `feeds` 参数的请求将返回两个附加成员：

* `feeds` 包含一组 `group` 对象的数组
* `feeds_groups` 包含一组 `feeds_group` 对象的数组

一个 `feed` 对象具有以下成员：

* `id`（正整数）
* `favicon_id`（正整数）
* `title`（utf-8 字符串）
* `url`（utf-8 字符串）
* `site_url`（utf-8 字符串）
* `is_spark`（布尔整数）
* `last_updated_on_time`（Unix 时间戳/整数）

`feeds_group` 对象在“Feeds/Groups Relationships”下有记录。

不包括在此响应中的“所有项目”超级订阅源，它由属于某个组的所有订阅源的所有项目组成。对于“Kindling”超级组和所有用户创建的组，项目应限于 `is_spark` 等于 `0` 的订阅源。对于“Sparks”超级组，项目应限于 `is_spark` 等于 `1` 的订阅源。

## 订阅源/组关系

带有 `groups` 或 `feeds` 参数的请求将返回一个附加成员：

一个 `feeds_group` 对象具有以下成员：

* `group_id`（正整数）
* `feed_ids`（字符串/正整数的逗号分隔列表）

## 图标

`http://yourdomain.com/fever/?api&favicons`

带有 `favicons` 参数的请求将返回一个附加成员：

* `favicons` 包含一组 `favicon` 对象的数组

一个 `favicon` 对象具有以下成员：

* `id`（正整数）
* `data`（base64 编码的图像数据；前缀为图像类型）

一个 `data` 值的示例：

`image/gif;base64,R0lGODlhAQABAIAAAObm5gAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==`

`favicon` 对象的 `data` 成员可以与 `data:` 协议一起使用，以在 CSS 或 HTML 中嵌入图像。一个 PHP/HTML 示例：

`echo '<img src="data:'.$favicon['data'].'">';`

## 项目

`http://yourdomain.com/fever/?api&items`

带有 `items` 参数的请求将返回两个附加成员：

* `items` 包含一组项目对象的数组
* `total_items` 包含数据库中存储的项目总数（在 API 版本 2 中添加）

一个 `item` 对象具有以下成员：

* `id`（正整数）
* `feed_id`（正整数）
* `title`（utf-8 字符串）
* `author`（utf-8 字符串）
* `html`（utf-8 字符串）
* `url`（utf-8 字符串）
* `is_saved`（布尔整数）
* `is_read`（布尔整数）
* `created_on_time`（Unix 时间戳/整数）

大多数服务器分配给 PHP 的内存不足以一次性倾倒所有项目。三个可选参数控制确定响应中包含的项目。

使用 `since_id` 参数和本地缓存项目的最高 id 请求 50 个额外的项目。重复直到响应中的项目数组为空。

使用 `max_id` 参数和本地缓存项目的最低 id（或最初为 `0`）请求 50 个之前的项目。重复直到项目数组为空。（在 API 版本 2 中添加）

使用 `with_ids` 参数和项目 id 的逗号分隔列表请求（最多 50 个）特定项目。（在 API 版本 2 中添加）

## 热门链接

`http://yourdomain.com/fever/?api&links`

包含 `links` 参数的请求将返回一个额外的成员：

* `links` 包含一个 `link` 对象数组

一个 `link` 对象具有以下成员：

* `id`（正整数）
* `feed_id`（正整数）仅在 `is_item` 等于 1 时使用
* `item_id`（正整数）仅在 `is_item` 等于 1 时使用
* `temperature`（正浮点数）
* `is_item`（布尔整数）
* `is_local`（布尔整数）用于确定是否应显示源 feed 和 favicon
* `is_saved`（布尔整数）仅在 `is_item` 等于 1 时使用
* `title`（utf-8 字符串）
* `url`（utf-8 字符串）
* `item_ids`（字符串/逗号分隔的正整数列表）

请求热门链接时，您可以通过指定每个链接的天数长度以及用来获取额外热门链接的页面来控制范围和偏移量。仅包含 `links` 参数的请求等同于：

`http://yourdomain.com/fever/?api&links&offset=0&range=7&page=1`

或者是从现在开始（`offset=0`），上一个星期（`range=7`）的第一页（`page=1`）热门链接。

# 链接注意事项

Fever 实时计算热门链接的温度。API 假设您拥有最新的本地缓存项、feeds 和 favicons，以此来构建有意义的热视图。由于它们是短暂的，热门链接不应以与项、feeds、组和 favicons 相同的关系方式缓存。

由于 Fever 保存的是项而不是单个链接，所以您只能在 `is_item` 等于 `1` 时“保存”热门链接。

`unread_item_ids` 和 `saved_item_ids` 参数可用于将您的本地缓存与远程 Fever 安装同步。

`http://yourdomain.com/fever/?api&unread_item_ids`

包含 `unread_item_ids` 参数的请求将返回一个额外的成员：

* `unread_item_ids`（字符串/逗号分隔的正整数列表）

`http://yourdomain.com/fever/?api&saved_item_ids`

包含 `saved_item_ids` 参数的请求将返回一个额外的成员：

* `saved_item_ids`（字符串/逗号分隔的正整数列表）

在标记一个项为已读、未读、已保存或未保存，以及在标记一个 feed 或组为已读时，将返回适当的一个成员。

由于组和 feeds 的数量相对于项来说较少，它们应通过将本地缓存的 feed 或组 id 数组与通过各自的 API 请求返回的 feed 或组 id 数组进行比较来同步。

# 编写

API 的公共测试版不提供添加、编辑或删除 feeds 或组的方式，但您可以标记项、feeds 和组为已读，并保存或取消保存项。您还可以将最近已读的项标为未读。在向 Fever API 写入时，您需要将参数添加到提交到 API 端点 URL 的 POST 数据中。

添加 `unread_recently_read=1` 到您的 POST 数据将会将最近已读的项标记为未读。

您可以通过向您的 POST 数据中添加以下三个参数来更新一个单独的项：

* `mark=item`
* `as=?` 其中 `?` 替换为 `read`、`saved` 或 `unsaved`
* `id=?` 其中 `?` 替换为要修改的项的 `id`

标记一个 feed 或组为已读类似，但需要一个额外的参数来防止标记新的、未收到的项为已读：

* `mark=?` 其中 `?` 替换为 `feed` 或 `group`
* `as=read`
* `id=?` 其中 `?` 替换为要修改的 feed 或组的 `id`
* `before=?` 其中 `?` 替换为本地客户端最近一次 `items` API 请求的 Unix 时间戳

您可以通过向您的 POST 数据中添加以下四个参数来将“Kindling”超级组（以及“Sparks”超级组）标记为已读：

* `mark=group`
* `as=read`
* `id=0`
* `before=?` 其中 `?` 替换为本地客户端最后一次 `items` API 请求的 Unix 时间戳

类似地，您可以通过向您的 POST 数据中添加以下四个参数来仅将“Sparks”超级组标记为已读：

* `mark=group`
* `as=read`
* `id=-1`
* `before=?` 其中 `?` 替换为本地客户端最后一次 `items` API 请求的 Unix 时间戳

# 非官方/未记录的 API

这是代表将从 iPad 上的 Mr.Reader App 使用的一些事物的扩展，它们未作为正常 API 文档记录，但因为 Fever API 端点与网页请求相同而被允许。

## 登录

`http://yourdomain.com/fever/?action=login&username=[username]&password=[password]`

包含 `action=login` 参数的请求将返回一个名为 `fever_auth` 的 cookie。这必须与 API 密钥相等。这是通常从 Fever 网页的登录对话框创建的调用。

* `username` - 您登录的用户名
* `password` - 您为 api 设置的密码

作为返回，将设置一个名为 `fever_auth` 的 cookie，其中包含 API 密钥。

幕峰网

Fever API 中文文档-机翻

添加新评论

轻语

热门文章

最新文章

最近回复

标签