2026-08-21 14:40:05.708033+08 / restful-api
Resource Naming and URI Design
介绍资源命名、URI 路径、路径参数、查询参数和 HTTP Header 的 RESTful API 设计规范。
Resource Naming and URI Design
静态路径段使用小写连字符分隔的单词
静态 URI 路径段必须使用小写单词，并使用连字符分隔。
示例：
/node-groups
/locked-cells该规则只适用于静态路径段，不适用于路径参数名称。
路径参数可以出现在 URI 路径的任意段中
路径参数可以出现在 URI 末尾，也可以出现在其他路径段中。
示例：
/cells/{id}
/cells/{id}/adjacent-cells
/nodes/{id}
/nodes/{id}/connected-nodes
/node-groups/{id}
/node-groups/{id}/nodes优先使用 id 作为主要身份属性
资源应使用唯一的 id 属性作为主要身份属性。
id 的值至少应在对象所属的资源集合范围内保持唯一。
示例：
请求：
GET /nodes/123 HTTP/1.1响应：
HTTP/1.1 200 OK
Content-Type: application/json{
"id": "123",
"userLabel": "KistaEast",
"ipAddress": "192.168.1.1"
}在这个示例中：
id是主要标识符。userLabel和ipAddress是次要标识符。
当业务领域中的自然键能够保证唯一时，也可以使用自然键。
次要标识符可以使用矩阵参数
主要标识符通常应表示为路径参数：
/nodes/{id}/connected-nodes次要标识符应带上属性名称，也可以使用矩阵参数表示。
主要标识符：
/nodes/{id}/connected-nodes矩阵参数：
/nodes/userLabel={userLabel}/connected-nodes/nodes/ipAddress={ipAddress}/connected-nodes多个矩阵参数：
/nodes/ipAddress={ipAddress}/connected-nodes/cabinetName={cabinetName1},{cabinetName2};operationalState={operationalState}矩阵参数允许将带名称的属性直接放入 URI 路径段中。
矩阵路径参数使用 camelCase
矩阵路径参数必须使用 camelCase。
不要使用：
- snake_case
- kebab-case
正确示例：
/nodes/userLabel={userLabel}/connected-nodes
/nodes/ipAddress={ipAddress}/connected-nodes错误示例：
/nodes/user_label={user_label}
/nodes/ip-address={ip_address}该规则不适用于表示主要标识符的简单路径参数。
示例：
/nodes/{id}查询参数使用 camelCase
查询参数必须使用 camelCase。
不要使用：
- snake_case
- kebab-case
正确示例：
customerNumber
orderId
billingAddress
ipAddress错误示例：
customer_number
order-id
billing_addressHTTP Header 字段优先使用连字符 Pascal Case
HTTP Header 字段应优先使用连字符 Pascal Case，以保持命名一致性。
像 ID 这样的常见缩写可以保留大写。
示例：
Accept-Encoding
Apply-To-Redirect-Ref
Disposition-Notification-Options
Original-Message-ID根据 HTTP 标准，HTTP Header 名称不区分大小写。
资源名称使用复数
资源名称应使用复数形式。
大多数 REST API 暴露的是资源集合，即使某个资源当前只有一个实例，也应使用集合形式建模。
正确示例：
/users
/orders
/products
/devices避免：
/user
/order
/product
/deviceSingleton 资源仍然可以建模为元素数量为 1 的集合。
避免使用 /api 作为基础路径
API 基础路径通常不应包含 /api。
推荐：
/customers
/orders
/devices避免：
/api/customers
/api/orders
/api/devices部署基础路径应作为部署配置处理，并与资源路径分开定义。
避免尾部斜杠
资源 URI 不应以尾部斜杠结尾。
推荐：
/customers/123避免：
/customers/123/无论是否存在尾部斜杠，资源都应保持一致的行为；但客户端和服务端应统一使用不带尾部斜杠的格式。
标准查询参数
支持搜索、排序、过滤和分页的 API 应使用约定俗成的查询参数名称。
搜索
使用：
q示例：
/products?q=phoneq 表示用户输入的搜索关键词。
排序
使用：
sort参数值是以逗号分隔的字段列表。
示例：
/orders?sort=id可以通过前缀指定排序方向：
升序：
/orders?sort=+id降序：
/orders?sort=-createdAt多个字段：
/orders?sort=-createdAt,status部分响应字段
使用：
fields示例：
/users?fields=id,name,email这样客户端可以只请求所需的字段。
嵌入关联资源
使用：
embed示例：
/orders?embed=customer这样可以将关联资源直接嵌入响应中。
Offset 分页
使用：
offset示例：
/orders?offset=100offset 表示集合中第一个返回元素的位置。
Cursor 分页
使用：
cursor示例：
/orders?cursor=eyJwYWdlIjoyfQ==Cursor 应被视为不透明值。
客户端不得检查、修改或自行构造 Cursor 值。
限制分页大小
使用：
limit示例：
/orders?limit=50limit 允许客户端建议一次响应最多返回的资源数量。