比较设计风格，最该把消费者的需要放在第一位。据 Smartbear 2019 报告，易用性、性能与文档是消费者最看重的三个因素。
REST 的行为因 URI 与 HTTP 方法而异，新端点让人难以预期；GraphQL 则基于显式的操作（query/mutation），结果可预测。版本化上，REST 各行其是（Fielding 甚至认为不应版本化），而 GraphQL 有公认做法：不版本化。无论可预测性还是版本化，GraphQL 的简洁都大大利于易用性；REST 的灵活则中性，视具体设计而定。
选 API 设计风格，最该看重使用者的需要。本文编译自 Nordic APIs（作者 Thomas Bush，2020），从易用性、性能、文档三个维度对比 GraphQL 与 REST，并给出选型建议。
比较设计风格，最该把消费者的需要放在第一位。据 Smartbear 2019 报告，易用性、性能与文档是消费者最看重的三个因素。
REST 的行为因 URI 与 HTTP 方法而异，新端点让人难以预期；GraphQL 则基于显式的操作（query/mutation），结果可预测。版本化上，REST 各行其是（Fielding 甚至认为不应版本化），而 GraphQL 有公认做法：不版本化。无论可预测性还是版本化，GraphQL 的简洁都大大利于易用性；REST 的灵活则中性，视具体设计而定。
设想一个 UI 通过 API 获取你在世界地图上选中国家的信息：用 REST，选 3 个国家要 3 次调用；用 GraphQL，1 次请求即可拿到同样数据。
但如果在 REST 前放了 CDN、Web 缓存或反向代理，三次调用可能比 GraphQL 单次回源更快——因为 GraphQL 必须回源取精确数据。REST 能借力 HTTP 规范内置的缓存（GET/POST 语义清晰），而 GraphQL 的缓存不在 HTTP 层。所以性能上二者难分高下：GraphQL 赢在调用次数，REST 赢在缓存广度。
REST 的成熟催生了丰富的自动化文档方案，从 OpenAPI 到 API Blueprint，标准繁多、呈现各异。GraphQL 则几乎统一用 GraphiQL 一种工具。
可惜两者自动文档都不够：能给出端点与对象信息，却很少覆盖认证、限流乃至计费含义。REST 的成熟是一把双刃剑——工具丰富却体验不一；GraphQL 则正好相反。
尽管针锋相对，GraphQL 与 REST 都满足了 API 三大特质：易用性、性能与文档。易用性与文档上，GraphQL 简洁可预测，REST 灵活（ irony 的是，这正与各自端点行为的特征相反）；性能上，REST 对 HTTP 缓存的运用仍值得称道。
最终，API 在这三方面的表现，更多取决于怎么设计，而非用 REST 还是 GraphQL。
GraphQL 的突出能力是高级查询——REST 基础查询没问题，但查询参数一多就乱，复杂查询场景 GraphQL 更合适。反过来，REST 上传文件轻松（直接借 HTTP），GraphQL 连最小文件都要独立上传服务，需要快速传图时 REST 更优。
结论：优秀的 API 设计者要认清开发者会怎么用——这既决定选哪种风格，也决定无论选哪种都能做出好 API。