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

res-

http-

link-

status-

media-

coll-

err-

cache-

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