fatcat的Rust API

Fatcat 是一个可扩展、版本化的面向 API 的书目实体和文件元数据目录。这些 API 参考文档以及客户端软件库是从 OpenAPI 2.0（“Swagger”）定义文件自动生成的。## 简介 API 的高级介绍以及 fatcat 数据模型的描述可以在"Fatcat 指南"中找到。指南还包括一个食谱部分，展示了如何创建实体作为编辑组的一部分，或者安全地合并重复实体等端到端任务。### 预期和最佳实践 fatcat 的测试/预发布 QA API 实例可在https://api.qa.fatcat.wiki/v0找到。支撑此实例的数据库与生产界面分开，并定期从完整生产数据库的快照中重建，这意味着 QA 服务器的编辑将不会持久化，并且像变更日志索引单调增加这样的语义可能会被破坏。开发者应在针对生产环境运行之前，在 QA 实例上测试其脚本和工具。Fatcat 作为一项免费（无成本）且自由（保留自由）的服务提供给公众，资金和资源有限。我们欢迎新的和未预料到的用途和贡献，但可能需要施加限制（如速率限制）以保持服务对其他用户的功能性，在极端情况下，如果必要，保留阻止账户和 IP 范围以保持服务运行的选择。互联网档案馆拥有并运营自己的服务器设备和数据中心，其运营优化以低成本为主，而不是高可用性。用户和合作伙伴应预期 fatcat API 每月会有数小时的停机时间。定期元数据导出可用于批量处理，并且数据库快照可用于创建用于更密集和可靠查询的服务本地镜像。### 其他细节 允许 API 服务进行跨源请求，以使第三方能够构建浏览器应用程序。元数据搜索服务可在https://search.fatcat.wiki（以及https://search.qa.fatcat.wiki）找到。API 当前是原始的 elasticsearch API，仅允许 GET（读取）请求。这项公共服务是实验性的，未来可能会被移除或限制。## 认证 API 允许无认证的只读“GET” HTTP 请求。提出更改元数据或其他修改请求（“PUT”、“POST”、“DELETE”）都需要认证，某些操作需要额外的账户权限。最终用户账户创建和登录通过网页界面进行。从登录编辑器个人资料页面，您可以生成 API 令牌。令牌是“马卡龙”，类似于 JWT 令牌，并用于所有 API 认证。网页界面包括在浏览器 cookie 中的马卡龙并将其传递到 API 以进行编辑器操作的认证。

概述

此客户端/服务器是由 [swagger-codegen]（《https://github.com/swagger-api/swagger-codegen》）项目生成的。通过使用来自远程服务器的 OpenAPI-Spec，您可以轻松生成服务器存根。

要了解如何将其作为自己的，请看这里

README

• API 版本：0.3.1
• 构建日期：2019-09-19T00:21:33.977Z 更多信息，请访问 https://fatcat.wiki

此自动生成的项目定义了一个名为 fatcat 的 API 套件，其中包含

• 一个 Api 特性，用于定义 Rust 中的 API。
• 代表底层数据模型的数据类型。
• 一个 Client 类型，它实现 Api 并为每个操作发出 HTTP 请求。
• 一个路由器，它接受 HTTP 请求并调用每个操作的适当 Api 方法。

它还包含一个示例服务器和客户端，它们使用了 fatcat。

• 示例服务器使用 fatcat 路由器启动一个 Web 服务器，并提供了 Api 的简单实现，该实现对每个操作都返回失败。
• 示例客户端提供了一个 CLI，允许您通过在命令行中传递适当的参数来调用 fatcat 客户端的任何单个操作。

您可以将示例服务器和客户端作为您自己的代码的基础。有关实现服务器的更多信息，请参阅下文。

示例

运行示例

cargo run --example <example-name>

要将参数传递给示例，请将它们放在 -- 之后，例如

cargo run --example client -- --help

运行服务器

要运行服务器，请按照以下简单步骤操作

cargo run --example server

运行客户端

要运行客户端，请按照以下简单步骤之一操作

