api-design-principles

Guide REST and GraphQL API design with resource-oriented architecture and error handling.

Updated Oct 16, 2025

Search Tags:#best practices #api design #rest #developer experience #graphql #api standards

Ready to run

npx skills add https://github.com/Axeloooo/BridgeMart --skill api-design-principles-axeloooo

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill provides comprehensive guidance on designing and implementing robust, developer-friendly REST and GraphQL APIs, ensuring scalability and maintainability.

Core Features & Use Cases

RESTful Design: Learn resource-oriented architecture, HTTP method semantics, and best practices for collections, pagination, and error handling.
GraphQL Design: Understand schema-first development, query/mutation patterns, and N+1 problem prevention with DataLoaders.
Use Case: When designing a new microservice API, use this Skill to ensure adherence to industry best practices for both REST and GraphQL endpoints, leading to a more intuitive developer experience.

Quick Start

Consult the API design checklist to ensure all critical aspects of a new API are considered before implementation.

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 design regarding pagination and error handling?▼

REST API design best practices include using resource-oriented architecture, proper HTTP method semantics, and standardized error handling. For collections, implement consistent pagination and filtering patterns to ensure your API remains intuitive and scalable for consumers.

How do I prevent the N+1 problem in GraphQL schema design?▼

To prevent the N+1 problem in GraphQL schema design, implement DataLoaders for batch fetching. Adopt a schema-first development approach and apply structured query and mutation patterns to ensure your GraphQL API maintains optimal performance and maintainability.

How do I design a scalable and maintainable API for a new microservice?▼

Designing a scalable, maintainable API for a new microservice requires adhering to industry standards for resource-oriented architecture and HTTP method semantics. Consult an API design checklist to ensure all critical aspects are considered before implementation begins.

What is the difference between REST and GraphQL API design patterns for developer experience?▼

REST focuses on resource-oriented architecture and HTTP method semantics for collections, while GraphQL emphasizes schema-first development, mutation patterns, and N+1 prevention. Both aim to improve developer experience by establishing intuitive, standardized API endpoints.

Do I need to follow specific API standards when establishing architecture for my service?▼

Establishing API standards requires following proven principles for resource-oriented architecture, HTTP method semantics, and schema design. Applying these standards ensures your service endpoints are intuitive, scalable, and maintainable for long-term developer use.