Skip to main content
skill CX Codex

restful-hateoas — Claude Code skill: what it does, how to install

restful-hateoas adds 47 guidelines for building Richardson Maturity Level 3 REST APIs with HATEOAS in Ruby on Rails projects.

MIT 304 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill restful-hateoas -a claude-code
Open on GitHub

What restful-hateoas does

The skill equips coding agents with 47 REST design rules divided into 9 lifecycle categories. It covers resource URI design, HTTP verb semantics, hypermedia affordances, status codes, content negotiation, collection patterns, error handling, and caching.

Specific guidelines mandate plural nouns for paths, a 2-level limit on resource nesting, opaque identifiers instead of database IDs, and cursor pagination over offset pagination. Error structures follow the RFC 9457 Problem Details standard, while responses receive hypermedia controls like _links.

All rules target Ruby on Rails controllers, routes, and serializers, which makes them ill-fitted for other web frameworks without manual translation.

What it helps with

  • model Rails API controllers and serializers using HATEOAS links
  • configure cursor-based pagination and typed query filters
  • format API errors using the RFC 9457 Problem Details standard
  • enforce HTTP method semantics and status codes across endpoints

Example prompts for the agent

  • Review Api::V1::ArticlesController and add HATEOAS affordances to the response
  • Design cursor pagination and sorting for the orders collection endpoint
  • Refactor our Rails error responses to follow RFC 9457

How to install restful-hateoas

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill restful-hateoas -a claude-code

2Manually: put the files in place

~/.claude/skills/restful-hateoas/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/restful-hateoas/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about restful-hateoas

How to install restful-hateoas in Claude Code?

Run npx skills add pproenca/dot-skills --skill restful-hateoas -a claude-code. The skill will be placed into ~/.claude/skills/restful-hateoas/SKILL.md.

What does restful-hateoas do?

It guides the agent to design and refactor Ruby on Rails REST APIs up to Richardson Maturity Level 3 using hypermedia controls.

Which rule categories are included?

The guide covers 9 categories, starting from Resource Modeling and HTTP Semantics to Caching and API Evolution.

Source text

SKILL.md · MIT
---
name: restful-hateoas
description: 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.
---

# 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`](references/res-noun-based-uris.md) - URIs must be nouns, not verbs
- [`res-plural-collection-uris`](references/res-plural-collection-uris.md) - Always use plural nouns for collections
- [`res-limit-nesting-depth`](references/res-limit-nesting-depth.md) - Limit nested resources to max 2 levels
- [`res-model-business-entities`](references/res-model-business-entities.md) - Model business entities, not database tables
- [`res-use-consistent-identifiers`](references/res-use-consistent-identifiers.md) - Use opaque identifiers, never auto-increment IDs
- [`res-sub-resources-for-relationships`](references/res-sub-resources-for-relationships.md) - Express relationships as sub-resources

### 2. HTTP Method Semantics (CRITICAL)

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

### 3. Hypermedia & Link Relations (CRITICAL)

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

### 4. Status Codes & Response Headers (HIGH)

- [`status-201-with-location`](references/status-201-with-location.md) - Return 201 Created with Location header
- [`status-204-for-no-content`](references/status-204-for-no-content.md) - Return 204 No Content for empty responses
- [`status-409-for-conflicts`](references/status-409-for-conflicts.md) - Return 409 Conflict for state conflicts
- [`status-202-for-async`](references/status-202-for-async.md) - Return 202 Accepted for async operations
- [`status-allow-header-on-405`](references/status-allow-header-on-405.md) - Return 405 with Allow header for wrong methods
- [`status-rate-limit-headers`](references/status-rate-limit-headers.md) - Include rate limit headers in API responses

### 5. Content Negotiation & Media Types (HIGH)

- [`media-accept-header-negotiation`](references/media-accept-header-negotiation.md) - Respect the Accept header for content negotiation
- [`media-content-type-in-responses`](references/media-content-type-in-responses.md) - Set the correct Content-Type in every response
- [`media-vendor-media-types`](references/media-vendor-media-types.md) - Use vendor media types for API versioning
- [`media-406-for-unsupported-types`](references/media-406-for-unsupported-types.md) - Return 406 for unsupported media types

### 6. Collection Patterns (MEDIUM-HIGH)

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

### 7. Error Semantics (MEDIUM)

- [`err-problem-details`](references/err-problem-details.md) - Use Problem Details (RFC 9457) for errors
- [`err-validation-errors`](references/err-validation-errors.md) - Return structured validation errors
- [`err-error-links`](references/err-error-links.md) - Include recovery links in error responses
- [`err-machine-readable-codes`](references/err-machine-readable-codes.md) - Use machine-readable error codes
- [`err-auth-error-codes`](references/err-auth-error-codes.md) - Distinguish 401 Unauthorized from 403 Forbidden

### 8. Caching & Conditional Requests (MEDIUM)

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

### 9. API Evolution (LOW-MEDIUM)

- [`evolve-additive-changes-only`](references/evolve-additive-changes-only.md) - Make only additive changes to responses
- [`evolve-deprecation-headers`](references/evolve-deprecation-headers.md) - Use Deprecation and Sunset headers
- [`evolve-hateoas-reduces-versioning`](references/evolve-hateoas-reduces-versioning.md) - Leverage HATEOAS to eliminate URL versioning

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
rails-testing rails-testing — a set of 46 rules for RSpec, FactoryBot, and Capybara in Ruby on Rails. Guides your AI agent during test generation, reviews, and test suite refactoring. CX Codex +1 309installs ruby-refactor ruby-refactor — a refactoring skill with 45 community guidelines for Ruby projects. Helps agents simplify nested branches, decouple classes, and adopt modern Ruby 3.x patterns. CX Codex +1 307installs ios-xcode ios-xcode is a Claude Code skill for Xcode setup and iOS project tooling. It applies to App-target configuration, SwiftData, testing, debugging, profiling, and app distribution. CX Codex +1 307installs think think — a skill that shifts the AI into deep analysis mode: instead of the first reasonable answer, it finds the highest-leverage solution by connecting ideas across domains. Use it when you need strategy, not instructions. CX Codex +1 307installs ios-ui-refactor The ios-ui-refactor skill reviews existing SwiftUI screens and guides refactoring of hierarchy, transitions, animations, and visual systems for iOS 26 and Swift 6.2. CX Codex +1 299installs rails-dev Set of guidelines for Ruby on Rails development. Helps build clean controllers, optimize ActiveRecord queries, and configure caching. CX Codex +1 299installs swift-optimise The swift-optimise skill reviews Swift and SwiftUI performance across concurrency, rendering, and animation. Use it while profiling clinic modules. CX Codex +1 293installs ruby-optimise The ruby-optimise skill guides Ruby code reviews and refactors around performance. Use it when working with allocations, collections, ActiveRecord queries, or runtime settings. CX Codex +1 292installs

Project sponsors

Companies that keep this analytics open