api-conventions

Standardize API design across REST, GraphQL, and CLI interfaces.

3|Updated Nov 19, 2025
One-click install
npx skills add https://github.com/meaganewaller/.dotfiles --skill api-conventions-meaganewaller
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-conventions
Source: https://github.com/meaganewaller/.dotfiles/tree/main/home/.claude/skills/common/api-conventions
Command: npx skills add https://github.com/meaganewaller/.dotfiles --skill api-conventions-meaganewaller

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides a comprehensive set of guidelines and best practices for designing, reviewing, and building well-structured APIs across various formats like REST, GraphQL, and CLIs.

Core Features & Use Cases

  • API Design Principles: Covers explicit over implicit, validation at the boundary, structured error responses, and backward compatibility.
  • Format-Specific Conventions: Details best practices for REST (HTTP methods, status codes, pagination), GraphQL (schema design, error handling, naming), CLI tools (arguments, output, exit codes), and Service Interfaces (method design, parameter objects).
  • Use Case: When designing a new user management API, consult this Skill to ensure consistent naming, proper error handling, and appropriate use of HTTP methods.

Quick Start

Review the core principles for designing clear, maintainable, and robust APIs.

Frequently Asked Questions about api-conventions

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

FAQPage Schema
What are the best practices for REST API design regarding HTTP methods and status codes?

REST API design best practices involve using explicit HTTP methods, standard status codes, and structured pagination. This framework ensures consistent resource interactions, clear error reporting, and robust backward compatibility across your service interfaces.

How do I handle error reporting and input validation in GraphQL schema design?

GraphQL error reporting requires validation at the boundary and structured error responses within the schema design. Following these mutation patterns and naming conventions ensures robust, maintainable APIs that communicate failures clearly to clients.

What conventions should I follow for CLI argument parsing and exit codes?

CLI argument parsing conventions standardize how command-line tools process inputs, format output, and return exit codes. Applying explicit design principles ensures your CLI interface remains predictable, maintainable, and robust across different execution environments.

How do I maintain backward compatibility when designing APIs across different interfaces?

Maintaining backward compatibility requires applying explicit design over implicit behavior and validating inputs at the boundary. This standardized framework ensures consistent API evolution across REST, GraphQL, and CLI interfaces without breaking existing client integrations.

Does this API design framework provide guidelines for service interface method design?

Yes, the API design framework provides specific conventions for service interface method design and parameter objects. It standardizes interactions across REST, GraphQL, and CLI formats to ensure your service boundaries remain robust and consistently structured.

What is the best way to structure pagination and mutation patterns in APIs?

The best way to structure pagination and mutation patterns is by following explicit design principles and standardized conventions. This framework details specific schema designs and mutation patterns to ensure consistency and robustness across REST and GraphQL APIs.