restful-hateoas

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