skills.rest
DevelopersGlobal
DevelopersGlobalOFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-design

Design stable, versioned, self-documenting APIs using Hyrum's Law.

65|10|Updated May 1, 2026
Search Tags:#versioning#api design#self-documentation#api stability#hyrum's law
One-click install
npx skills add https://github.com/DevelopersGlobal/ai-agent-skills --skill api-design-developersglobal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/DevelopersGlobal/ai-agent-skills/tree/main/skills/api-design
Command: npx skills add https://github.com/DevelopersGlobal/ai-agent-skills --skill api-design-developersglobal

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill helps design APIs that are stable, self-documenting, and difficult to misuse, ensuring reliable and maintainable software contracts.

Core Features & Use Cases

  • Stable API Design: Enforces API stability and adherence to Hyrum's Law.
  • Versioning Strategy: Guides the creation of a versioning strategy for APIs.
  • Self-Documentation: Encourages comprehensive API documentation.
  • Use Case: Ideal for designing and maintaining APIs for any software project, especially for public-facing or widely-used internal APIs.

Quick Start

To begin designing a stable API, run the skill and follow the outlined steps for interface design, applying Hyrum's Law, versioning strategy, and self-documentation.

Frequently Asked Questions about api-design

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

FAQPage Schema
What is Hyrum's Law in API design and why does it matter?▼

Hyrum's Law in API design states that all observable behaviors become implicit dependencies for users. Accounting for these hidden contracts ensures API stability and prevents breaking changes during versioning and updates.

How do I design a versioning strategy for a public API?▼

Design a public API versioning strategy by enforcing interface stability and applying Hyrum's Law. This involves structured steps for interface design, versioning strategy formulation, and comprehensive self-documentation to maintain reliable software contracts.

What is the best way to make an API self-documenting and difficult to misuse?▼

The best way to make an API self-documenting is to enforce disciplined API design principles alongside comprehensive documentation practices. This creates robust, stable interfaces that are inherently difficult for consumers to misuse.

Can I use this API design approach for internal library endpoints?▼

Yes, this API design approach applies to both public API endpoints and internal library APIs. It enforces stability and self-documentation for any software project, ensuring maintainable contracts for widely-used internal interfaces.

When do I need to apply formal API versioning and stability principles?▼

You need formal API versioning and stability principles when designing public-facing endpoints or widely-used internal library APIs. Applying these disciplined design practices early ensures reliable software contracts and prevents breaking consumer dependencies.

Related Skills

Explore More Software Engineering Skills→
dtsongdtsong
1

intake-skill

Transform natural language project descriptions into structured engagement briefs.

Community
Advanced
jhlee0409jhlee0409
4

openapi-parser

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

Community
Advanced
camilooscargbaptistacamilooscargbaptista
7

api-gateway-patterns

Design API gateway architectures with rate limiting, authentication, routing, and circuit breaking.

Community
Intermediate
devs6186devs6186

ai-first-engineering

Design and enforce AI-first engineering practices across planning, reviews, and testing.

Community
Advanced