- 知识库
- 文档
【免费下载链接】public-apis
A collaborative list of public APIs for developers
这是一篇面向开发者的实操指南，围绕 public-apis 开源仓库的 CONTRIBUTING.md 展开：你将掌握本仓库对公共 API 条目的接受标准、表格格式规范、Auth与CORS字段的取值约束、Pull Request 提交流程，以及这些规范如何被仓库自动构建脚本（/db目录生成）程序化消费。读完本文，你能够独立完成一个格式合规、能够通过自动化审查并最终合入main分支的 API 条目提交。
public-apis 是一个"协作式公共 API 清单"，它以 README.md 中的 52 个分类表格为唯一内容源，所有 API 条目都写在 Markdown 表格里。这意味着：对公共 API 的增删改，不是直接编辑数据文件，而是编辑 README 中的表格行，随后由仓库脚本自动同步生成结构化数据。理解这一"编辑 → 解析 → 生成"链路，是正确提交的前提。
核心原则：/db目录自动生成，勿手动修改
仓库目录结构中存在db/categories.json与db/resources.json两个数据文件，但贡献者必须明确一条铁律：
/db目录是自动生成的，请不要编辑它。任何与公共 API 相关的变更都应发生在README.md文件上。
这一点在 CONTRIBUTING.md 开头即被强调。从源码看，该流程由 scripts/db/update-db.js 实现：脚本读取README.md，使用remark-parse与unified将 Markdown 解析为 AST，再依次经过separateTables、groupRowContent、formatResources、formatCategories等工具函数，最终写入db/resources.json与db/categories.json。其中formatResources会把表格行中的Description | Auth | CORS拆分映射为API、Description、Auth、Cors、Link、Category六个字段——这意味着你在表格里怎么写，数据文件里就怎么长，格式不合规会直接污染下游数据。
配套的公开数据结构与读取示例见 API.md，它给出使用Octokit从仓库/db目录拉取categories.json（含count与entries）和resources.json（含API、Auth、Category、Cors、Description、Link）的完整代码。换句话说，README 表格是"人读"的界面，/dbJSON 是"机器读"的产物，二者必须保持一一对应。
接受标准：什么样的 API 才有资格进入清单
提交之前，请先对照以下 8 条硬性标准自查，缺一不可：
- 任何用例均可（Any use case）：产品可以服务任意受众与主题，关键不在于领域，而在于它确实对外暴露了可连接的 API。
- 免费或付费均可（Free or paid）：这里的 "public" 指"任何人都能注册并调用"，不等于免费。付费（paid）与 freemium 模式的 API 同样欢迎。
- 自助服务（Self-serve）：不允许候补名单（waitlists）、封闭注册的 beta、"即将上线"（coming soon）产品、合作伙伴审批流程或"联系销售"（contact sales）门槛。一个陌生人必须能仅凭文档就独立完成从阅读到成功调用的全过程。
- 可公开访问且有文档（Publicly reachable and documented）：API 必须在当前时刻可公开访问，并具备完整文档；若无法从文档中确定其
Auth与CORS行为，则不符合资格。 - 仅限主产品（Main product only）：提交对象必须是独立产品本身；大型产品的内部工具或子功能不被接受（API 本身不必是产品的主营业务）。
- 必须使用自定义域名（Custom domain required）：托管在共享子域名（如
vercel.app、netlify.app、herokuapp.com、github.io、pages.dev等）上的 API 一律不接受。 - 干净的 URL（Clean URLs）：URL 不得包含查询参数（
?之后的部分），应链接到普通页面。 - 质量门槛（Quality bar）：低质量、低投入的项目不被接受。
此外，仅提供应用（apps）、库（libraries）、CLI、SDK 或网站、但没有可连接 API 的工具不属于本清单。文档进一步说明：若你的产品是"开发者用来构建软件的工具"，它更契合dev-resources类项目；若它同时暴露公共 API，则可以同时出现在两个清单中——两个目录有意存在重叠，一个出现在其中并不构成另一个的重复。
条目格式规范：四列表格与示例
标准表格结构
清单中每个分类是一个四列 Markdown 表格，列头依次为：
| API | Description | Auth | CORS |
|---|---|---|---|
| API 名称（链接到 API 主页） | API 描述 | 是否需要认证 * | 是否支持 CORS * |
文档给出的最小示例条目为：
| [Cataas](https://cataas.com) | Cat as a service (cats pictures and gifs) | No | No |URL 与链接规范
- URL 必须以
https://开头，纯http://的 URL 不被接受。 - 链接应指向 API 的主页——即你会优先发给别人的那个页面。当产品有自己的主页时，避免深链到文档页、具体端点或子域名。
- 链接页面的截屏会成为该条目在
publicapis.dev网站上的展示卡片，访问者可以由此进入文档。
Auth 字段：只接受 5 种取值
当前Auth字段唯一接受的输入如下：
OAuth— API 支持 OAuth 认证；apiKey— API 使用私有密钥字符串/令牌进行认证（尽量使用正确的参数名）；X-Mashape-Key— 可能需要发送的请求头名称（指旧 Mashape 市场遗留的认证头约定）；No— API 运行无需认证；User-Agent— 随请求发送的请求头名称（即仅需在请求中携带合法的 User-Agent 即可调用）。
CORS 字段：只接受 3 种取值
Yes— API 支持 CORS；No— API 不支持 CORS；Unknown— 是否支持 CORS 未知。
需要特别理解的是 CORS 的判定含义：没有正确配置 CORS 的 API 将只能在服务端使用（浏览器端的跨域请求会被拦截）。因此，如果文档无法明确说明 CORS 行为，该条目就可能在审查中被退回。
从源码看表格如何被程序化消费
了解规范背后的解析逻辑，能帮助你写出真正合格的条目。在 scripts/db/update-db.js 中，README 被解析后依次经过如下工具链：
separate-tables.js：跳过 Index 列表之后，每遇到一个三级标题（如### AI）就把紧随其后的表格识别为一个分类，得到{ name, rows }；group-row-content.js：跳过表头行，把每行中的链接解析为{ link, name }，并拼接同一行后续单元格文本作为description；format-resources.js：对每行的description按|再次切分并trim，得到description、auth、cors三个值，映射输出API / Description / Auth / Cors / Link / Category字段；format-categories.js：对分类名做 slug 化处理——小写化、&替换为and、非字母数字字符替换为-（例如Art & Design→art-and-design，这可以在 db/categories.json 中得到印证）；format-json.js与write-to-file.js：组装出{ "count": n, "entries": [...] }结构的 JSON 并写入db/目录。
从format-resources.js的实现可以推断两个关键事实：一是Auth字段中No会被规范化处理为空字符串（auth?.toLowerCase() === 'no' ? '' : auth），即"无需认证"在数据结构中以空值表达；二是Cors字段会统一转为小写。因此，表格中拼写错误的Auth/CORS取值会原样进入数据文件，保持与文档允许值一致是唯一稳妥做法。
Pull Request 提交规范
完成条目修改并创建分支后，提交 PR 时须遵守以下硬性规则：
- 不提交已列 API 的更新/新版本：已列出的 API 只保留当前版本，旧版本会随时间弃用。
- 保持分类内字母序：继续遵循每个分类现有的字母排序。
- 表格单元格两侧各留一个空格：保证 Markdown 表格对齐与解析稳定。
- 分类归属以服务性质为准：若一个 API 可归入多个分类，放入与其服务最契合的一类（文档示例：Instagram API 归入
Social而非Photography，因为其本质是社交网络）。 - 一个 PR 只添加一个链接。
- PR 标题格式：必须为
Add Api-name API，例如Add Blockchain API。 - 提交信息要简短且具描述性：例如 ✅
Add Blockchain API to Cryptocurrency，而非 ❌Update Readme.md。 - 提交前检索：先搜索既有 Pull Requests 与 Issues，避免重复提交。
- 名称不要带顶级域名（TLD）：❌
Gmail.com，✅Gmail。 - 名称不要以
API结尾：❌Gmail API，✅Gmail。 - 确保 API 有完整文档。
- 链接主页而非深链（见上文 URL 规范）。
- 描述控制在 160 字符以内，以保证适配条目卡片展示。
- 合并所有提交（squash）：提交 PR 前把所有 commit 压缩为一个；若审查后要求修改，补充的新提交也要一并 squash。
- 目标分支：PR 必须指向
public-apis仓库的main分支。
Pull Request 实用技巧（Pro Tips）
- 先 Fork 仓库并本地 clone；将本地仓库与原始
upstream仓库关联为 remote，经常从upstream拉取更新，这样提交 PR 时更不容易产生合并冲突。 - 为你的改动创建独立分支。
- 按照上文约定风格贡献，便于协作者合并与后续维护。
PR 提交后的审查流程
PR 打开后，围绕你的改动会展开讨论：
- 先由自动化审查者审核：仓库可能通过 bot 账号对 PR 进行评论、批准或关闭；审查内容包括 URL 是否可访问。
- 再由维护者做最终合并决策：讨论期间若被要求修改，只需在分支上追加提交并推送，它们会自动进入现有 PR（但别忘记 squash）。
- 无 CI 构建需要等待：自动化审查在 PR 打开时检查条目（含 URL 可达性），已合入的每条 API 会被持续链接检查（link-checked）。请确保提交的 URL 是活的且正确——失效或跳转的链接是提交被退回的最常见原因。
一份可直接执行的提交检查清单
把以上规范压缩成提交前的最后检查步骤：
- 在 README.md 的对应分类表格中，以
https://主页链接新增一行，四列均合规； Auth取值 ∈ {OAuth,apiKey,X-Mashape-Key,No,User-Agent}，CORS取值 ∈ {Yes,No,Unknown}；- 描述 ≤ 160 字符，名称不含 TLD、不以
API结尾； - URL 不含查询参数、为自定义域名、非深链；
- 保持分类内字母序，表格单元格两侧留空格；
- 单条链接一个 PR，标题为
Add Api-name API，目标分支为main； - squash 所有 commit，提交前检查 URL 可访问且无重定向。
遵循以上规范，你的条目将顺利通过自动化审查与维护者评估，成为这份 52 个分类、覆盖 AI、区块链、金融、天气等领域的公共 API 清单的一员。
- 知识库
- 文档
【免费下载链接】public-apis
A collaborative list of public APIs for developers
相关推荐
public-apis 贡献指南实战：API 条目格式规范与 Pull Request 提交流程全解析
public apis 贡献指南实战：API 条目格式规范与 Pull Request 提交流程全解析 本指南以 CONTRIBUTING.md https:/
文档awesome-nlp 贡献指南：为 NLP 精选资源清单提交高质量 Pull Request 的完整规范
awesome nlp 贡献指南：为 NLP 精选资源清单提交高质量 Pull Request 的完整规范 导读 本文以仓库根目录的 contributing.
NLP文档从零到一：Public APIs项目完整贡献指南 - 轻松提交你的第一个API 🚀
从零到一：Public APIs项目完整贡献指南 轻松提交你的第一个API 🚀 Public APIs是一个由开发者社区共同维护的公共API资源库，汇集了数千
知识库文档
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
