应用的 REST API 与 API 文档

Q: 为什么我点不了“发布文档”？

文档至少需要一个已上线的端点，并且不能有未保存的更改。在某个端点上勾选发布端点，点击保存并发布端点，再点击发布文档。

Q: 网站可以在浏览器中调用我的 API 吗？

可以，任何网站都能调用你的端点。在网页中请使用公开读取端点；需要密钥的调用请放在服务器上，这样密钥才不会泄露。

要点在“管理”标签页中，API 功能可以把应用的表变成其他软件能调用的 REST 端点，用来列出、获取、创建、更新或删除记录。你可以选择表、字段以及谁可以调用（读取可以对所有人开放，也可以只允许持有项目 API 密钥的调用方），然后勾选“发布端点”使其生效。想分享时，点击“发布文档”，即可为开发者提供一个 API 参考页面和一个 OpenAPI 文件。

有时其他软件需要用到你应用的数据：合作伙伴的网站要展示你的商品，某个电子表格要拉取新订单，还有移动应用、Zapier 或 n8n 这样的自动化工具。它们通过 API 和你的应用对话。API 是一组网址（端点），返回的是数据而不是页面。REST API 是最常见的一种。

MonstarX 无需写代码就能替你生成 API。你只需选择要共享的内容，几秒钟就能上线，还附带一个开发者可以阅读的参考页面。

在哪里找到它？

打开项目，点击顶部栏中的管理，再点击管理后台侧栏中的 API。你会看到项目 API：顶部是用于发布 API 文档的 API 参考栏；左侧是你的端点，每个都标有已上线或草稿；下方是 API 密钥。

Pantry Notes 的管理 → API：API 参考栏标为“已发布”，显示“已上线端点：1”；已上线的 GET /recipes 端点名为 List Recipes，显示名称、路径、集合和操作

如何创建端点？

在管理API 中，点击新建端点（或端点旁的 +）。
选择集合，也就是端点要操作的表，比如 Recipes。

选择操作：

操作	方法和地址	作用
列出	`GET /recipes`	分页返回记录。
获取	`GET /recipes/{id}`	按 ID 返回一条记录。
创建	`POST /recipes`	添加一条记录。
更新	`PATCH /recipes/{id}`	修改一条记录的部分字段。
删除	`DELETE /recipes/{id}`	删除一条记录。

填写名称、URL 路径，还可以选填描述。这些内容会显示在 API 文档中。
在开放的字段中，只勾选调用方可以查看或提交的字段。未勾选的字段保持私有。看起来敏感的字段，比如密码和令牌，始终会被排除。
在访问权限中，选择谁可以调用（见下文）。
勾选发布端点，然后点击保存并发布端点。已发布的端点状态为已上线：它会立即响应请求。如果不勾选，点击保存端点会把它保存为草稿。

在列表中，每个端点都标有已上线或草稿。编辑端点下方也会显示同样的状态，在你保存之前，后面还会跟着未保存的更改。取消勾选发布端点并保存，就能让端点下线而不删除它；删除则会将其彻底移除。

谁可以调用我的端点？

访问权限	谁可以调用	适用于
公开读取	任何知道地址的人。	仅限列出和获取
项目 API 密钥	只有发送了项目 API 密钥之一的调用方。	所有操作

会修改数据的端点始终需要密钥。

如何创建 API 密钥？

在管理API 中，点击 API 密钥。
输入一个能说明密钥用途的名称，比如“菜谱小组件服务器”，然后点击创建密钥。
立即复制密钥。它以 mxapi_ 开头，之后无法再次查看。请把它存放在安全的地方，比如密码管理器，或者另一个服务的密钥设置中。

项目 API 密钥：已输入密钥名称“食谱小组件服务器”，旁边是“创建密钥”按钮，并提示密钥可访问所有需要密钥的端点，每个密钥只显示一次

一个密钥可以访问项目中所有需要密钥的端点，所以请为每个服务单独创建密钥。点击吊销即可停用某个密钥，所有使用它的地方会立即失效。

调用方在 Authorization 请求头中发送密钥：Authorization: Bearer mxapi_…。

如何试用端点？

打开端点，点击测试。如果端点需要，填写记录 ID、Bearer 密钥或 JSON 请求体，然后点击发送请求。你会看到状态码（200 表示成功）、耗时和返回结果。对于需要密钥的端点，请从 API 密钥中复制一个密钥，粘贴到 Bearer 密钥。

测试请求会发往真实的线上端点，所以：

草稿还不能测试。 “测试”标签页会显示此端点仍是草稿；在那里点击保存并发布端点，发布后即可测试。
先保存更改。 如果有未保存的更改，“测试”标签页会请你先保存再测试，并提供保存端点按钮。

