api-design-principles
Skill by wpank
Why use this skill?
Learn to design scalable REST and GraphQL APIs. Get expert advice on resource modeling, pagination, and error handling for developers.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/wpank/api-design-principlesWhat This Skill Does
The api-design-principles skill is a comprehensive knowledge base and advisory tool for software architects and developers. It serves as a structured reference for building modern, robust, and intuitive APIs. The skill encapsulates industry-standard practices for both REST and GraphQL paradigms, focusing on clean resource modeling, adherence to HTTP semantics, sophisticated pagination strategies, and standardized error handling. By providing an explicit decision framework, it helps teams determine whether a RESTful approach or a GraphQL-driven architecture is best suited for their specific project requirements, performance constraints, and team expertise levels. It effectively acts as a pair-programmer for architectural reviews, ensuring that API specifications align with RESTful conventions like proper status code usage, resource naming hierarchies, and the avoidance of common design pitfalls like over-nesting.
Installation
To integrate this skill into your environment, run the following command in your terminal:
clawhub install openclaw/skills/skills/wpank/api-design-principles
Use Cases
- Drafting new API schemas from scratch for REST or GraphQL services.
- Conducting design reviews to ensure API compliance with architectural standards before code is written.
- Determining the best paradigm for complex data-driven applications compared to simple CRUD services.
- Standardizing error responses and status codes across a microservices-based architecture.
- Refactoring existing legacy API endpoints to improve developer ergonomics and resource discoverability.
Example Prompts
- "I am designing a new e-commerce service; please help me decide if I should use REST or GraphQL, considering my primary need is a mobile-first interface with high-frequency data updates."
- "Review this endpoint path: GET /api/v1/users/{id}/orders/{orderId}/items/{itemId}/details. Is this compliant with RESTful design principles? If not, suggest a flatter alternative."
- "Explain the difference between cursor-based and offset-based pagination and tell me when to use each for a large user database."
Tips & Limitations
While this skill provides authoritative guidance on design principles, it cannot automatically audit or modify your actual production codebases or databases. It is a consultative tool. Always combine these design patterns with your team's specific security requirements and existing infrastructure constraints. When designing APIs, prioritize consistency across all endpoints; a well-designed but inconsistent API is often harder to maintain than one with minor flaws that is predictable throughout.
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-wpank-api-design-principles": {
"enabled": true,
"auto_update": true
}
}
}Tags(AI)
Related Skills
mermaid-diagrams
Create software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams, sequence diagrams, flowcharts, ERDs, C4 architecture diagrams, state diagrams, git graphs, and other diagram types. Triggers include requests to diagram, visualize, model, map out, or show the flow of a system.
auto-context
Automatically read relevant context before major actions. Loads TODO.md, roadmap.md, handoffs, task plans, and other project context files so the AI operates with full situational awareness. Use when starting a task, implementing a feature, refactoring, debugging, planning, or resuming a session.
clear-writing
Write clear, concise prose for humans — documentation, READMEs, API docs, commit messages, error messages, UI text, reports, and explanations. Combines Strunk's rules for clearer prose with technical documentation patterns, structure templates, and review checklists.
compare-pools
Compare all Uniswap pools for a token pair across fee tiers and versions. Use when the user asks which pool is best, wants to compare V3 vs V4, or wants to find the optimal fee tier.
track-performance
Track the performance of Uniswap LP positions over time — check which positions need attention, are out of range, or have uncollected fees. Use when the user asks how their positions are doing.