api-design-principles

Guide REST and GraphQL API design with versioning, error handling, and security.

Updated Mar 25, 2026

Search Tags:#api design #rest #graphql #api patterns #api best practices

Ready to run

npx skills add https://github.com/nccasia/bwl-v2 --skill api-design-principles-nccasia

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/nccasia/bwl-v2/tree/main/.agents/skills/api-design-principles
Command: npx skills add https://github.com/nccasia/bwl-v2 --skill api-design-principles-nccasia

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This Skill helps in mastering REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs.

Core Features & Use Cases

API Design Principles: Provides guidelines for REST and GraphQL API design.
Design Patterns: Offers best practices for API design patterns like RESTful design and GraphQL schema design.
Versioning Strategies: Explains various versioning strategies for APIs.
Error Handling: Provides best practices for error handling and status codes.
Security and Performance: Offers tips on security and performance considerations for APIs.
Use Case: Ideal for software engineers and API designers looking to improve their API design skills and implement best practices.

Quick Start

Use the api-design-principles skill to understand RESTful design principles for APIs.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema

What are the best practices for REST API error handling and status codes?▼

REST API error handling best practices involve using standard HTTP status codes correctly and returning consistent error response payloads. This skill provides guidelines for mapping errors to appropriate status codes and structuring error details for maintainable APIs.

How do I design a scalable GraphQL schema?▼

Designing a scalable GraphQL schema requires defining clear types, queries, and mutations following architectural patterns. This skill offers best practices for GraphQL schema design to ensure your API remains intuitive and maintainable as it grows.

What's the best way to version my API?▼

The best way to version an API depends on your architectural style, whether REST or GraphQL. This skill explains various API versioning strategies, helping you choose an approach that balances backward compatibility with evolutionary design.

Do I need prior knowledge of HTTP methods and data modeling to use these API design principles?▼

Yes, applying these API design principles requires existing knowledge of HTTP methods, data modeling, and API security practices. This skill builds on that foundation to guide you through architectural patterns, versioning, and performance considerations.

When should I choose REST over GraphQL for my API architecture?▼

Choosing REST over GraphQL depends on your specific data fetching needs and architectural patterns. This skill compares REST and GraphQL design principles, outlining scenarios where each approach maximizes security, performance, and scalability.