skills.rest
DuveSalo
DuveSaloCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Guide RESTful and GraphQL API design with patterns and best practices.

Updated Aug 27, 2026
Search Tags:#api design#rest#developer experience#graphql#software architecture#api principles
One-click install
npx skills add https://github.com/DuveSalo/app --skill api-design-principles-duvesalo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/DuveSalo/app/tree/main/.claude/skills/api-design-principles
Command: npx skills add https://github.com/DuveSalo/app --skill api-design-principles-duvesalo

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps you design, review, and standardize intuitive, scalable, and maintainable APIs by providing comprehensive principles 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, filtering, and HATEOAS.
  • GraphQL Design: Understand schema-first development, query/mutation structure, and patterns like Relay-style pagination and DataLoader for efficiency.
  • Best Practices & Pitfalls: Avoid common mistakes and implement industry-standard best practices for API versioning, error handling, security, and performance.
  • Use Case: When designing a new microservice API, use this Skill to ensure your REST endpoints are well-structured, your GraphQL schema is robust, and your error handling is consistent across the board.

Quick Start

Review the best practices for designing REST APIs by reading the 'references/rest-best-practices.md' document.

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 designing RESTful APIs with proper HTTP semantics?▼

RESTful API design best practices involve resource-oriented architecture, correct HTTP method semantics, and standard patterns for pagination, filtering, and HATEOAS to ensure endpoints are intuitive and maintainable.

How do I prevent the N+1 problem in GraphQL using DataLoaders?▼

To prevent the N+1 problem in GraphQL, implement DataLoaders to batch and cache database requests. This pattern groups multiple queries into a single request, optimizing data fetching efficiency and performance.

Should I use REST or GraphQL for my new microservice API architecture?▼

Choosing between REST and GraphQL depends on your microservice API needs. Use REST for resource-oriented design and caching, or GraphQL for schema-first development and flexible client-driven data fetching.

How do I implement consistent API error handling and versioning?▼

Consistent API error handling and versioning require industry-standard best practices. This involves structuring error responses uniformly and applying clear versioning strategies to avoid breaking existing clients.

What is schema-first development in GraphQL and how does it structure queries?▼

Schema-first development in GraphQL defines your API contract before writing code. It structures queries and mutations through a strongly typed schema, ensuring robust and predictable client interactions.

Related Skills

Explore More Software Engineering Skills→
sunLeeesunLeee

doc-spec

Transform PRDs into technical specifications with API definitions, data models, and sequence diagrams.

Community
Advanced
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
vertivolatamvertivolatam
1

API Gateway & Rate Limiting

Implement API Gateways with Kong and Nginx rate limiting strategies.

Official
Advanced
tech-leads-clubtech-leads-club
5.0k

nx-generate

Generate libraries and applications using Nx generators in a monorepo.

Official
Intermediate