Skip to content
Skills Library
Programming · Planning

api-design

/api-design

Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.

Repository
AI-SKILLS ↗
Licence
MIT
Last repository change
05.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.

Original author description

Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.

How it works

  1. Method
  2. Litmus tests
  3. Boundaries
Original SKILL.md headings · 48 lines, 361 words
SKILL.md preview
---
name: api-design
description: Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.
---

# API design

An API is a promise you keep for years. Design for the caller you cannot
see, then keep the promise boring.

## Method

1. **Start from the caller's sentence.** Write the code or request the
   caller *wants* to make, before any implementation exists: `POST
   /notebooks/{id}/share` or `client.notebooks.share(id)`. If the ideal call
   is awkward to say, the design is wrong at the root.
2. **Name by domain, shape by convention.** Nouns for resources, verbs for
   actions that are not CRUD. Same word for the same concept everywhere:
   an API where "document", "file", and "source" mean one thing teaches
   distrust of every name.
3. **Make the common case one call** with obvious defaults, and the rare
   case possible with explicit options. Never make every caller pay a
   configuration tax for flexibility one caller needs.
4. **Errors are API.** Every failure a caller can cause gets a distinct,
   documented, stable error with: what went wrong, on which input, and what
   to do. A caller should distinguish "you sent garbage" (4xx / typed
   error), "we broke" (5xx), and "try later" without parsing prose.
5. **Design for the invalid states not to exist.** Required pairs travel in
   one object; mutually exclusive options are one enum, not three booleans;
   ids that must belong together are validated together. If misuse compiles
   or returns 200, it will ship.
6. **Version from day one, break never.** Additive change is free (new
   optional field, new endpoint). Breaking change (rename, meaning change,
   removal) needs a version and a deprecation window. Before renaming a
   field, remember: someone wrote a cron job against it.
7. **Paginate every list, bound every input.** Unbounded responses and
   unbounded request sizes are outages on a delay.

## Litmus tests

- Can a caller learn the API from one example call plus type/shape
  signatures, without reading your source?
- Is every operation idempotent that safely can be, and documented where it
  cannot?
- Could you delete the docs page for defaults and have callers unaffected?

## Boundaries

Consistency with the existing API's conventions beats abstract elegance:
one surprising-but-uniform surface is kinder than a half-migrated ideal.
Note the inconsistency you would fix, then follow the house style.

Versions

RepositoryScoreLicence
This page · Amey-Thakur/AI-SKILLS100MIT
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

Database snapshot: 13.11.2026 · package version 01af97307cc9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-and-interface-design
    Design seams, APIs, config keys and schemas that are deep, hard to misuse, and safe to roll out and back. Use when adding or changing a contract.
  • 100api
    RESTful API design patterns and best practices. Use when creating endpoints, designing APIs, or implementing routes.
  • 100http-api-guidelines
    This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards.
  • 100api-design-rest
    Rules for designing and implementing HTTP/REST APIs. Use when creating or reviewing endpoints, request/response shapes, status codes, error formats, pagination, filtering, versioning, idempotency, rate limiting, or API documentation.
  • 95api-and-interface-design
    Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
  • 100reviewing-module-design
    Reviews module and type design: cohesion and coupling (via connascence), encapsulation, hard-to-misuse interfaces, and making illegal states unrepresentable. Use when reviewing class/module structure, interfaces, type or data modeling, coupling, or API ergonomics for callers.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.