restful-hateoas

Original：🇺🇸 English

Translated

RESTful API design guidelines following the Richardson Maturity Model through to Level 3 (HATEOAS) for Ruby on Rails. This skill should be used when designing, building, reviewing, or refactoring REST APIs to ensure proper resource modeling, HTTP method semantics, hypermedia controls, content negotiation, and API evolvability. Triggers on tasks involving API controllers, serializers, routing, link relations, pagination, error handling, or HTTP caching in Rails.

1installs

Sourcepproenca/dot-skills

Added on2026-02-13

NPX Install

npx skill4agent add pproenca/dot-skills restful-hateoas

SKILL.md Content

View Translation Comparison →

Community RESTful HATEOAS Best Practices

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.

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

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-`

Quick Reference

1. Resource Modeling (CRITICAL)

```
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

2. HTTP Method Semantics (CRITICAL)

```
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

3. Hypermedia & Link Relations (CRITICAL)

```
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

4. Status Codes & Response Headers (HIGH)

```
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

5. Content Negotiation & Media Types (HIGH)

```
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

6. Collection Patterns (MEDIUM-HIGH)

```
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

7. Error Semantics (MEDIUM)

```
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

8. Caching & Conditional Requests (MEDIUM)

```
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

9. API Evolution (LOW-MEDIUM)

```
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

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