GET /recipes 的“测试”标签页：monstarx.com 上的完整地址、“发送请求”按钮，以及以 JSON 形式列出菜谱的 200 响应

测试创建、更新或删除端点会修改你的真实数据。

代码标签页提供一条可直接复制的 cURL 命令，以及 Postman、Insomnia 等 API 工具可以导入的 OpenAPI JSON 文件。

“代码”标签页：GET /recipes 的 cURL 命令和“复制”按钮，以及指向 OpenAPI JSON 文件的链接

如何发布和分享 API 文档？

API 文档是一个面向开发者的 API 参考页面：列出每个已上线的端点、它的字段、是否需要密钥，还有一个试一试输入框和 cURL 示例。发布端点并不会同时发布文档，何时分享由你决定。

至少发布一个端点，并保存所有更改。在此之前，管理API 顶部的 API 参考栏会显示未发布，并告诉你还缺什么。
点击发布文档。
这时栏中会显示已发布。点击复制文档链接即可分享地址，或点击 API 密钥下方的打开 API 文档查看页面。地址形如 https://monstarx.com/api-docs/<your project id>。

Pantry Notes 已发布的 API 参考：项目名称和描述、“端点：1”、项目 ID 和基础地址，以及标为“公开读取”的 GET /recipes，附开放的字段和一个已返回 JSON 菜谱数据的“试一试”框

页面开头显示项目名称和描述、列出的端点数量、项目 ID 和基础地址。任何拿到链接的人都能阅读，并且会告知搜索引擎不要将其编入索引。页面只显示已上线的端点，永远不会显示密钥。顶部的 OpenAPI JSON 链接指向同样内容的文件版本。

要撤下文档，点击取消发布文档：页面和 OpenAPI 文件会停止访问，而你的端点会继续响应请求。如果你让所有端点都下线，文档也会随之取消发布，准备好后再重新发布即可。

请求和响应是什么样的？

每个端点都位于 https://monstarx.com/api/rest/<your project id> 之下，后面接上它的路径。

curl 'https://monstarx.com/api/rest/<project id>/recipes?page=1&limit=25'

{
  "data": [
    { "id": "41a6…", "title": "Street tacos al pastor", "country_code": "MX" }
  ],
  "page": 1,
  "limit": 25,
  "hasMore": false
}

limit 是每页的记录数，范围为 1 到 100（不填时为 25）；page 的范围是 1 到 100。hasMore 表示是否还有下一页。

curl -X POST 'https://monstarx.com/api/rest/<project id>/recipes' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Lemon ricotta pancakes", "country_code": "IT"}'

响应（状态码 201）会在 data 中返回新记录及其 id。

curl -X PATCH 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Fluffy lemon ricotta pancakes"}'

curl -X DELETE 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY'

更新会返回修改后的记录；删除会返回 { "deleted": true }。

提交数据的规则：

一个 JSON 对象，带 Content-Type: application/json 请求头，最大 64 KB。
只能包含开放的字段，每个字段都是简单值：文本（最多 20,000 个字符）、数字、true/false 或 null。
ID 不能设置或修改，在“管理”中设为只读的字段也一样。

出错时，响应会包含一条 error 信息和一个状态码：400（请求不正确）、401（需要有效的项目 API 密钥）、403（“管理”中不允许访问该表或执行该操作）、404（端点或记录不存在）、409（冲突，比如重复）、413（响应会超过 1 MB，请减少开放的字段或使用更小的分页）。

常见问题

为什么我点不了“发布文档”？

文档至少需要一个已上线的端点，并且不能有未保存的更改。在某个端点上勾选发布端点，点击保存并发布端点，再点击发布文档。

API 要能用，必须先发布应用吗？

不用。API 直接读写项目的数据库，所以端点一发布就能用。它和预览、线上应用使用同一份数据，不需要构建，不用 AI，也不消耗额度。

网站可以在浏览器中调用我的 API 吗？

可以，任何网站都能调用你的端点。在网页中请使用公开读取端点；需要密钥的调用请放在服务器上，这样密钥才不会泄露。

我弄丢了一个 API 密钥，还能再看到吗？

不能，密钥只显示一次。请创建一个新密钥，把服务切换过去，然后吊销旧密钥。

为什么我无法发布某个端点？

对于创建、更新或删除，请先在“管理”中为该表开启对应的操作。如果应用的线上数据库运行在你自己的 Cloudflare 账户上，就无法从 MonstarX 发布端点，因为这里的数据库保存的是预览用的测试数据。

数据变化时能收到 webhook 吗？

“管理 → API”不提供，它只负责响应请求。你可以让 MonstarX 为应用添加 webhook，比如“有人下单时，把订单 POST 到这个地址”。