skills.rest
lugassawan
lugassawanCOMMUNITY
Explore all skills by this author →
GitHub

principle-api-design

Design evolvable API contracts with versioning, idempotency, pagination, and error modeling.

2|8|Updated Apr 20, 2026
Search Tags:#versioning#error handling#api design#idempotency#pagination#backward compatibility
One-click install
npx skills add https://github.com/lugassawan/swe-workbench --skill principle-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: principle-api-design
Source: https://github.com/lugassawan/swe-workbench/tree/main/skills/principle-api-design
Command: npx skills add https://github.com/lugassawan/swe-workbench --skill principle-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents API breakage and integration pain by enforcing contract-first thinking, stable versioning, safe retries, consistent errors, and long-term evolvability.

Core Features & Use Cases

  • Contract-first API design: defines resource modeling and error cases up front to reduce downstream ambiguity.
  • Production-grade API discipline: covers semantic versioning, deprecation windows, and backward/forward compatibility rules.
  • Reliability & usability patterns: specifies idempotency keys for non-idempotent operations, safe pagination strategies, and consistent error envelopes (including request correlation).
  • Architecture trade-off guidance: helps choose REST vs RPC vs event-driven approaches based on client ecosystem, latency, typing, streaming, and consistency needs.
  • Pragmatic guardrails: highlights red flags like unsafe HTTP semantics, version creep, schema leakage, and inconsistent error responses.

Quick Start

Ask the API-focused assistant to review your endpoint design and propose a versioning, idempotency, pagination, and error-shape plan that preserves backward compatibility.

Frequently Asked Questions about principle-api-design

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

FAQPage Schema
How do I design an API contract to ensure backward compatibility when adding new fields?▼

Designing evolvable API contracts requires contract-first discipline, applying semantic versioning and clear deprecation windows to ensure backward compatibility when adding fields or deprecating endpoints.

What is the best way to handle API pagination for large collections?▼

API pagination for large collections requires selecting offset versus cursor pagination with enforced caps, ensuring reliable data retrieval without degrading service performance during large dataset traversal.

How do idempotency keys work for safe POST request retries?▼

Idempotency keys for POST requests provide safe retry semantics by ensuring duplicate submissions do not create multiple resources, preventing accidental side effects during network timeouts.

How should I structure consistent API error envelopes and HTTP status codes?▼

Consistent API error envelopes require uniform error modeling with request_id correlation and correct HTTP status discipline, ensuring clients receive predictable error responses for robust integration handling.

When should I choose REST versus RPC versus event-driven API architecture?▼

Choosing REST versus RPC versus event-driven API architecture depends on your client ecosystem, latency requirements, typing, streaming needs, and consistency models to determine the optimal interface design.

What are common API design red flags regarding unsafe HTTP semantics and schema leakage?▼

Common API design red flags include unsafe HTTP semantics, version creep, schema leakage, and inconsistent error responses, which undermine long-term API evolvability and integration stability.

Related Skills

Explore More Software Engineering Skills→
arvindbattulaarvindbattula

api-contracts

Define stable API contracts for REST endpoints and TypeScript interfaces before implementation.

Community
Advanced
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
vladm3105vladm3105
16

contract-tester

Validate API contracts and detect breaking changes across OpenAPI/AsyncAPI specifications.

Community
Advanced
guilhermemarketingguilhermemarketing
59

nx-generate

Generate boilerplate code using Nx workspace generators.

Community
Advanced