Why Cosmic Uses REST (and Why That's the Right Call in 2026)

查看原文 / View Original 编辑 / Edit

Why Cosmic Uses REST (and Why That’s the Right Call in 2026)

为什么 Cosmic 选择使用 REST（以及为什么在 2026 年这是正确的选择）

Every few years, a new API paradigm gets declared the future. GraphQL had its moment. And it’s genuinely good — for certain use cases. But “good for certain use cases” and “better default for most teams” are different claims. REST is still the right default, and in 2026 there’s a new reason it matters: AI agents. Here’s an honest breakdown of the tradeoffs, and why Cosmic is REST-first by design. 每隔几年，就会有一种新的 API 范式被宣称为“未来”。GraphQL 曾风光一时，它在某些特定场景下确实表现出色。但“在特定场景下表现出色”与“成为大多数团队的首选默认方案”是两个不同的概念。REST 依然是正确的默认选择，而在 2026 年，它变得至关重要还有一个新原因：AI 智能体（AI agents）。以下是对两者权衡的客观分析，以及为什么 Cosmic 在设计上坚持“REST 优先”。

The Honest GraphQL vs REST Comparison

关于 GraphQL 与 REST 的客观对比

Let’s be direct about where each one wins. 让我们直接切入重点，看看各自的优势所在。

Where GraphQL excels GraphQL 的优势：

  • Precisely shaped responses. GraphQL lets clients request exactly the fields they need. On mobile or low-bandwidth environments, this can meaningfully reduce payload size. 精确的数据响应。 GraphQL 允许客户端精确请求所需的字段。在移动端或低带宽环境下，这可以显著减小数据传输量。
  • Single endpoint for complex graphs. When your data has deeply nested relationships and you need to traverse them in a single request, GraphQL’s query model can simplify client code. 处理复杂图结构的单一端点。 当数据具有深度嵌套关系且需要通过单次请求遍历时，GraphQL 的查询模型可以简化客户端代码。
  • Rapid iteration on the client side. Frontend teams can adjust what data they fetch without waiting for a backend API change. 客户端快速迭代。 前端团队可以调整获取的数据内容，而无需等待后端 API 的变更。
  • Type-safe schema introspection. Tooling like Apollo DevTools and GraphQL Codegen is genuinely excellent for teams that invest in the ecosystem. 类型安全的模式自省。 对于投入该生态系统的团队来说，Apollo DevTools 和 GraphQL Codegen 等工具确实非常出色。

Where REST wins REST 的优势：

  • Simplicity. A REST endpoint is a URL. Any HTTP client — curl, fetch, Postman, a Python script, an AI agent — can consume it without understanding a schema or learning a query language. 简单易用。 REST 端点就是一个 URL。任何 HTTP 客户端（如 curl、fetch、Postman、Python 脚本或 AI 智能体）都可以直接调用，无需理解复杂的模式或学习查询语言。
  • Cacheability. HTTP caching is built for REST. GET requests to a stable URL can be cached at the CDN layer with no additional tooling. GraphQL’s POST-by-default convention makes this harder. 可缓存性。 HTTP 缓存是为 REST 而生的。针对稳定 URL 的 GET 请求可以在 CDN 层进行缓存，无需额外工具。而 GraphQL 默认使用 POST 的惯例使得缓存实现变得更加困难。
  • Debuggability. When something breaks, a REST API gives you a URL you can open in a browser, paste into Postman, or log directly. GraphQL errors can be harder to trace without dedicated tooling. 易于调试。 当出现问题时，REST API 提供了一个可以直接在浏览器中打开、粘贴到 Postman 或直接记录日志的 URL。而没有专用工具时，GraphQL 的错误往往更难追踪。
  • Ecosystem breadth. REST is universal. Every language, every framework, every tool speaks REST. 生态广泛。 REST 是通用的。每种语言、每个框架、每个工具都支持 REST。
  • Operational simplicity. No query parser, no resolver overhead, no N+1 query problems to solve. For most content APIs, the queries are simple enough that REST’s structure is a feature, not a limitation. 运维简单。 没有查询解析器，没有解析器（resolver）开销，也不需要解决 N+1 查询问题。对于大多数内容 API 而言，查询足够简单，REST 的结构反而是一种特性，而非限制。

The honest verdict on GraphQL

关于 GraphQL 的客观结论

GraphQL makes sense for complex, client-driven data fetching scenarios — large product catalogs with dozens of relationship types, mobile apps with strict bandwidth constraints, teams with mature frontend infrastructure. It’s a real tool for real problems. But most content APIs are not that complex. A blog post has a title, a body, some metadata, and maybe a category. A landing page has sections and a hero image. REST handles these cases cleanly, with less overhead and more cacheability. GraphQL 适用于复杂的、由客户端驱动的数据获取场景——例如拥有数十种关系类型的大型产品目录、带宽受限的移动应用，以及拥有成熟前端基础设施的团队。它确实是解决实际问题的利器。但大多数内容 API 并没有那么复杂。一篇博客文章通常只有标题、正文、一些元数据和分类；一个落地页也只有几个区块和一张主图。REST 可以简洁地处理这些情况，且开销更小、缓存性更好。

Why 2026 Changes the Calculation: AI Agents

为什么 2026 年改变了计算方式：AI 智能体

Here’s the new variable: AI agents are now part of most content workflows. And REST is dramatically better suited for agent consumption than GraphQL. 这里有一个新的变量：AI 智能体现在已成为大多数内容工作流的一部分。而 REST 在供智能体调用方面，比 GraphQL 表现得好得多。

  • REST endpoints are trivially parseable by LLMs. A REST endpoint is a URL with predictable structure: GET /objects?type=blog-posts&limit=10. An AI agent can construct this URL from a natural language instruction without understanding a schema. The response is JSON — structured, flat, predictable. GraphQL requires the agent to understand the schema, construct a valid query document, and handle the query syntax correctly. That’s more tokens, more failure modes, and more prompting complexity. REST 端点极易被大模型（LLM）解析。 REST 端点是一个结构可预测的 URL，例如 GET /objects?type=blog-posts&limit=10。AI 智能体可以根据自然语言指令构建此 URL，而无需理解复杂的模式。其响应是结构化、扁平且可预测的 JSON。相比之下，GraphQL 要求智能体理解模式、构建有效的查询文档并正确处理查询语法。这会消耗更多 Token，增加失败概率，并提高提示词（Prompting）的复杂度。
  • Caching matters for agent workflows. AI agents often make repeated, similar requests — checking content status, fetching object counts, reading metadata. CDN-cached REST responses make this cheap and fast. GraphQL’s POST-by-default pattern bypasses CDN caching entirely, meaning every agent request hits your origin. 缓存对智能体工作流至关重要。 AI 智能体经常发出重复的、相似的请求——例如检查内容状态、获取对象数量、读取元数据。CDN 缓存的 REST 响应使这些操作既廉价又快速。而 GraphQL 默认的 POST 模式完全绕过了 CDN 缓存，这意味着每个智能体请求都会直接命中你的源服务器。
  • Direct URL-based queries are auditable. When an AI agent fetches content via a REST endpoint, the request is a plain URL you can log, inspect, and replay. This matters for debugging agent workflows and for understanding what your agents are actually doing. 基于 URL 的直接查询是可审计的。 当 AI 智能体通过 REST 端点获取内容时，请求就是一个简单的 URL，你可以记录、检查并重放它。这对于调试智能体工作流以及了解智能体实际在做什么非常重要。

The emerging standard: REST + structured JSON

新兴标准：REST + 结构化 JSON

Tools like Model Context Protocol (MCP) and the major LLM provider SDKs are all built around REST + JSON. The ecosystem is converging on REST as the lingua franca for agent-to-service communication — because it’s the most universally parseable format. 诸如模型上下文协议（MCP）和各大 LLM 提供商的 SDK 等工具，都是围绕 REST + JSON 构建的。整个生态系统正在将 REST 视为智能体与服务之间通信的通用语言（lingua franca），因为它是一种最通用的可解析格式。

Cosmic’s REST API in Practice

Cosmic REST API 的实践

Cosmic’s REST API is designed to be fast, predictable, and easy for both humans and AI agents to consume. Sub-100ms response times globally via CDN caching. Whether it’s a developer building a Next.js page or an AI agent fetching content to include in a generated article, the API is consistently fast. Cosmic 的 REST API 设计旨在实现快速、可预测，并方便人类和 AI 智能体调用。通过 CDN 缓存，全球响应时间均在 100ms 以内。无论是开发者构建 Next.js 页面，还是 AI 智能体获取内容以生成文章，该 API 都能保持始终如一的高速。

Here’s a simple example using the Cosmic TypeScript SDK — which wraps the REST API with full type safety: 以下是一个使用 Cosmic TypeScript SDK 的简单示例，它在 REST API 之上封装了完整的类型安全：

import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG as string,
  readKey: process.env.COSMIC_READ_KEY as string,
})

