restful-hateoas

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.