api-design

Design and review HTTP, gRPC, and library APIs with contract-first workflows.

1|Updated Mar 22, 2026

Search Tags:#backward-compatibility #error-handling #grpc #contract-first #api-design #rest-api #api-versioning

One-click install

npx skills add https://github.com/tswr/engineering-mastery-plugin --skill api-design-tswr

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/tswr/engineering-mastery-plugin/tree/main/skills/api-design
Command: npx skills add https://github.com/tswr/engineering-mastery-plugin --skill api-design-tswr

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Poorly designed APIs create significant maintenance burden, break consumer trust with unexpected breaking changes, and lead to inconsistent error handling, naming, and pagination that frustrate developers and cause integration failures. This Skill eliminates those issues by providing language-agnostic, industry-vetted principles for building APIs that are intuitive, stable, and easy to consume.

Core Features & Use Cases

Contract-First Design: Define OpenAPI, protobuf, or GraphQL schemas before writing implementation to avoid leaking internal details and ensure the API matches consumer needs.
Backward Compatibility & Versioning: Safely evolve APIs without breaking existing consumers, with clear deprecation policies and automated compatibility checks.
Standardized Error Handling & Pagination: Implement RFC 7807 Problem Details for consistent, actionable errors, and cursor-based pagination for stable performance with large or changing datasets.
Language-Specific Idioms: Reference implementations for C++, Java, Python, and Rust that align with each ecosystem's best practices for routing, validation, and error handling.
Use Case: When building a new public REST API for user management, use this Skill to define the contract first, enforce consistent /users resource naming, implement RFC 7807 error responses, and add idempotency keys for order creation endpoints to prevent duplicate charges.

Quick Start

Use the api-design skill to review your existing /products API endpoint for backward compatibility issues, incorrect HTTP status code usage, and missing pagination support for large product catalogs.

Frequently Asked Questions about api-design

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

FAQPage Schema

How do I design a REST API that doesn't break existing consumers?▼

Standardize REST API error handling by implementing RFC 7807 Problem Details. This provides consistent, actionable error responses across your endpoints, eliminating inconsistent error formats that frustrate developers and cause integration failures.

What is the best way to implement pagination for large API datasets?▼

Yes, you can use contract-first design for gRPC APIs by defining protobuf schemas before writing implementation. This prevents leaking internal details and aligns the gRPC service strictly with consumer needs and industry-vetted principles.

How do I add idempotency to an API order creation endpoint?▼

Add idempotency to an API order creation endpoint by requiring idempotency keys in the request headers. This guarantees that retried requests do not produce duplicate charges, maintaining consumer trust and data integrity.

Does this API design approach support Python and Rust ecosystems?▼

Yes, this API design approach supports Python and Rust ecosystems. It provides language-specific reference implementations that align with each platform's best practices for routing, validation, and error handling.