Readplace 推出自助注册公开 API,供第三方集成保存和阅读文章
来源标题:Show HN: Readplace read-it-later self-registration Public API
Readplace 发布公开 API,开发者可自助注册应用并获取令牌,代表用户保存链接、列出并阅读文章、管理 readlists。该 API 采用 Siren 超媒体格式,文章也可以 Markdown 文档形式返回。集成需经读者授权后才能操作其账户。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
有更新版本的文章阅读器,要刷新吗? 有些网站不允许 Readplace 保存完整文章。请使用浏览器扩展或 iPhone、Android 应用来保存完整页面。 Readplace 书库 安装 导入链接 功能 账户 登录 基于 Readplace API 构建 Readplace API 允许集成方在读者授权后保存链接、列出并阅读文章,并将文章归档到阅读列表中。 你可以构建什么 注册你的应用并获取 token 注册 授权 获取 token 断开连接 从一个 URL 开始 读取一个集合 读取一篇文章 保存链接和页面 标记为已读或未读 管理阅读列表 缓存 错误 限制 API 之外的功能 演练:清空一个阅读列表 你可以构建什么 该 API 使用 Siren(application/vnd.siren+json),一种超媒体格式:每个响应都携带你接下来可以执行的链接和操作。文章也以 Markdown 文档(text/markdown)形式提供。 一个集成代表一位读者,该读者用其 Readplace 账户进行授权。创建一个账户来试用。 典型的集成是一个定时任务,用于清空一个阅读列表:它列出列表中的内容,将每篇文章作为 Markdown 读取,传递出去,然后将其从阅读列表中移除。文末的演练遵循这一流程。没有任何内容会主动推送给你,因此该任务采用轮询方式。 Readplace 自身就是 OAuth 2.0 授权服务器。其元数据位于 /.well-known/oauth-authorization-server,受保护资源元数据位于 /.well-known/oauth-protected-resource,指向前者。 通过 Dynamic Client Registration(RFC 7591)注册一次:向 /oauth/register 发送一个带 JSON 的 POST 请求。 POST /oauth/register HTTP/1.1 Host: readplace.com Content-Type: application/json {"redirect_uris": ["http://127.0.0.1:8765/callback"], "client_name": "Reading automator"} 授权 将读者的浏览器引导至 /oauth/authorize,并携带 PKCE challenge,使用 S256。Readplace 会在需要时要求读者登录并批准你的应用,然后携带 code 和 state 重定向到你的 redirect URI。 redirect_uri 必须与注册的 URI 完全匹配,包括端口,因此请注册你的应用实际监听的精确回环端口。 省略 scope。每个 token 都获得对读者账户的完整访问权限,携带 scope 的刷新请求会以 400 invalid_scope 被拒绝。受保护资源元数据在 scopes_supported 中将这一单一访问级别列为 account。 resource 是可选的,因为 Readplace 既是授权服务器又是 API,所以它签发的每个 token 已经就是针对此 API 的。 GET /oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&state=STATE HTTP/1.1 Host: readplace.com 获取 token 使用你的 PKCE verifier 交换 code: 响应是包含 access_token、refresh_token、token_type 和 expires_in 的 JSON。 访问令牌是短期的。从每个 token 响应中读取 expires_in,当请求返回 401 和 invalid_token 时进行刷新。 刷新令牌有效期为 180 天并且会轮换:每次刷新都会返回一对新令牌,并使你发送的刷新令牌失效。在使用新令牌对之前先将其存储好。 POST /oauth/token HTTP/1.1 Host: readplace.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&code_verifier=CODE_VERIFIER POST /oauth/token HTTP/1.1 Host: readplace.com Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID 断开连接 /oauth/revoke 接受访问令牌或刷新令牌,撤销其中一个也会同时撤销另一个。读者也可以在其账户的 Connected apps 下断开你的应用。 Connected apps 会将你的应用列为 AI assistant,连接来源为你的第一个 redirect URI 的主机,或当该 URI 位于 127.0.0.1 或 [::1] 时列为你计算机上的应用。如果 client_name 匹配某个受支持的助手名称(不区分字母大小写),则你的应用会被列为该助手。 create-session 在每个集合上返回 204 并附带浏览器会话 cookie,供在自己的 web view 中打开 Readplace 阅读器的应用使用。大多数集成会跳过它。撤销 token 或读者断开你的应用并不会结束它创建的会话,因此当你的应用被断开时,请从你的 web view 中清除该 cookie。更改或重置密码则会结束会话。 create-browser-handoff 在每个集合上返回 200 并附带一个一次性、短期有效的 code。使用该 code 打开交接页面的浏览器会以该读者身份登录。大多数集成会跳过它。 POST /oauth/revoke HTTP/1.1 Host: readplace.com Content-Type: application/json {"token": "REFRESH_TOKEN"} 从一个 URL 开始 每个请求都携带读者的访问令牌和 Siren 媒体类型。从 / 开始。 GET / HTTP/1.1 Host: readplace.com Authorization: Bearer ACCESS_TOKEN Accept: application/vnd.siren+json HTTP/1.1 200 OK Content-Type: application/vnd.siren+json 读取一个集合 一个集合是某个阅读列表中某一标签页内的一页文章。其 entities 是文章,其 properties 链接到其余部分: 其他链接服务于 Readplace 自己的应用,因此忽略你不使用的那些。 Readplace 不接受的值会被丢弃,而不是被拒绝。search 始终列出 All,因此在具名阅读列表内,请改为跟随其标签页和页面的 href。 每个文章 entity 携带以下 properties: 携带 token 和 Markdown 媒体类型跟随文章的 read 链接,即可获取文章文档: 先检查状态,再检查 Content-Type,因为 401 和 404 响应也有 Markdown 正文。404 表示该文章不属于此读者。 文档以 YAML frontmatter 开头。值为缺失的键会被省略,绝不会为 null: 当 readplace_content_status 为 failed 或 not-an-article,或者为 ready 且 readplace_summary_status 为 ready、failed 或 skipped 时,文档即为最终状态。稍后再次获取不完整的文档。最终状态并非冻结不变:阅读状态、阅读列表成员关系以及重新爬取仍会改变它。 GET READ_HREF HTTP/1.1
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。