designing-api-principles

What problem does it solve?

This Skill addresses the challenge of creating APIs that are consistent, maintainable, and scalable by providing clear principles for REST and GraphQL design. It prevents costly rewrites by ensuring contracts are solid from the start.

Core Features & Use Cases

• Resource Naming: Establishes conventions for clear and intuitive URL structures.
• HTTP Status Codes & Error Handling: Ensures predictable and informative error responses.
• Pagination & Filtering: Implements efficient data retrieval strategies.
• Versioning: Guides on maintaining API evolution.
• GraphQL Schema Design: Promotes schema-first development and N+1 prevention.
• Use Case: When designing a new /users endpoint, this skill ensures proper resource naming, defines the expected request/response shapes, and specifies the correct HTTP status codes for various scenarios (e.g., 201 for creation, 400 for bad requests).

Quick Start

Use the designing-api-principles skill to design the API for a new /products resource, focusing on REST principles and defining its error cases.