api-design-principles
Design principles and playbooks for creating scalable REST and GraphQL APIs.
Install
mkdir -p .claude/skills/api-design-principles-ranbot-ai && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/11083" && unzip -o skill.zip -d .claude/skills/api-design-principles-ranbot-ai && rm skill.zipInstalls to .claude/skills/api-design-principles-ranbot-ai
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.Key capabilities
- →Design new REST or GraphQL APIs
- →Refactor existing APIs for better usability
- →Establish API design standards for a team
- →Review API specifications before implementation
- →Migrate between API paradigms
- →Create developer-friendly API documentation
How it works
The skill guides the user through defining consumers, use cases, and constraints, then choosing an API style and modeling resources or types. It then specifies error handling, versioning, pagination, and authentication strategies.
Inputs & outputs
When to use api-design-principles
- →Designing new APIs
- →Refactoring API interfaces
- →Establishing API standards
About this skill
API Design Principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
Use this skill when
- Designing new REST or GraphQL APIs
- Refactoring existing APIs for better usability
- Establishing API design standards for your team
- Reviewing API specifications before implementation
- Migrating between API paradigms (REST to GraphQL, etc.)
- Creating developer-friendly API documentation
- Optimizing APIs for specific use cases (mobile, third-party integrations)
Do not use this skill when
- You only need implementation guidance for a specific framework
- You are doing infrastructure-only work without API contracts
- You cannot change or version public interfaces
Instructions
- Define consumers, use cases, and constraints.
- Choose API style and model resources or types.
- Specify errors, versioning, pagination, and auth strategy.
- Validate with examples and review for consistency.
Refer to resources/implementation-playbook.md for detailed patterns, checklists, and templates.
Resources
resources/implementation-playbook.mdfor detailed patterns, checklists, and templates.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
When not to use it
- →Only implementation guidance for a specific framework is needed
- →Infrastructure-only work without API contracts is being done
- →Public interfaces cannot be changed or versioned
Limitations
- →The skill should only be used when the task matches the described scope.
How it compares
This workflow provides a structured approach to API design by validating with examples and reviewing for consistency, unlike an ad-hoc design process.
Compared to similar skills
api-design-principles side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| api-design-principles (this skill) | 0 | 4mo | No flags | Intermediate |
| mcp-builder | 136 | 3mo | Review | Advanced |
| api-design-principles | 72 | 2mo | No flags | Intermediate |
| langchain-architecture | 8 | 2mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by ranbot-ai
View all by ranbot-ai →You might also like
mcp-builder
anthropics
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
api-design-principles
wshobson
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
langchain-architecture
wshobson
Design LLM applications using the LangChain framework with agents, memory, and tool integration patterns. Use when building LangChain applications, implementing AI agents, or creating complex LLM workflows.
nodejs-backend-patterns
wshobson
Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when creating Node.js servers, REST APIs, GraphQL backends, or microservices architectures.
springboot-patterns
affaan-m
Spring Boot 架构模式、REST API 设计、分层服务、数据访问、缓存、异步处理和日志记录。适用于 Java Spring Boot 后端工作。
backend-architect
sickn33
Expert backend architect specializing in scalable API design, microservices architecture, and distributed systems. Masters REST/GraphQL/gRPC APIs, event-driven architectures, service mesh patterns, and modern backend frameworks. Handles service boundary definition, inter-service communication, resilience patterns, and observability. Use PROACTIVELY when creating new backend services or APIs.