cargo run --example client AuthCheck
cargo run --example client AuthOidc
cargo run --example client CreateAuthToken
cargo run --example client GetChangelog
cargo run --example client GetChangelogEntry
cargo run --example client CreateContainer
cargo run --example client CreateContainerAutoBatch
cargo run --example client DeleteContainer
cargo run --example client DeleteContainerEdit
cargo run --example client GetContainer
cargo run --example client GetContainerEdit
cargo run --example client GetContainerHistory
cargo run --example client GetContainerRedirects
cargo run --example client GetContainerRevision
cargo run --example client LookupContainer
cargo run --example client UpdateContainer
cargo run --example client CreateCreator
cargo run --example client CreateCreatorAutoBatch
cargo run --example client DeleteCreator
cargo run --example client DeleteCreatorEdit
cargo run --example client GetCreator
cargo run --example client GetCreatorEdit
cargo run --example client GetCreatorHistory
cargo run --example client GetCreatorRedirects
cargo run --example client GetCreatorReleases
cargo run --example client GetCreatorRevision
cargo run --example client LookupCreator
cargo run --example client UpdateCreator
cargo run --example client AcceptEditgroup
cargo run --example client CreateEditgroup
cargo run --example client CreateEditgroupAnnotation
cargo run --example client GetEditgroup
cargo run --example client GetEditgroupAnnotations
cargo run --example client GetEditgroupsReviewable
cargo run --example client UpdateEditgroup
cargo run --example client GetEditor
cargo run --example client GetEditorAnnotations
cargo run --example client GetEditorEditgroups
cargo run --example client UpdateEditor
cargo run --example client CreateFile
cargo run --example client CreateFileAutoBatch
cargo run --example client DeleteFile
cargo run --example client DeleteFileEdit
cargo run --example client GetFile
cargo run --example client GetFileEdit
cargo run --example client GetFileHistory
cargo run --example client GetFileRedirects
cargo run --example client GetFileRevision
cargo run --example client LookupFile
cargo run --example client UpdateFile
cargo run --example client CreateFileset
cargo run --example client CreateFilesetAutoBatch
cargo run --example client DeleteFileset
cargo run --example client DeleteFilesetEdit
cargo run --example client GetFileset
cargo run --example client GetFilesetEdit
cargo run --example client GetFilesetHistory
cargo run --example client GetFilesetRedirects
cargo run --example client GetFilesetRevision
cargo run --example client UpdateFileset
cargo run --example client CreateRelease
cargo run --example client CreateReleaseAutoBatch
cargo run --example client DeleteRelease
cargo run --example client DeleteReleaseEdit
cargo run --example client GetRelease
cargo run --example client GetReleaseEdit
cargo run --example client GetReleaseFiles
cargo run --example client GetReleaseFilesets
cargo run --example client GetReleaseHistory
cargo run --example client GetReleaseRedirects
cargo run --example client GetReleaseRevision
cargo run --example client GetReleaseWebcaptures
cargo run --example client LookupRelease
cargo run --example client UpdateRelease
cargo run --example client CreateWebcapture
cargo run --example client CreateWebcaptureAutoBatch
cargo run --example client DeleteWebcapture
cargo run --example client DeleteWebcaptureEdit
cargo run --example client GetWebcapture
cargo run --example client GetWebcaptureEdit
cargo run --example client GetWebcaptureHistory
cargo run --example client GetWebcaptureRedirects
cargo run --example client GetWebcaptureRevision
cargo run --example client UpdateWebcapture
cargo run --example client CreateWork
cargo run --example client CreateWorkAutoBatch
cargo run --example client DeleteWork
cargo run --example client DeleteWorkEdit
cargo run --example client GetWork
cargo run --example client GetWorkEdit
cargo run --example client GetWorkHistory
cargo run --example client GetWorkRedirects
cargo run --example client GetWorkReleases
cargo run --example client GetWorkRevision
cargo run --example client UpdateWork

HTTPS

可以通过传递标志 --https 在 HTTPS 模式下运行示例，例如

cargo run --example server -- --https

这将从示例目录中使用密钥/证书。请注意，服务器链已用 CN=localhost 签名。

编写服务器

服务器示例旨在成为实现您自己的服务器的基础。只需按照以下步骤操作。

• 设置一个新的 Rust 项目，例如，使用 cargo init --bin。
• 在根目录的 Cargo.toml 中的 [workspace] 下将 fatcat 插入到 members 数组中，例如 members = [ "fatcat" ]。
• 在根目录的 Cargo.toml 中的 [dependencies] 下添加 fatcat = {version = "0.3.1", path = "fatcat"}。
• 将 fatcat/Cargo.toml 中的 [dependencies] 和 [dev-dependencies] 复制到根 Cargo.toml 的 [dependencies] 部分。
  • 复制所有 [dev-dependencies]，但只复制示例服务器所需的 [dependencies]。这些应该通过注释清楚地指示。
  • 如果存在，请从这些行中删除 "optional = true"。

每个自动生成的 API 都将包含一个实现占位符和主入口点，第一次应该将其复制到您的项目中

cp fatcat/examples/server.rs src/main.rs
cp fatcat/examples/server_lib/mod.rs src/lib.rs
cp fatcat/examples/server_lib/server.rs src/server.rs

现在

• 从 src/main.rs 中删除 mod server_lib; 这一行，取消注释并填写 extern crate 这一行，用此服务器crate的名称替换。
• 将 "由服务库需要的" 导入块从 src/main.rs 移动到 src/lib.rs 并取消注释。
• 将 let server = server::Server {}; 这行代码改为 let server = SERVICE_NAME::server().unwrap(); 其中 SERVICE_NAME 是服务器crate的名称。
• 运行 cargo build 来检查它是否可以构建。
• 运行 cargo fmt 重新格式化代码。
• 在做出任何进一步更改之前提交结果（以免格式更改与您的更新混淆）。