skills.rest
eous
eousCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Provide structured REST and GraphQL patterns for API design and auditing.

Updated Dec 4, 2025
Search Tags:#versioning#documentation#openapi#rest#graphql#api-design
One-click install
npx skills add https://github.com/eous/dotclaude --skill api-design-eous
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/eous/dotclaude/tree/main/skills/api-design
Command: npx skills add https://github.com/eous/dotclaude --skill api-design-eous

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

APIs often suffer from inconsistency, vague conventions, and poor documentation, making integration slower and error-prone. This guide provides a cohesive set of REST and GraphQL design patterns, conventions, and documentation standards to align teams and accelerate API delivery.

Core Features & Use Cases

  • REST Fundamentals: standard resource naming, HTTP methods, and status codes to ensure predictable interactions.
  • GraphQL Patterns: schema design, queries, mutations, and pagination to optimize client flexibility.
  • Documentation & Governance: OpenAPI/OpenAPI spec alignment, versioning strategies, and consistent error handling.
  • Use Case: Design and audit new APIs, refactor existing APIs for consistency, and document APIs for developer adoption.

Quick Start

Audit your current API contracts against REST/GraphQL best practices and start applying OpenAPI specifications and consistent naming today.

Frequently Asked Questions about api-design

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 status codes?▼

REST API design best practices involve standard resource naming, proper HTTP methods, and correct status codes to ensure predictable client interactions and consistent response formats across endpoints.

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

GraphQL schema design requires structured patterns for queries, mutations, and pagination to optimize client flexibility while maintaining consistent conventions across the full API lifecycle.

How do I align my API documentation with OpenAPI specifications?▼

Align API documentation with OpenAPI specifications by applying standardized versioning strategies, consistent error handling, and structured response formats to accelerate developer adoption and integration.

Can I use this API design guide to audit existing API contracts for consistency?▼

Yes, you can audit existing API contracts against REST and GraphQL best practices to identify inconsistencies in endpoint naming, error handling, and secure design to refactor APIs effectively.

REST vs GraphQL: which API design approach should I choose for my project?▼

Choosing between REST and GraphQL depends on your needs: REST provides standard resource naming and predictable interactions, while GraphQL offers schema design flexibility for optimized client queries.

Related Skills

Explore More Software Engineering Skills→
franroafranroa

API Designer

Design REST and GraphQL APIs with OpenAPI 3.1 specifications.

Community
Advanced
icartshicartsh
4

api-designer

Design RESTful and GraphQL APIs with OpenAPI 3.0 specifications.

Community
Advanced
Nick777-PixelNick777-Pixel

response-compliance

Automate OpenResponses compliance testing for the Response API.

Community
Intermediate
vieriusorinvieriusorin

db-migrate

Create and execute PostgreSQL schema migrations with Drizzle ORM.

Community
Intermediate