skills.rest
miles990
miles990COMMUNITY
Explore all skills by this author →
GitHub

api-design

Provides design guidelines and best practices for RESTful, GraphQL and gRPC APIs.

20|5|Updated Jan 5, 2026
Search Tags:#design#versioning#api#openapi#rest#graphql#grpc
One-click install
npx skills add https://github.com/miles990/claude-software-skills --skill api-design-miles990
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/miles990/claude-software-skills/tree/main/software-design/api-design
Command: npx skills add https://github.com/miles990/claude-software-skills --skill api-design-miles990

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill provides comprehensive guidance and best practices for designing various types of APIs, ensuring consistency, scalability, and maintainability across your software architecture.

Core Features & Use Cases

  • Protocol Guidance: Covers RESTful, GraphQL, and gRPC design principles.
  • Best Practices: Details on resource naming, HTTP methods, status codes, pagination, filtering, and sorting.
  • Versioning & Security: Strategies for API versioning and essential security considerations.
  • Use Case: Design a new RESTful API for a user management system, ensuring clear endpoints, proper error handling, and secure authentication.

Quick Start

Use the api-design skill to generate an OpenAPI specification for a user resource.

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 RESTful API resource naming and HTTP status codes?▼

RESTful API design best practices include using plural nouns for resource naming, mapping HTTP methods to CRUD operations, and returning standard HTTP status codes for success and error handling.

How do I design an OpenAPI specification for a user management system?▼

To design an OpenAPI specification for a user management system, apply guidelines for resource naming, pagination, filtering, and security, then use provided OpenAPI templates to generate the schema.

How do I choose between REST, GraphQL, and gRPC for my API architecture?▼

Choosing between REST, GraphQL, and gRPC depends on your architectural needs; this Skill provides comparative design principles for all three protocols to ensure consistency, scalability, and maintainability.

What strategies should I use for API versioning and security?▼

API versioning strategies prevent breaking changes across architecture, while essential security best practices ensure proper authentication and data protection for your endpoints.

How do I implement pagination, filtering, and sorting in RESTful APIs?▼

Implement pagination, filtering, and sorting in RESTful APIs by following detailed best practices that ensure clear endpoint structures and scalable data retrieval for client applications.

Related Skills

Explore More Software Engineering Skills→
TonyQ-AITonyQ-AI
9

domain-modeling

Extract core business concepts, entity relationships, and domain rules from requirement specifications.

Community
Intermediate
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
trilwutrilwu
109

testing-apis

Identify and exploit API security weaknesses across REST and GraphQL endpoints.

Community
Advanced
aquariuscookaquariuscook

contract-testing

Automate consumer-driven contract testing for microservices using Pact and schema validation.

Community
Advanced