restful-hateoas

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community RESTful HATEOAS Best Practices

社区RESTful HATEOAS最佳实践

Comprehensive guide to building REST APIs that reach the Glory of REST (Richardson Maturity Level 3) in Ruby on Rails. Contains 44 rules across 9 categories, ordered by the request/response lifecycle — from resource URI design through hypermedia link relations to API evolution.

这是一份在Ruby on Rails中构建达到REST巅峰（Richardson成熟度第3级）的REST API的综合指南。包含9个类别共44条规则，按请求/响应生命周期排序——从资源URI设计到超媒体链接关系，再到API演进。

When to Apply

适用场景

Reference these guidelines when:

Designing new REST API endpoints and resource URIs
Adding hypermedia controls (_links, affordances) to API responses
Implementing content negotiation with HAL, JSON:API, or vendor media types
Building paginated, filterable, sortable collection endpoints
Reviewing APIs for proper HTTP method semantics and status codes
Evolving APIs without breaking existing clients

在以下场景中参考本指南：

设计新的REST API端点和资源URI
为API响应添加超媒体控制（_links、功能入口）
基于HAL、JSON:API或供应商媒体类型实现内容协商
构建支持分页、过滤、排序的集合端点
评审API的HTTP方法语义和状态码是否规范
在不破坏现有客户端的前提下演进API

Rule Categories by Priority

按优先级划分的规则类别


res-
http-
link-
status-
media-
coll-
err-
cache-
evolve-

Priority	Category	Impact	Prefix
1	Resource Modeling	CRITICAL	`res-`
2	HTTP Method Semantics	CRITICAL	`http-`
3	Hypermedia & Link Relations	CRITICAL	`link-`
4	Status Codes & Response Headers	HIGH	`status-`
5	Content Negotiation & Media Types	HIGH	`media-`
6	Collection Patterns	MEDIUM-HIGH	`coll-`
7	Error Semantics	MEDIUM	`err-`
8	Caching & Conditional Requests	MEDIUM	`cache-`
9	API Evolution	LOW-MEDIUM	`evolve-`


res-
http-
link-
status-
media-
coll-
err-
cache-
evolve-

优先级	类别	影响程度	前缀
1	资源建模	关键	`res-`
2	HTTP方法语义	关键	`http-`
3	超媒体与链接关系	关键	`link-`
4	状态码与响应头	高	`status-`
5	内容协商与媒体类型	高	`media-`
6	集合模式	中高	`coll-`
7	错误语义	中	`err-`
8	缓存与条件请求	中	`cache-`
9	API演进	中低	`evolve-`

Quick Reference

快速参考

1. Resource Modeling (CRITICAL)

1. 资源建模（关键）

```
res-noun-based-uris
```
- URIs must be nouns, not verbs
```
res-plural-collection-uris
```
- Always use plural nouns for collections
```
res-limit-nesting-depth
```
- Limit nested resources to max 2 levels
```
res-model-business-entities
```
- Model business entities, not database tables
```
res-use-consistent-identifiers
```
- Use opaque identifiers, never auto-increment IDs
```
res-sub-resources-for-relationships
```
- Express relationships as sub-resources

```
res-noun-based-uris
```
- URI必须使用名词，而非动词
```
res-plural-collection-uris
```
- 集合URI始终使用复数名词
```
res-limit-nesting-depth
```
- 嵌套资源最多限制为2级
```
res-model-business-entities
```
- 建模业务实体，而非数据库表
```
res-use-consistent-identifiers
```
- 使用不透明标识符，绝不使用自增ID
```
res-sub-resources-for-relationships
```
- 将关系表示为子资源

2. HTTP Method Semantics (CRITICAL)

2. HTTP方法语义（关键）

```
http-get-must-be-safe
```
- Keep GET requests free of side effects
```
http-post-for-creation
```
- Return 201 Created with Location header from POST
```
http-put-for-full-replacement
```
- Use PUT only for full resource replacement
```
http-patch-for-partial-updates
```
- PATCH for partial updates with merge semantics
```
http-delete-is-idempotent
```
- Ensure DELETE is idempotent
```
http-head-for-metadata
```
- Use HEAD for metadata without body transfer

```
http-get-must-be-safe
```
- GET请求不得产生副作用
```
http-post-for-creation
```
- POST请求返回201 Created状态码及Location头
```
http-put-for-full-replacement
```
- 仅在完全替换资源时使用PUT
```
http-patch-for-partial-updates
```
- 使用PATCH进行带合并语义的部分更新
```
http-delete-is-idempotent
```
- 确保DELETE请求是幂等的
```
http-head-for-metadata
```
- 使用HEAD请求获取元数据，无需传输响应体

3. Hypermedia & Link Relations (CRITICAL)

3. 超媒体与链接关系（关键）

```
link-self-link-every-resource
```
- Include a self link in every resource
```
link-related-resource-links
```
- Link to related resources instead of foreign keys
```
link-action-affordances
```
- Expose available actions as conditional links
```
link-standard-relation-types
```
- Use IANA-registered link relation types
```
link-entry-point
```
- Provide a root API entry point
```
link-pagination-links
```
- Use hypermedia links for pagination
```
link-embedded-vs-linked
```
- Choose between embedding and linking

