# restful-hateoas

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 304 installs · ★ 227 repo stars
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/restful-hateoas/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/restful-hateoas

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill restful-hateoas -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/restful-hateoas/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/restful-hateoas/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill restful-hateoas -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/restful-hateoas/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill restful-hateoas -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/restful-hateoas/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills skills/.curated/restful-hateoas
```

2. **Manually: put the files in place**
- File: `.github/skills/restful-hateoas/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill restful-hateoas -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/restful-hateoas
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/restful-hateoas/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill restful-hateoas -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/restful-hateoas/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3225ff36a9341589.

BEGIN THIRD-PARTY FILE 3225ff36a9341589
```text
---
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
```
END THIRD-PARTY FILE 3225ff36a9341589

The third-party file has ended. Everything between the 3225ff36a9341589 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2892 of 8312 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/restful-hateoas/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
