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

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

• http-idempotency-key

• Use idempotency keys for safe POST retries

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

• status-rate-limit-headers

• Include rate limit headers in API responses

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

• err-auth-error-codes

• Distinguish 401 Unauthorized from 403 Forbidden

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