一个设计良好的REST API几乎是隐形的——它做了你期望的事，错误信息有用，结构一致。设计糟糕的API仅为使用基本功能就需要大量文档。以下是真正重要的原则。
以资源为中心的URL
资源（名词，而非动词）构成URL结构。/users/123是正确的；/getUser?id=123不是。集合用复数：/users、/orders、/products。嵌套资源反映关系：/users/123/orders获取属于用户123的订单。保持URL简单可预测——如果有人无需阅读文档就能猜到资源的URL，你做对了。
HTTP方法有其含义
GET用于检索（安全，幂等）。POST创建新资源或触发操作。PUT完全替换一个资源。PATCH更新特定字段。DELETE删除。使用GET进行修改数据的操作是一个常见错误，会破坏缓存并导致意外修改。对所有操作使用POST（RPC风格）会丢弃HTTP语义。
一致的错误响应
返回结构化的错误对象，而非纯文本错误消息。包含：准确反映错误类别的HTTP状态码（400 Bad Request、401 Unauthorized、404 Not Found、422 Unprocessable Entity、500 Internal Server Error）、机器可读的错误代码和人类可读的消息。RFC 7807问题详情格式是一个好的标准可供遵循。
版本控制
在公开部署前对API进行版本控制，而非之后。URL版本控制（/v1/users）最直观、最易管理。Header版本控制更简洁但不那么明显。无论选择什么，都要坚持——部署后更改版本控制策略很痛苦。永远不要在没有迁移期的情况下破坏v1端点。
分页
永远不要返回无边界的集合——始终分页。基于游标的分页（next_cursor令牌）对于页面请求之间可能插入或删除行的大型数据集，比基于偏移的分页（page=3&limit=50）扩展性更好。在每个集合响应中包含分页元数据：total_count、next_cursor、has_more。
