skills.rest
yusoofsh
yusoofshCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Apply REST and GraphQL principles to design and refactor APIs.

Updated Aug 27, 2026
Search Tags:#error handling#GraphQL#backend#REST#developer experience#API design#API versioning
One-click install
npx skills add https://github.com/yusoofsh/dotfiles --skill api-design-principles-yusoofsh
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/yusoofsh/dotfiles/tree/main/home/dot_claude/private_plugins/private_marketplaces/claude-code-workflows/plugins/backend-development/skills/api-design-principles
Command: npx skills add https://github.com/yusoofsh/dotfiles --skill api-design-principles-yusoofsh

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires fastapi, pydantic, ariadne, aiodataloader, requests, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This Skill provides a comprehensive guide to designing well-structured, developer-friendly REST and GraphQL APIs, preventing common pitfalls and ensuring long-term maintainability and scalability.

Core Features & Use Cases

  • RESTful Design: Master resource-oriented architecture, HTTP methods, and status codes for robust APIs.
  • GraphQL Schema Design: Learn schema-first development, type definitions, and efficient data fetching with resolvers.
  • Versioning & Error Handling: Implement effective API versioning strategies and consistent, informative error responses.
  • Use Case: Design a new public API for a mobile application, ensuring it's easy for third-party developers to integrate, handles errors gracefully, and supports future growth.

Quick Start

Use the api-design-principles skill to generate a FastAPI endpoint for listing users with pagination and filtering, following REST best practices.

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's easy for developers to integrate?▼

REST API design relies on resource-oriented architecture, proper HTTP method semantics, and clear status codes. Use consistent naming conventions, meaningful URLs, pagination for large datasets, and versioning strategies to ensure your API scales and remains maintainable as requirements evolve.

What's the best way to handle errors in REST and GraphQL APIs?▼

Implement consistent, informative error responses with meaningful status codes and error details. In REST, use appropriate HTTP status codes; in GraphQL, structure errors with context about what failed. Both approaches should guide developers toward fixing integration issues quickly.

How do I implement API versioning without breaking existing integrations?▼

API versioning strategies include URL paths, headers, or query parameters to signal schema changes. Plan deprecation cycles, communicate changes clearly to developers, and maintain backward compatibility during transitions to prevent third-party integrations from breaking unexpectedly.

Can I use REST and GraphQL together, or should I choose one?▼

REST and GraphQL address different API design patterns. REST is resource-oriented and stateless; GraphQL enables clients to request exactly the fields they need, reducing over-fetching. Choose based on your client needs, developer experience priorities, and team expertise.

How do I add pagination and filtering to API endpoints?▼

Pagination uses limit and offset or cursor-based parameters to return data in chunks. Filtering lets clients query specific subsets using query parameters. Both improve performance, reduce payload size, and enhance developer experience by enabling efficient data retrieval.

What makes a GraphQL schema developer-friendly?▼

Schema-first development defines clear type definitions, meaningful field names, and predictable resolver behavior before implementation. Consistent naming, comprehensive documentation, and efficient data fetching patterns help developers understand the API surface and integrate faster.

Related Skills

Explore More Software Engineering Skills→
greyhaven-aigreyhaven-ai
29

Data Validation Skill

Validate API payloads and database inputs using Pydantic v2 models.

Community
Intermediate
HieubkavHieubkav

api-documentation-writer

Generates API documentation with OpenAPI specs, endpoint descriptions, and code examples.

Community
Advanced
AbdullahMalik17AbdullahMalik17
8

fastapi-mastery

Develop RESTful APIs with FastAPI, Pydantic validation, and authentication.

Community
Advanced
iludeilude
8

api-design-patterns

Design REST and GraphQL APIs with language-agnostic patterns for routes, schemas, and specs.

Community
Advanced