tiptap 文档管理 API

协作管理 API 提供了一套 RESTful 端点，用于管理文档。这个 API 支持创建、列出、检索、更新和删除文档，以及高效的内容管理的文档复制功能。

请参阅 Postman 集合，进行实际操作体验，探索 REST API 的功能。

访问管理 API

REST API 直接从您的协作应用中暴露出来，可通过自定义 URL 访问：

https://YOUR_APP_ID.collab.tiptap.cloud/

使用应用设置中的 API 密钥进行身份验证。密钥应作为 Authorization 头发送。

如果文档标识符包含斜杠（ / ），请确保用百分比编码，例如使用 encodeURIComponent 。

文档操作

创建文档

POST /api/documents/:identifier

此请求接受一个二进制的 Yjs 更新消息（您需要先使用 Y.encodeStateAsUpdate 对本地的 Yjs 文档进行编码）。这可用于在用户连接到 Tiptap Collab 服务器之前初始化文档。

如果创建成功，此端点将返回 HTTP 状态码 204，如果文档已存在，则返回 409。若要覆盖现有文档，请先删除它。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'

列出文档

GET /api/documents?take=100&skip=0

此调用返回服务器存储中所有文档的列表。默认情况下，我们会返回前 100 个，可以通过 take 或 skip 参数调整数量。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

获取文档

GET /api/documents/:identifier?format=:format&fragment=:fragment

此请求导出指定文档及其所有片段的 JSON 格式。我们导出的是内存中的当前版本或数据库中读取的版本。如果文档在您的服务器上是打开的，我们将返回内存中的版本。

format 支持 yjs 或 json 。默认：json

如果您选择 yjs 格式，将得到使用 Y.encodeStateAsUpdate 创建的二进制 Yjs 更新消息。

fragment 可以是数组（ fragment=a&fragment=b ）或单个片段，您想导出的片段。默认情况下，我们将导出所有片段。请注意，这仅当使用 json 格式时才有效，否则始终会获取整个 Yjs 文档。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

注意： 使用 axios 时，请求选项中需要指定 responseType: arraybuffer 。

import * as Y from "yjs";

const ydoc = new Y.Doc();

const axiosResult = await axios.get(
  "https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc?format=yjs",
  {
    headers: {
      Authorization: "YOUR_SECRET_FROM_SETTINGS_AREA",
    },
    responseType: "arraybuffer",
  }
);

Y.applyUpdate(ydoc, axiosResult.data);

使用 node-fetch 时，需要使用 .arrayBuffer() 方法并将其转换为 Buffer：

import * as Y from "yjs";

const ydoc = new Y.Doc();

const fetchResult = await fetch(
  "https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc?format=yjs",
  {
    headers: {
      Authorization: "YOUR_SECRET_FROM_SETTINGS_AREA",
    },
  }
);

Y.applyUpdate(ydoc, Buffer.from(await docUpdateAsBinaryResponse.arrayBuffer()));

更新文档

PATCH /api/documents/:identifier

此调用接受一个 Yjs 更新消息，并将其应用于服务器上的现有文档。如果更新成功，端点将返回 HTTP 状态码 204 ，如果文档不存在则返回 404 ，如果数据无效或更新无法应用，则返回 422 。

curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'

删除文档

DELETE /api/documents/:identifier

此端点在关闭与文档的所有连接后从服务器删除文档。如果删除成功，返回 HTTP 状态码 204，如果文档未找到，则返回 404。

如果端点返回 204，但文档仍然存在，请确保没有用户从提供商重新创建该文档。我们在删除文档前关闭所有连接，但您的错误处理可能重新创建了提供商，从而再次创建文档。

curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

复制文档

要复制文档，只需使用 GET 端点，然后使用 POST 端点再次创建它。以下是使用 TypeScript 的示例：

const docUpdateAsBinaryResponse = await axios.get(
  "https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc?format=yjs",
  {
    headers: {
      Authorization: "YOUR_SECRET_FROM_SETTINGS_AREA",
    },
    responseType: "arraybuffer",
  }
);

await axios.post(
  "https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/somedoc-duplicated",
  docUpdateAsBinaryResponse.data,
  {
    headers: {
      Authorization: "YOUR_SECRET_FROM_SETTINGS_AREA",
    },
  }
);