api-design

Enforce REST API resource naming, versioning, and error handling protocols.

3|Updated Mar 28, 2026
One-click install
npx skills add https://github.com/vekzz-dev/opencode-skills --skill api-design-vekzz-dev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/vekzz-dev/opencode-skills/tree/main/api-design
Command: npx skills add https://github.com/vekzz-dev/opencode-skills --skill api-design-vekzz-dev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This skill addresses the complexity of designing consistent RESTful interfaces, helping developers avoid common pitfalls like poor resource naming, improper versioning, and inconsistent error handling.

Core Features & Use Cases

  • Standardized Resource Modeling: Provides clear patterns for CRUD operations, sub-resource nesting, and action-based endpoints.
  • API Lifecycle Management: Offers strategies for versioning (URI, Header, Query) and documentation using OpenAPI/Swagger.
  • Resilience & UX: Implements best practices for error envelopes (RFC 9457), pagination (Cursor/Offset), and HATEOAS to improve client-side integration.

Quick Start

Use the api-design skill to review my current endpoint structure and suggest improvements based on RESTful best practices.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design REST API resource naming conventions and sub-resource nesting?

REST API resource naming conventions standardize endpoint structures by defining clear patterns for CRUD operations, sub-resource nesting, and action-based endpoints. This ensures consistent interface design and maintainability across web service architectures.

What is the best way to version REST API endpoints?

The best way to version REST API endpoints involves implementing standardized lifecycle management strategies using URI, Header, or Query parameter versioning. This maintains backward compatibility while allowing iterative architectural refactoring.

How does HATEOAS implementation work in REST architecture?

HATEOAS implementation in REST architecture works by embedding hypermedia links within response payloads, guiding client-side integration through dynamic navigation. This improves client-side integration by decoupling clients from hardcoded URI structures.

How do I standardize REST API error handling protocols?

REST API error handling protocols are standardized by implementing consistent error envelopes following RFC 9457 specifications. This structures error responses uniformly to improve client-side resilience and integration predictability.

When do I need OpenAPI documentation for web service endpoints?

You need OpenAPI documentation for web service endpoints when standardizing REST API architecture and ensuring maintainability. It satisfies lifecycle management requirements by providing structured Swagger specifications for client integration.