skills.rest
pproenca
pproencaCOMMUNITY
Explore all skills by this author →
𝕏@ThePedroProencaGitHub

restful-hateoas

Design RESTful APIs with HATEOAS hypermedia controls and Richardson Maturity Model Level 3.

193|17|Updated Jan 16, 2026
Search Tags:#api design#rest#hypermedia#resource modeling#hateoas#api evolution#http semantics
One-click install
npx skills add https://github.com/pproenca/dot-skills --skill restful-hateoas
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: restful-hateoas
Source: https://github.com/pproenca/dot-skills/tree/main/skills/.curated/restful-hateoas
Command: npx skills add https://github.com/pproenca/dot-skills --skill restful-hateoas

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve?

This Skill addresses the challenge of building truly RESTful APIs that are discoverable, evolvable, and maintainable by adhering to HATEOAS principles. It moves beyond basic CRUD to implement hypermedia controls that guide clients and decouple them from server-side URI structures.

Core Features & Use Cases

  • Resource Modeling: Design URIs using nouns, plural collections, and limited nesting.
  • HTTP Method Semantics: Ensure correct usage of GET, POST, PUT, PATCH, DELETE for safety and idempotency.
  • Hypermedia Controls: Implement _links for self-reference, related resources, and action affordances.
  • Content Negotiation: Support multiple representations (JSON, HAL, JSON:API) via Accept headers.
  • Error Handling: Use standard Problem Details (RFC 9457) with machine-readable codes and recovery links.
  • API Evolution: Leverage HATEOAS to eliminate URL versioning and enable additive changes.
  • Use Case: When designing a new e-commerce API, use this Skill to ensure that clients can discover products, add them to a cart, checkout, and track shipments purely by following links provided in API responses, without needing to hardcode any URI patterns.

Quick Start

Apply the restful-hateoas skill to ensure all API responses include a self link pointing to the resource's canonical URI.

Frequently Asked Questions about restful-hateoas

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is HATEOAS and how does it make a REST API evolvable?▼

HATEOAS embeds hypermedia links in REST API responses, guiding clients to discover actions dynamically. This decouples clients from hardcoded URI structures, enabling servers to evolve APIs additively without breaking existing integrations.

How do I design REST API URIs and HTTP methods for resource modeling?▼

Design REST API URIs using plural nouns for collections with limited nesting. Apply HTTP methods by semantics: GET for safe reads, POST for creation, PUT or PATCH for updates, and DELETE for removal, ensuring correct idempotency and safety.

What is the best way to handle REST API errors with machine-readable codes?▼

Handle REST API errors using standard Problem Details (RFC 9457) responses. This format provides machine-readable error codes, human-readable details, and recovery links, allowing clients to programmatically parse failures and follow hypermedia controls for resolution.

Does this HATEOAS approach work with Ruby on Rails and multiple content types?▼

Yes, this HATEOAS approach works with Ruby on Rails and supports content negotiation via Accept headers. It allows serving multiple representations, including JSON, HAL, and JSON:API formats, from the same resource endpoints.

How to implement hypermedia controls and _links in a REST API?▼

Implement hypermedia controls by embedding a `_links` object in every REST API response. Include a `self` link for the canonical resource URI, links to related resources, and action affordances that dictate valid state transitions.

Why use HATEOAS to eliminate URL versioning in API evolution?▼

HATEOAS eliminates URL versioning by allowing clients to discover endpoints dynamically through hypermedia links rather than hardcoded paths. This enables additive API changes and resource modifications without requiring versioned URI structures.

Related Skills

Explore More Software Engineering Skills→
EveryIncEveryInc
24.1k

dhh-rails-style

Enforce DHH RESTful Rails conventions in Ruby code reviews.

Official
Advanced
berkayoztuncberkayoztunc
21

Link Header Support

Publish RFC 8288 Link headers for API catalog, OpenAPI, documentation, and MCP server-card relations.

Community
Basic
ChwistopheChwistophe

rails-37-style-backend-caching

Implement HTTP and fragment caching patterns in Rails applications.

Community
Intermediate
twofoldtech-dakotatwofoldtech-dakota
2

fullstack-modern

Coordinate React or Vue frontends with GraphQL and REST APIs in Next.js-style apps.

Community
Advanced