skills.rest
NovusAevum
NovusAevumCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Guide REST and GraphQL API design with resource-oriented patterns and versioning strategies.

1|Updated Nov 10, 2025
Search Tags:#api design#microservices#graphql#api development#software architecture#rest api#api standards
One-click install
npx skills add https://github.com/NovusAevum/dev-agents-orchestration --skill api-design-principles-novusaevum
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/NovusAevum/dev-agents-orchestration/tree/main/configs/claude-code/skills/api-design-principles
Command: npx skills add https://github.com/NovusAevum/dev-agents-orchestration --skill api-design-principles-novusaevum

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps developers and architects design robust, maintainable, and developer-friendly APIs (both REST and GraphQL), preventing common pitfalls and ensuring consistency, scalability, and ease of integration. It streamlines the process of establishing high-quality API standards.

Core Features & Use Cases

  • RESTful Design Patterns: Guides on resource-oriented architecture, correct HTTP method semantics, pagination, filtering, consistent error handling, and HATEOAS.
  • GraphQL Design Principles: Focuses on schema-first development, efficient resolver design, DataLoader for N+1 problem prevention, and strongly typed schemas.
  • API Versioning Strategies: Covers best practices for URL, header, and query parameter versioning to manage API evolution and breaking changes gracefully.
  • Use Case: When starting a new microservice or refactoring an existing one, use this skill to ensure your API adheres to industry best practices from day one, avoiding costly refactoring later and making it easy for other teams to integrate.

Quick Start

Design a REST API for a new e-commerce product catalog, including pagination, filtering, and consistent error handling.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
How do I design a REST API that follows best practices?▼

REST API design relies on resource-oriented architecture, correct HTTP method semantics, consistent pagination and filtering, proper error handling, and HATEOAS principles. This Skill guides you through each component to ensure scalability, maintainability, and ease of integration for other teams.

What's the difference between REST and GraphQL API design?▼

REST uses resource-oriented endpoints with HTTP verbs; GraphQL uses a strongly typed schema with efficient resolvers. Choose REST for simple, cacheable resources; GraphQL for complex, interconnected data. This Skill covers design principles and trade-offs for both paradigms.

How do I version an API without breaking existing integrations?▼

API versioning strategies include URL paths, HTTP headers, and query parameters. Each approach balances compatibility with evolution. This Skill covers best practices for managing breaking changes gracefully and maintaining backward compatibility across microservices.

Can I use these API design principles across multiple microservices?▼

Yes. This Skill helps standardize API design practices across teams and microservices, ensuring consistency and reducing integration friction. It addresses resource-oriented design, versioning, error handling, and documentation standards applicable to distributed architectures.

What should I avoid when designing GraphQL schemas?▼

Common GraphQL pitfalls include N+1 query problems, poorly structured resolvers, and loosely typed schemas. This Skill covers schema-first development, DataLoader patterns for performance, and strongly typed design to prevent these issues and ensure scalability.

How do I document APIs so developers can integrate easily?▼

Clear API documentation requires consistent error handling conventions, pagination specifications, and endpoint contracts. This Skill emphasizes developer-friendly documentation as part of principled API design, reducing integration time and support burden.

Related Skills

Explore More Software Engineering Skills→
vasilyu1983vasilyu1983
73

software-architecture-design

Design system-level software architectures including patterns, scalability, resilience, and ADR-driven decisions.

Community
Advanced
ramybarsoumramybarsoum

api-design

Design RESTful API contracts with endpoint specs, JSON Schema, and error codes.

Community
Intermediate
pdovhomiljapdovhomilja

Backend API

Design RESTful API endpoints with HTTP methods, versioning, and rate limiting.

Community
Basic
amanning3390amanning3390
13

api-builder

Generate OpenAPI 3.0 specs and scaffold REST and GraphQL APIs.

Community
Advanced