skills.rest
wpank
wpankCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Provides RESTful and GraphQL API design principles including resource modeling, HTTP semantics, pagination, error handling, versioning, schema design, REST vs GraphQL decision frameworks, FastAPI examples, and pre-implementation checklists.

11|4|Updated Feb 9, 2026
Search Tags:#api design#rest#graphql#backend development#api best practices#http semantics
One-click install
npx skills add https://github.com/wpank/ai --skill api-design-principles-wpank
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/wpank/ai/tree/main/skills/backend/api-design-principles
Command: npx skills add https://github.com/wpank/ai --skill api-design-principles-wpank

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill provides comprehensive guidance on designing robust, scalable, and developer-friendly REST and GraphQL APIs, addressing common pitfalls and establishing best practices.

Core Features & Use Cases

  • RESTful Design: Covers resource naming, HTTP methods, status codes, pagination, filtering, and error handling.
  • GraphQL Design: Includes schema patterns, DataLoader for performance, and query protection.
  • Use Case: When starting a new microservice that will expose data via an API, use this Skill to ensure the API design adheres to industry standards for usability and maintainability.

Quick Start

Consult the API Design Principles skill for guidance on designing a new REST API.

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 resource modeling and HTTP semantics?▼

RESTful API design best practices involve standardizing resource naming, correctly applying HTTP methods and status codes, and implementing consistent pagination, filtering, and error handling to ensure backend service maintainability.

How do I decide between using REST vs GraphQL for my new microservice?▼

Deciding between REST and GraphQL requires evaluating a decision framework based on data fetching needs. REST provides standardized HTTP semantics, while GraphQL offers flexible schema patterns and DataLoader for query performance optimization.

How to design a GraphQL schema with query protection and DataLoader?▼

Designing a GraphQL schema involves defining type structures using established patterns, implementing DataLoader to batch requests for performance optimization, and applying query protection mechanisms to prevent malicious over-fetching.

Can I use these API design principles with FastAPI for backend development?▼

Yes, you can apply these API design principles with FastAPI. The guidance includes implementation examples in FastAPI to help developers build robust, scalable, and developer-friendly RESTful backend services.

What should be included in a pre-implementation checklist for API versioning and error handling?▼

A pre-implementation checklist for API versioning and error handling should verify that resource modeling, HTTP semantics, pagination strategies, and standardized error formats are fully defined to avoid common design pitfalls before coding starts.

Related Skills

Explore More Software Engineering Skills→
adelabdelgawadadelabdelgawad

api-integration

Proxy Next.js API routes to FastAPI with cookie forwarding and typed clients.

Community
Advanced
nashirabbashnashirabbash

api-documentation

Generate OpenAPI specs and interactive documentation for REST and GraphQL APIs.

Community
Intermediate
boomNDSboomNDS

api-security-best-practices

Apply authentication, authorization, input validation, and rate limiting patterns to secure APIs.

Community
Advanced
elmochilyaselmochilyas
8

laravel-api-grpc

Implement gRPC in Laravel 13 microservices using Protocol Buffers and RoadRunner.

Community
Advanced