api-design

Design RESTful and GraphQL APIs with OpenAPI documentation and versioning.

8|2|Updated Jan 15, 2026
One-click install
npx skills add https://github.com/bradtaylorsf/alphaagent-team --skill api-design-bradtaylorsf
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/bradtaylorsf/alphaagent-team/tree/main/plugins/aai-dev-backend/skills/api-design
Command: npx skills add https://github.com/bradtaylorsf/alphaagent-team --skill api-design-bradtaylorsf

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides best practices and patterns for designing consistent, maintainable, and developer-friendly RESTful and GraphQL APIs, reducing ambiguity and improving developer experience.

Core Features & Use Cases

  • REST API Design: Covers URL structure, HTTP methods, status codes, request/response formats, query parameters, and versioning strategies.
  • GraphQL Design: Includes schema design, Relay-style pagination, and error handling patterns.
  • Documentation Standards: Demonstrates OpenAPI (Swagger) for API documentation.
  • Performance Considerations: Outlines rate limiting and caching strategies.
  • Use Case: When starting a new backend service, use this Skill to quickly establish a clear and industry-standard API design for both REST and GraphQL endpoints.

Quick Start

Use the api-design skill to generate a standard REST API response envelope structure.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the best way to structure REST API URLs and handle HTTP methods?

The best way to structure REST API URLs and handle HTTP methods is by following standard patterns for resource naming, request formats, and response codes. This ensures consistent and maintainable backend services.

How do I design a GraphQL schema with pagination and error handling?

To design a GraphQL schema with pagination and error handling, implement standard patterns like Relay-style pagination and structured error responses. This approach maintains consistency across your query endpoints.

How do I document API endpoints using OpenAPI?

You document API endpoints using OpenAPI by generating standard specifications that describe your URL structures, request formats, and response codes. This creates clear, developer-friendly documentation.

What strategies should I use for API versioning, rate limiting, and caching?

For API versioning, rate limiting, and caching, apply established performance patterns that manage traffic and maintain backward compatibility. This reduces ambiguity and improves the overall developer experience.

When do I need standard patterns for REST and GraphQL API design?

You need standard patterns for REST and GraphQL API design when starting a new backend service. Applying these patterns early establishes a clear, industry-standard structure for your endpoints.

Can I use standard API patterns for both REST and GraphQL endpoints?

Yes, you can use standard API patterns for both REST and GraphQL endpoints. Comprehensive design guidelines cover URL structure, query parameters, and schema design, ensuring both architectures remain maintainable.