How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

restful-hateoas - Skill - OpenSmartRoute

Name: restful-hateoas
Author: pproenca

Imported from pproenca/dot-skills (skills/.curated/restful-hateoas/SKILL.md). Install upstream with npx skills add pproenca/dot-skills --skill restful-hateoas. Copyright stays with the author.

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

Install restful-hateoas and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "pproenca-dot-skills-restful-hateoas", "kind": "skill", "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.", "publisher": "pproenca", "version": "1.0.0", "capabilities": { "domains": [ "coding" ], "tags": [ "skill-md", "skills-sh" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "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." ], "primary": false, "metadata": { "source": { "provider": "skills.sh", "repository": "https://github.com/pproenca/dot-skills", "path": "skills/.curated/restful-hateoas/SKILL.md", "ref": "HEAD", "url": "https://github.com/pproenca/dot-skills/blob/HEAD/skills/.curated/restful-hateoas/SKILL.md", "key": "pproenca/dot-skills/skills/.curated/restful-hateoas/SKILL.md" } }, "instructions": "# Community RESTful HATEOAS Best Practices\n\nComprehensive 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.\n\n## When to Apply\n\nReference these guidelines when:\n- Designing new REST API endpoints and resource URIs\n- Adding hypermedia controls (_links, affordances) to API responses\n- Implementing content negotiation with HAL, JSON:API, or vendor media types\n- Building paginated, filte", "cost": { "context_tokens": 1949 } }

restful-hateoas

About