Zulip REST API 端点全景指南从消息收发到实时事件队列的完整 API 地图【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulipZulip 的 REST API 是其 Web 应用、桌面客户端、移动端、机器人bot与集成脚本共同的交互底座官方宣称只要你能在 Zulip 里做的事都能通过 REST API 完成。本文以 rest-endpoints.md 这份官方端点索引为骨架系统梳理 Zulip 当前公开的13 大分类、约 160 个 REST 端点并结合 zulip.yaml31,902 行 OpenAPI 定义166 个 operationId与zerver/views/下的真实视图实现深入讲解各端点群的用途、关键参数与底层机制。读完本文你将获得一张按功能域组织的完整 API 地图知道在什么场景该调用哪个端点、去哪个源文件验证行为以及如何按官方规范为 Zulip 新增一个 API 端点。这份索引文档的角色API 文档的导航骨架api_docs/include/rest-endpoints.md并不是一份普通的技术手册而是 Zulip API 文档体系的索引文件index它按功能域把全部端点分成若干分类每个条目是一个指向该端点独立文档页的链接。它的实际用途体现在两处rest.md 第 28 行通过 Markdown include 语法{!rest-endpoints.md!}将该索引嵌入《The Zulip REST API》总览页成为所有端点的统一入口sidebar_index.md 同样以{!rest-endpoints.md!}引入它驱动 API 文档侧边栏的渲染。也就是说你看到的所有端点列表、侧边栏目录都源于这一个文件。它的链接约定是链接 URL如/api/send-message必须与端点在 OpenAPI 定义中的operationId完全一致链接文本必须与 OpenAPI 的summary字段一致——这条规则在 docs/documentation/api.md 第 339-342 行有明确记载Add the endpoint to the index inapi_docs/include/rest-endpoints.md. The URL should match theoperationIdfor the endpoint, and the link text should match the title of the endpoint from the OpenAPIsummaryfield.因此这份文档与zerver/openapi/zulip.yaml是一一对应的索引负责导航OpenAPI 定义负责细节。单个端点页的详细内容Usage examples、Parameters、Response则由 api-doc-template.md 定义的模板自动生成本文末尾会专门拆解这个模板。Messages消息生命周期全链路消息是 Zulip 的核心实体这一分类也是端点最密集、被官方客户端使用最多的域。/messages端点在 zulip.yaml 中定义其 GET 视图实现在 message_fetch.py 的get_messages_backendPOST 实现在 message_send.py 的send_message_backendPATCH 实现在 message_edit.py 的update_message_backend。端点链接 operationId功能要点Send a message发送消息到频道或私聊支持typestream/private、to、topic、content等参数Upload a file上传文件生成附件返回uri供消息引用Edit a message修改消息内容行为受可编辑时间窗等组织策略约束Delete a message删除消息受组织权限与时间窗限制Get messages拉取消息的核心端点配合 narrow 过滤器使用Construct a narrow构造窄化过滤器按频道、话题、发送者、关键词等筛选消息Add / Remove an emoji reaction添加 / 移除表情回应Render a message服务端将 Markdown 渲染为 HTML便于预览Fetch a single message按 ID 获取单条消息及其渲染内容Check if messages match a narrow判断一组消息是否匹配某个 narrowGet a messages edit history获取消息编辑历史Update personal message flags / for narrow更新消息标记已读、星标、话题关注等后者针对窄化结果批量操作Mark all messages / channel / topic as read三种粒度的标记已读Get a messages read receipts获取消息阅读回执Get temporary URL for an uploaded file为附件生成带时效的临时访问 URLCheck thumbnail status检查缩略图生成状态Report a message向服务端上报消息用于滥用举报等Get messages 与 narrow拉取消息的正确姿势GET /api/v1/messages在 OpenAPI 中的description指出它是所有官方 Zulip 客户端Web、桌面、移动、终端以及大量机器人、备份脚本拉取消息的主要途径。其核心设计是以锚点anchor为中心的窗口拉取anchor整数消息 ID也支持特殊字符串值newest最新消息、oldest最旧消息、first_unread第一条未读消息若无则取最新、date配合anchor_date取该时间点起的第一条消息Zulip 12.0 / feature level 445 新增num_before/num_after分别指定锚点之前、之后各取多少条二者至少提供一个include_anchor是否包含锚点消息本身默认trueZulip 6.0 / feature level 155 起提供批量大小建议不超过 1000 条单请求硬上限 5000 条超出会报错——这是 zulip.yaml 中明示的官方建议。message_ids变体客户端显式指定要拉取的消息 ID 列表是 Zulip 10.0 / feature level 300 新增的少见用法。用户的消息历史默认不含订阅频道之前的历史消息且新建的机器人用户通常不订阅任何频道这两点很容易被 API 初学者忽视。Scheduled messages 与 Message reminders时间维度的消息控制端点功能要点Get / Create / Edit / Delete a scheduled message定时消息的增删改查。创建端点在 create-scheduled-message.md 有独立文档核心参数为scheduled_delivery_timestampUnix 时间戳配合消息本身的内容与目标参数Create a message reminder为自己创建一条消息提醒Get / Delete reminders查询 / 删除已创建的提醒定时消息适合延迟发送与提醒型工作流例如晚间撰写、次日早晨触达提醒则与消息内容解耦是面向个人的时间管理能力。这两组端点让 Zulip API 在消息发送之外具备了完整的时间调度语义。Drafts 与 Saved snippets草稿与复用片段端点功能要点Get / Create / Edit / Delete a draft草稿的增删改查草稿对象包含type、to、topic、content等字段供客户端实现自动保存草稿、跨设备同步Get / Create / Edit / Delete a saved snippet保存的消息片段可复用的消息模板的增删改查草稿端点组支撑了 Zulip Web 客户端写消息时自动保存草稿、重新打开时恢复的体验snippet 端点则进一步把常用消息内容如团队公告模板、例行周报格式沉淀为可复用资源。Navigation views组织内导航视图端点功能要点Get all navigation views获取组织内全部导航视图配置Add / Update / Remove a navigation view导航视图的增改删导航视图navigation view是 Zulip 为组织定制客户端左侧导航结构的能力属于偏组织级定制化的端点群。Channels频道全生命周期管理这一分类对应 Zulip 模型中的stream/channel新版文档统称 channel。GET/POST /users/me/subscriptions定义在 zulip.yaml/streams系列定义在第 24445 行。频道端点覆盖了订阅关系—频道元数据—话题—默认频道—频道文件夹五个层次端点功能要点Get subscribed channels获取当前用户已订阅的频道含Subscription对象数组Subscribe to a channel订阅一个或多个用户到频道频道不存在时自动创建可通过参数指定初始设置如invite_onlyUnsubscribe from a channel退订频道Get subscription status查询单频道订阅状态Get channel subscribers / Get a users subscribed channels按频道查订阅者 / 按用户查其订阅的频道Update a subscription setting / Bulk update单个 / 批量更新订阅偏好通知方式、置顶、静音等Get all channels / Get a channel by ID / Get channel ID频道列表、按 ID 查、按名称查 IDCreate / Update / Archive a channel频道的创建、更新、归档Get channels email address获取频道专属邮件地址用于邮件网关发信Get topics in a channel列出频道内话题及最新消息时间Topic muting / Update personal preferences for a topic话题静音 / 更新个人对话题的偏好Delete a topic删除整个话题连带其全部消息Add / Remove a default channel把频道设为 / 移出新用户默认订阅频道Create / Get / Reorder / Update a channel folder频道文件夹的创建、查询、排序、更新Subscribe 端点的权限演进源码级佐证POST /users/me/subscriptions的 OpenAPI 描述记录了一段很有意思的权限演进史zulip.yamlZulip 10.0feature level 362之前已归档频道中的订阅关系不可修改feature level 357 引入can_subscribe_group权限允许组成员自行订阅feature level 349 放宽了订阅私有频道必须先订阅该频道的限制只要用户属于can_add_subscribers_group即使本人未订阅也可把他人加入私有频道feature level 333 移除了stream_post_policy、is_announcement_only参数发帖权限统一由can_send_message_group控制feature level 208 起对不存在的/已停用的principals被操作对象错误码从 403UNAUTHORIZED_PRINCIPAL改为 400BAD_REQUEST。这提醒 API 使用者订阅端点不是简单的写库其行为深度绑定组织的权限体系Group 模型。GET /users/me/subscriptions的响应中Subscription对象包含color、is_muted、pin_to_top、desktop_notifications、audible_notifications、push_notifications、invite_only、is_archived、creator_id、subscribers订阅者 ID 列表等字段并且 Zulip 8.0 起响应中已移除email_address字段、Zulip 6.0 起移除role字段——字段的增删在 OpenAPI 里都有**Changes**标注是查询当前版本到底返回什么的最权威来源。Users用户、状态、用户组与个性化用户域是端点数量最多的分类之一约 40 个覆盖身份、状态、设置、用户组、机器人凭证五个子块端点功能要点Get a user / by email / Get own user / Get users用户信息的四种查询方式含include_custom_profile_fields等参数Create a user / Update a user / by email创建用户、按 ID 或邮箱更新用户Deactivate a user / own user / Reactivate停用他人 / 停用自己 / 重新激活Get a users status / Update your status / Update user status用户状态emoji 状态文案的查询与更新Update / Remove your profile data自定义档案字段profile data的增删Upload / Delete your profile picture头像上传与删除Set typing status / for message editing输入状态广播两种场景正在写消息 / 正在编辑消息Get a users presence / Get presence of all users / Update your presence在线状态presence的三端点配合客户端在线显示Get / Delete attachments当前用户的附件列表与删除Update settings更新个人设置通知偏好、显示偏好等参数极多Get / Create / Update / Deactivate a user group用户组的增删改查支持子组Update user group members / subgroups组成员增删、子组关系调整Get user group membership status / members / subgroups组成员关系查询Mute / Unmute a user静音 / 取消静音某个用户Get / Add / Remove alert words提醒词alert word管理Regenerate your API key / Get a bots API key / Regenerate a bots API key用户本人 / 机器人的 API key 管理与轮换其中Get users端点支持按include_custom_profile_fields附带自定义档案字段Update settings是个人设置的统一入口——Zulip 把大量用户级设置收敛到这一个端点通过数百个可选参数实现而组织级默认值则由 Server organizations 分类中的Update realm-level defaults of user settings统一管控二者形成个人覆盖 / 组织兜底的双层设置体系。Invitations邀请与可复用链接端点功能要点Get all invitations列出全部待处理邀请Send invitations发送邮箱邀请可带invite_expires_in_minutes等参数Create a reusable invitation link生成可重复使用的邀请链接适合社区型组织Resend / Revoke an email invitation重发 / 撤销邮箱邀请Revoke a reusable invitation link撤销可复用邀请链接这组端点对应 Zulip 组织邀请成员的管理工作流其中可复用邀请链接与一次性邀请在生命周期管理上做了明确区分。Server organizations组织级配置与治理这一分类是组织管理员视角的端点群约 29 个覆盖链接解析、自定义 emoji、档案字段、域名、数据导出、会话与会话体系等端点功能要点Get server settings获取服务器设置登录方式、功能开关等客户端据此渲染 UIGet / Add / Update / Remove / Reorder linkifiers链接解析器把模式匹配的 URL 转成富文本链接的增删改查与排序Add / Remove a code playground代码演练场把代码块链接到外部 IDE/沙箱的注册与移除Get all / Upload / Deactivate custom emoji自定义 emoji 的查询、上传、停用Get all / Reorder / Create / Update / Delete a custom profile field自定义档案字段的全生命周期管理Update realm-level defaults of user settings更新组织级用户设置默认值Get / Add / Update / Remove an allowed domain组织允许登录域名的管理Get all / Create a data export / Get export consent / Delete a data export数据导出工作流含用户同意状态查询Test welcome bot custom message测试欢迎机器人自定义消息Deactivate an organization停用整个组织其中自定义档案字段端点组与 Users 域的Update your profile data呼应组织定义字段 schema用户填充字段值是组织定制化数据模型的标准做法。数据导出相关端点则支撑了 Zulip 的GDPR 式数据可携带能力。Real-time events实时事件队列系统这是 Zulip API 中最具特色的部分也是其类 IRC 类 Slack实时体验的引擎。四个端点构成完整的注册—拉取—确认—销毁闭环端点功能要点Real time events API实时事件系统的总览文档Register an event queue注册事件队列并返回queue_id、last_event_id同时可拉取当前状态快照Get events from an event queue长轮询从队列取事件Delete an event queue释放队列资源register 与 events长轮询的正确打开方式POST /registerregister-queue定义于 zulip.yaml被官方称为强大的端点powerful endpoint它不仅注册事件队列还能一次性返回用户当前可见的数据状态消息、频道、用户、设置等。其关键行为返回queue_id与last_event_id供后续GET /events使用队列在空闲idle_queue_timeout_secs秒后会被垃圾回收该参数与响应字段为 Zulip 12.0 / feature level 481 新增此前是服务端固定超时服务端每分钟发送一次heartbeat心跳事件帮助客户端区分连接正常但无事件与连接断开若队列已被回收还去取事件服务端返回BAD_EVENT_QUEUE_ID错误客户端必须捕获该错误并重新执行整个注册流程——这正是 Web 客户端在笔记本休眠后恢复时自动刷新的底层触发机制原型阶段建议不带event_types注册先观察全部数据类型生产环境务必设置event_types与fetch_event_types过滤器——官方直言花几分钟做好过滤往往能省下客户端 90% 的带宽与资源消耗。GET /eventsget-events定义于 zulip.yaml负责长轮询queue_id已注册队列的 IDlast_event_id已确认收到的最高事件 ID事件 ID 递增但不保证连续dont_block设为true时非阻塞返回无事件立即返回空数组不设置时请求会阻塞直到有新事件或服务端发送心跳客户端应使用register响应中的event_queue_longpoll_timeout_seconds作为本端点的 HTTP 超时时间官方保证该值高于心跳超时——直接照此实现就不会因为心跳超时增加而提前断开。开发者若想深入了解队列系统的实现原理如何避免竞态、事件分发的内部结构可阅读 events-system.md该文档专门讲解 Zulip 事件系统的设计细节。Interactive bots、视频集成与移动推送Interactive bots交互式机器人存储——为机器人提供简单的键值存储端点功能要点Get / Update / Remove a bots stored data按bot_user_id读取、写入、删除机器人的键值数据Video call integrations视频通话集成——四个创建视频会议端点分别对接 BigBlueButton、Constructor Groups、Nextcloud Talk、Webex端点功能要点Create BigBlueButton / Constructor Groups / Nextcloud Talk / Webex video call按集成类型生成对应的视频会议会话Mobile push notifications移动推送——约 11 个端点覆盖设备注册与推送通道管理端点功能要点Register a logged-in device注册当前登录设备关联用户Remove a registered device注销设备Register E2EE push device / to bouncer端到端加密推送设备的注册后者面向 Zulip 推送代理 bouncerSend an E2EE test notification / Send a test notification向设备发送测试推送Add / Remove an APNs device tokenApple 推送通道APNs令牌管理Add / Remove an FCM registration tokenGoogle/Android 推送通道FCM令牌管理完整的移动推送协议细节见 mobile-notifications.md。注意E2EE 推送设备与普通推送设备是两套独立端点——Zulip 移动端对通知内容做了端到端加密的选配方案。Specialty endpoints特殊端点端点功能要点Fetch an API key (production)生产环境用密码/邮箱换取 API keyFetch an API key (development only)仅开发环境可用免密码取 keyFetch an API key (JWT)通过 JWT 认证换取 API keyList users (development only)仅开发环境列出可登录用户Outgoing webhook payloads出站 Webhook 的负载格式规范前三者是 API key 的引导式获取路径适用于交互式脚本JWT 变体则服务于第三方 SSO 集成dev-前缀端点仅在开发模式下注册体现了 Zulip 对开发调试便利性与生产安全的刻意区分。出站 Webhook 负载文档则定义了 Zulip 机器人把事件转发给外部服务时的 JSON 契约。每个端点页长什么样模板与生成机制理解索引文档之后还需要知道点进去能看到什么。api_docs/include/rest-endpoints.md中每个链接指向的独立端点页大多由 api-doc-template.md 统一生成其结构是Usage examples{generate_code_example(python|javascript|curl)}三标签页Python、JavaScript、cURL的真实调用示例Parameters{generate_api_arguments_table|zulip.yaml|API_ENDPOINT_NAME}从 OpenAPI 定义自动生成参数表格配{generate_parameter_description}生成参数详解Response{generate_return_values_table}自动生成的返回值说明以及{generate_code_example|fixture}注入的示例响应fixture。也就是说索引文档本文件决定有哪些端点zulip.yaml 决定每个端点的参数与响应模板把它们拼装成完整页面。tools/下的检查脚本会校验索引、OpenAPI 与端点页三者的一致性保证导航不出现 404。维护者视角如何把一个新端点登记进索引对于想为 Zulip 贡献 API 端点的开发者docs/documentation/api.md 记录了完整的文档化流程其中与本索引直接相关的一步是在zerver/openapi/zulip.yaml中定义端点的 OpenAPI 描述包含operationId、summary、参数与响应 schema确认端点页是否沿用 api-doc-template.md 公共模板仅在有充分理由时才为其单独编写 Markdown在api_docs/include/rest-endpoints.md的对应分类下新增一行URL 必须等于operationId链接文本必须等于 OpenAPIsummary通过http://localhost:9991/api/本地文档服务验证示例可复制、可运行运行./tools/create-api-changelog生成变更记录文件并在 OpenAPI 描述中按 feature level 规范添加**Changes**标注。这套索引 OpenAPI 模板 changelog的规范闭环保证了数百个端点的文档在任何版本迭代下都能保持结构一致、信息准确。从索引到实践建议的阅读与调用路线认证先行任何 API 调用前先阅读 api-keys.md 获取 API key、http-headers.md 了解 Basic Auth 头部格式、rest-error-handling.md 了解标准错误结构result/msg/code选语言官方提供 Python / JavaScript 绑定 与 其他语言客户端官方 Python 绑定中的client.call_endpoint甚至可以调用未收录在文档中的端点发消息从 send-message.md 入手理解type/to/topic/content最小调用拉消息掌握 construct-narrow.md 的 narrow 语法与GET /messages的 anchor 窗口模型做实时应用完整走一遍register → events长轮询→ delete-queue闭环注意BAD_EVENT_QUEUE_ID的重建逻辑实现集成机器人存储、出站 Webhookoutgoing-webhook-payload.md、定时消息create-scheduled-message.md、频道创建create-stream.md分别覆盖了自动化通知、审批流、定时任务与频道供给四大常见集成场景。由于 Zulip 是开源项目当文档无法回答某个问题时你还可以直接阅读zerver/views/下的视图实现消息相关集中在message_fetch.py、message_send.py、message_edit.py与zerver/openapi/zulip.yaml中该端点的**Changes**标注二者是比任何二手教程都权威的行为契约。【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考