```
link-self-link-every-resource
```
- 每个资源都必须包含self链接
```
link-related-resource-links
```
- 链接到关联资源，而非返回外键
```
link-action-affordances
```
- 将可用操作暴露为条件链接
```
link-standard-relation-types
```
- 使用IANA注册的链接关系类型
```
link-entry-point
```
- 提供API根入口点
```
link-pagination-links
```
- 使用超媒体链接实现分页
```
link-embedded-vs-linked
```
- 在嵌入和链接之间做出合理选择

4. Status Codes & Response Headers (HIGH)

4. 状态码与响应头（高）

```
status-201-with-location
```
- Return 201 Created with Location header
```
status-204-for-no-content
```
- Return 204 No Content for empty responses
```
status-409-for-conflicts
```
- Return 409 Conflict for state conflicts
```
status-202-for-async
```
- Return 202 Accepted for async operations
```
status-allow-header-on-405
```
- Return 405 with Allow header for wrong methods

```
status-201-with-location
```
- 返回201 Created状态码及Location头
```
status-204-for-no-content
```
- 空响应返回204 No Content状态码
```
status-409-for-conflicts
```
- 状态冲突时返回409 Conflict状态码
```
status-202-for-async
```
- 异步操作返回202 Accepted状态码
```
status-allow-header-on-405
```
- 方法错误返回405状态码时需附带Allow头

5. Content Negotiation & Media Types (HIGH)

5. 内容协商与媒体类型（高）

```
media-accept-header-negotiation
```
- Respect the Accept header for content negotiation
```
media-content-type-in-responses
```
- Set the correct Content-Type in every response
```
media-vendor-media-types
```
- Use vendor media types for API versioning
```
media-406-for-unsupported-types
```
- Return 406 for unsupported media types

```
media-accept-header-negotiation
```
- 尊重Accept头进行内容协商
```
media-content-type-in-responses
```
- 每个响应都需设置正确的Content-Type
```
media-vendor-media-types
```
- 使用供应商媒体类型进行API版本控制
```
media-406-for-unsupported-types
```
- 不支持的媒体类型返回406状态码

6. Collection Patterns (MEDIUM-HIGH)

6. 集合模式（中高）

```
coll-cursor-pagination
```
- Use cursor-based pagination instead of offset
```
coll-link-header-pagination
```
- Include pagination links in body and Link header
```
coll-filtering-via-query-params
```
- Support filtering via typed query parameters
```
coll-sorting-convention
```
- Support sorting with a standardized sort parameter
```
coll-field-selection
```
- Support sparse fieldsets via fields parameter

```
coll-cursor-pagination
```
- 使用基于游标分页替代偏移量分页
```
coll-link-header-pagination
```
- 在响应体和Link头中包含分页链接
```
coll-filtering-via-query-params
```
- 支持通过类型化查询参数进行过滤
```
coll-sorting-convention
```
- 使用标准化的sort参数支持排序
```
coll-field-selection
```
- 通过fields参数支持稀疏字段集

7. Error Semantics (MEDIUM)

7. 错误语义（中）

```
err-problem-details
```
- Use Problem Details (RFC 9457) for errors
```
err-validation-errors
```
- Return structured validation errors
```
err-error-links
```
- Include recovery links in error responses
```
err-machine-readable-codes
```
- Use machine-readable error codes

```
err-problem-details
```
- 使用Problem Details（RFC 9457）格式返回错误
```
err-validation-errors
```
- 返回结构化的验证错误
```
err-error-links
```
- 在错误响应中包含恢复链接
```
err-machine-readable-codes
```
- 使用机器可读的错误码

8. Caching & Conditional Requests (MEDIUM)

8. 缓存与条件请求（中）

```
cache-etag-conditional-get
```
- Use ETags with stale? for conditional GET
```
cache-last-modified
```
- Set Last-Modified for time-based validation
```
cache-cache-control-headers
```
- Set explicit Cache-Control headers
```
cache-vary-header
```
- Include Vary header for content-dependent caching

```
cache-etag-conditional-get
```
- 将ETag与stale?配合使用实现条件GET
```
cache-last-modified
```
- 设置Last-Modified头实现基于时间的验证
```
cache-cache-control-headers
```
- 设置明确的Cache-Control头
```
cache-vary-header
```
- 包含Vary头以支持基于内容的缓存

9. API Evolution (LOW-MEDIUM)

9. API演进（中低）

```
evolve-additive-changes-only
```
- Make only additive changes to responses
```
evolve-deprecation-headers
```
- Use Deprecation and Sunset headers
```
evolve-hateoas-reduces-versioning
```
- Leverage HATEOAS to eliminate URL versioning

```
evolve-additive-changes-only
```
- 仅对响应进行增量变更
```
evolve-deprecation-headers
```
- 使用Deprecation和Sunset头
```
evolve-hateoas-reduces-versioning
```
- 利用HATEOAS消除URL版本控制

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构和影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息