skills.rest
bigdegenenergy
bigdegenenergyCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design REST and GraphQL APIs with standardized endpoints, responses, and error handling.

Updated Aug 23, 2026
Search Tags:#rest#graphql#endpoints#api-design#status-codes#http-methods
One-click install
npx skills add https://github.com/bigdegenenergy/ai-dev-toolkit --skill api-design-bigdegenenergy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/bigdegenenergy/ai-dev-toolkit/tree/main/.claude/skills/api-design
Command: npx skills add https://github.com/bigdegenenergy/ai-dev-toolkit --skill api-design-bigdegenenergy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Standardizing API design lifts consistency and reduces integration friction by providing clear conventions for endpoints, responses, and error handling across REST and GraphQL.

Core Features & Use Cases

  • REST Design Principles: Naming conventions, HTTP methods semantics, status codes, and response shapes to create predictable APIs.
  • GraphQL Best Practices: Schema clarity, query/mutation patterns, type design, and versioning guidance for scalable data access.
  • Use Case: When drafting a new service, apply these patterns to define resources, errors, and client contracts before implementation.

Quick Start

Draft a REST or GraphQL API blueprint for a new user service.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design robust RESTful API endpoints and standardize HTTP responses?▼

To design robust RESTful APIs, apply clear naming conventions, correct HTTP method semantics, and standardized status codes to create predictable endpoints and structured response formats. This standardization reduces integration friction across backend services.

What are the best practices for GraphQL schema design and query patterns?▼

GraphQL schema design best practices involve ensuring schema clarity, defining precise type designs, and structuring scalable query and mutation patterns. Following these patterns provides versioning guidance and standardized data access for clients.

How do I standardize API error handling and client contracts across backend teams?▼

Standardizing API error handling requires applying structured response formats and consistent status codes across REST and GraphQL APIs. Defining these client contracts before implementation ensures consistent service design and reduces integration friction.

When should I choose REST versus GraphQL for a new service blueprint?▼

Choose REST for predictable resource-based endpoints using HTTP methods, or GraphQL for scalable data access with flexible query patterns. Both require standardized schemas and error handling to establish clear client contracts for backend teams.

Can I use this approach for API versioning and security design?▼

Yes, these API design principles apply directly to service design work including API versioning and security. By standardizing endpoints, response shapes, and schemas, you establish consistent client contracts and secure data access patterns.

Related Skills

Explore More Software Engineering Skills→
00PrabalK0000PrabalK00
1

api-contract-builder

Define and document API contracts with OpenAPI schemas before implementation.

Community
Intermediate
AI-Foundry-CoreAI-Foundry-Core
4

openapi-spec-generation

Generate OpenAPI 3.1 specifications from code and design artifacts.

Official
Advanced
jhlee0409jhlee0409
4

openapi-parser

Parse OpenAPI 3.x and Swagger 2.0 specs into structured endpoint catalogs.

Community
Advanced
ZurybrZurybr

kv-store-grpc

Implement gRPC key-value store services in Python with protocol buffers.

Community
Intermediate