const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props(['id', 'title', 'slug', 'metadata.teaser', 'created_at'])
  .sort('-created_at')
  .limit(10)

console.log(posts)

The SDK compiles down to simple REST requests. No schema introspection. No query document compilation. Just a URL, a JSON response, and TypeScript types. You can also call the REST API directly: 该 SDK 会编译为简单的 REST 请求。无需模式自省，无需查询文档编译。只需一个 URL、一个 JSON 响应和 TypeScript 类型。你也可以直接调用 REST API：

curl "https://api.cosmicjs.com/v3/buckets/my-bucket/objects?type=blog-posts&limit=10&read_key=YOUR_READ_KEY"

That URL is cacheable at the CDN layer, inspectable in a browser, and consumable by any HTTP client — including an AI agent with no Cosmic-specific knowledge whatsoever. 该 URL 可以在 CDN 层缓存，可以在浏览器中检查，并且可以被任何 HTTP 客户端调用——包括那些完全不了解 Cosmic 的 AI 智能体。

The Decision in Plain Terms

简而言之

For most content APIs, REST is faster to implement, easier to cache, simpler to debug, and better suited for the AI-agent workflows that are becoming standard in 2026. GraphQL is the right call when you have complex, client-driven data fetching needs and a team ready to invest in the ecosystem. Those situations exist. But they’re not the default. Cosmic is REST-first because REST is the right default for content delivery — and because in a world where AI agents are increasingly reading and writing your content, the simplicity… 对于大多数内容 API 而言，REST 实现更快、更易于缓存、更简单易调试，并且更适合 2026 年已成为主流的 AI 智能体工作流。当你拥有复杂的、由客户端驱动的数据获取需求，且团队愿意投入该生态系统时，GraphQL 才是正确的选择。这种情况确实存在，但它们并非默认情况。Cosmic 选择“REST 优先”，是因为 REST 是内容交付的正确默认方案——而且在一个 AI 智能体日益频繁地读取和编写内容的时代，这种简洁性……

← 返回新闻列表 / Back to news list