skills.rest
Sheldon-92
Sheldon-92COMMUNITY
Explore all skills by this author →
GitHub

API Design

Review REST and GraphQL API endpoints for RESTful design and developer experience.

3|Updated Sep 27, 2025
Search Tags:#design#documentation#api#rest#graphql#review#endpoint
One-click install
npx skills add https://github.com/Sheldon-92/TAD --skill api-design-sheldon-92
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: API Design
Source: https://github.com/Sheldon-92/TAD/tree/main/.tad/skills/api-design
Command: npx skills add https://github.com/Sheldon-92/TAD --skill api-design-sheldon-92

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams verify RESTful API endpoints for consistent naming, correct HTTP method usage, clear error handling, and comprehensive developer-facing documentation, reducing integration risks and improving DX.

Core Features & Use Cases

  • Consistency checks: naming conventions, plural resources, and method semantics.
  • Documentation & UX: error formats, response schemas, and OpenAPI/Swagger artifacts.
  • Design decisions: versioning strategy, pagination, filtering, and GraphQL schema considerations.
  • Use Case: before shipping a new endpoint, run this Skill to generate a design review checklist and recommended changes.

Quick Start

Analyze the new or existing API surface to produce a design review report and suggested improvements.

Frequently Asked Questions about API Design

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

FAQPage Schema
How do I review my REST API endpoints for consistent naming and proper HTTP methods?▼

To review REST API endpoints, validate resource naming, pluralization, and HTTP method semantics. This generates a design review checklist with recommended changes to ensure consistent RESTful architecture and improve developer experience.

What is the best way to check if my API error handling and response schemas are well documented?▼

Checking API error handling involves reviewing error formats and response schemas against documentation standards. This validates that OpenAPI or Swagger artifacts are comprehensive, ensuring clear error responses for developer integration.

Does this API design review process work for GraphQL schema considerations and versioning decisions?▼

Yes, the API design review process applies to GraphQL schema considerations and versioning decisions. It evaluates versioning strategies, pagination, and filtering to ensure robust architecture across both REST and GraphQL implementations.

How do I generate a design review checklist before shipping a new API endpoint?▼

To generate a design review checklist before shipping, analyze the new API surface to evaluate authentication documentation and status codes. This produces a report of suggested improvements for robust RESTful design and better developer experience.

When do I need to refactor my API surface for better developer experience?▼

You need to refactor your API surface when consistency checks reveal improper HTTP method usage or unclear error handling. Refactoring addresses these design flaws to reduce integration risks and align endpoints with RESTful standards.

Related Skills

Explore More Software Engineering Skills→
VeradelaCruzVeradelaCruz

api-design

Define API requirements and generate OpenAPI or GraphQL schemas.

Community
Intermediate
Adelie-SquadAdelie-Squad
17

api-developer

Design API contracts and generate OpenAPI 3.0 documentation.

Official
Advanced
willdadywilldady
63

API Response Conventions

Enforce JSON error and message keys for API response schemas.

Community
Basic
JasonLoJasonLo

ss-validate-skills

Validate Claude Code skills for frontmatter, naming, and structural rules.

Community
Intermediate