skills.rest
EanLee
EanLeeCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Guide REST and GraphQL API design with patterns for schemas, pagination, and versioning.

Updated Dec 16, 2025
Search Tags:#schema design#api design#rest#developer experience#graphql#api best practices
One-click install
npx skills add https://github.com/EanLee/article-write --skill api-design-principles-eanlee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/EanLee/article-write/tree/main/.github/skills/api-design-principles
Command: npx skills add https://github.com/EanLee/article-write --skill api-design-principles-eanlee

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps developers design, build, and maintain intuitive, scalable, and maintainable APIs by providing comprehensive guidance on REST and GraphQL design principles.

Core Features & Use Cases

  • API Design Standards: Establish best practices for RESTful resource design, HTTP methods, status codes, and versioning.
  • GraphQL Schema Design: Guide the creation of robust GraphQL schemas, including types, queries, mutations, and pagination.
  • Use Case: A team is starting a new microservice and needs to define its API contract. They use this Skill to ensure their REST API adheres to established patterns for resource naming, error handling, and pagination, making it predictable for consumers.

Quick Start

Use the api-design-principles skill to generate a checklist for reviewing a new REST API specification.

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 REST API resource naming and HTTP semantics?▼

REST API design best practices involve resource-oriented naming, correct HTTP method usage, and standard status codes. Following these principles ensures your RESTful interfaces are intuitive, scalable, and maintainable for consumers.

How do I design a GraphQL schema with queries, mutations, and pagination?▼

Designing a GraphQL schema requires defining robust types, queries, and mutations. This Skill guides the creation of GraphQL schemas, including patterns for pagination, to build maintainable and scalable API contracts.

What is the best way to handle errors and pagination in API design?▼

The best way to handle API errors and pagination is by applying established design patterns for both REST and GraphQL. This Skill provides comprehensive guidance on structuring error responses and implementing scalable pagination strategies.

How do I create a checklist for reviewing a new REST API specification?▼

You can generate a checklist for reviewing a REST API specification by applying the resource-oriented design principles and HTTP semantics provided by this Skill. This ensures your microservice API contract adheres to established patterns for error handling and versioning.

REST vs GraphQL: which API design paradigm should I choose for my microservice?▼

Choosing between REST and GraphQL depends on your data fetching needs and schema complexity. This Skill outlines design principles for both paradigms, helping you decide between resource-oriented REST interfaces or flexible GraphQL schemas.

Related Skills

Explore More Software Engineering Skills→
Prathmesh2000Prathmesh2000
1

contract-designer

Define service contracts with OpenAPI and AsyncAPI before implementation.

Community
Advanced
icartshicartsh
4

api-designer

Design RESTful and GraphQL APIs with OpenAPI 3.0 specifications.

Community
Advanced
alekspetrovalekspetrov
196

backend-endpoint

Generate REST or GraphQL API endpoints with validation, error handling, and tests.

Community
Intermediate
martinffxmartinffx
39

atelier-typescript-drizzle-orm

Define Drizzle ORM schemas and generate type-safe TypeScript queries.

Community
Advanced