skills.rest
xabierlameiro
xabierlameiroCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

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

Updated Mar 8, 2026
Search Tags:#api design#rest#developer experience#graphql#api specification#api best practices
One-click install
npx skills add https://github.com/xabierlameiro/price-tracker --skill api-design-principles-xabierlameiro
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/xabierlameiro/price-tracker/tree/main/.agents/skills/api-design-principles
Command: npx skills add https://github.com/xabierlameiro/price-tracker --skill api-design-principles-xabierlameiro

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps developers design, review, and standardize intuitive, scalable, and maintainable REST and GraphQL APIs, reducing development friction and improving developer experience.

Core Features & Use Cases

  • RESTful Principles: Learn resource-oriented design, HTTP method semantics, and best practices for endpoints.
  • GraphQL Principles: Understand schema-first development, query structure, and efficient data fetching.
  • Patterns & Pitfalls: Explore practical patterns for pagination, filtering, error handling, versioning, and common mistakes to avoid.
  • Use Case: When designing a new microservice API, use this Skill to ensure adherence to RESTful principles, leading to a more consistent and predictable API for consumers.

Quick Start

Use the api-design-principles skill to review the provided API specification against RESTful best practices.

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 design and resource-oriented architecture?▼

REST API design best practices involve resource-oriented architecture, correct HTTP method semantics, and consistent endpoint naming. This ensures your API is intuitive, scalable, and maintainable for developers consuming your service.

How do I design a GraphQL schema for efficient data fetching?▼

Designing a GraphQL schema requires a schema-first development approach to structure queries and enable efficient data fetching. This method minimizes over-fetching and optimizes payloads for clients requesting complex data relationships.

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

Choosing REST or GraphQL depends on your data fetching needs; REST uses resource-oriented architecture for predictable endpoints, while GraphQL offers schema-first query flexibility. Evaluate your client requirements for efficient data retrieval.

How do I handle pagination, filtering, and error handling in API specifications?▼

API pagination, filtering, and error handling require implementing standardized patterns across your endpoints. Consistent versioning and structured error responses improve developer experience and reduce integration friction.

What are common API design pitfalls and mistakes to avoid?▼

Common API design pitfalls include misusing HTTP semantics, inconsistent resource naming, and poor error handling. Reviewing your API specification against established principles helps avoid these mistakes and ensures a maintainable interface.

Related Skills

Explore More Software Engineering Skills→
Renzo-TognellaRenzo-Tognella

implementing-api-schema-validation-security

Implement API schema validation with OpenAPI and JSON Schema to prevent injection and mass assignment.

Community
Advanced
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
sobirdsobird
3

verifier-api

Validate Claude Code API endpoints and HTTP behavior with curl.

Community
Intermediate
seifsheikhelarabseifsheikhelarab

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from code and design artifacts.

Community
Advanced