api-design-principles

Design RESTful and GraphQL APIs with patterns for pagination, error handling, and DataLoader.

1|Updated Feb 24, 2026

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

Ready to run

npx skills add https://github.com/xurenlu/marstaff --skill api-design-principles-xurenlu

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps you design and build intuitive, scalable, and maintainable APIs by providing best practices and patterns for both REST and GraphQL.

Core Features & Use Cases

RESTful Design: Learn resource-oriented architecture, HTTP method semantics, and common patterns like pagination and error handling.
GraphQL Design: Understand schema-first development, query/mutation structure, and techniques like DataLoader for efficiency.
Use Case: When designing a new microservice API, use this Skill to ensure your endpoints are well-structured, your data fetching is efficient, and your error responses are consistent and informative.

Quick Start

Review the RESTful design principles for building resource-oriented endpoints.

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 RESTful API design and resource-oriented architecture?▼

RESTful API design best practices involve structuring endpoints around resources, using correct HTTP method semantics, and implementing standard patterns for pagination, filtering, and error handling to build intuitive and scalable interfaces.

How do I handle pagination, filtering, and error handling in a scalable API?▼

To handle pagination, filtering, and error handling in a scalable API, apply established patterns for resource slicing and return consistent, informative error responses to ensure the interface remains maintainable and intuitive for consumers.

What is the best way to design a GraphQL schema and implement DataLoader for efficiency?▼

The best way to design a GraphQL schema is through schema-first development, structuring queries and mutations logically, and implementing DataLoader to batch requests and solve the N+1 problem for efficient data fetching.

What versioning strategies should I use when building microservice APIs?▼

API versioning strategies for microservices should balance backward compatibility with maintainability, allowing you to iterate on resource-oriented architecture and HTTP semantics without breaking existing clients.

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

Choose GraphQL over REST when you need schema-first development and efficient, client-driven data fetching, whereas REST is often preferred for resource-oriented architecture and standard HTTP method semantics.