Skip to content
Skills Library
Programming · Learning & explanation

using-api-principles

/using-api-principles

This skill should be used when the user asks "which API design skill should I use", "show me all API principles", "help me pick an API pattern", or at the start of any RESTful API design conversation. Provides the index of all twelve principle skills and ensures the right ones are invoked before any API design work begins.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

90/ 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.
Content25 / 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 25.10.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

This skill should be used when the user asks "which API design skill should I use", "show me all API principles", "help me pick an API pattern", or at the start of any RESTful API design conversation. Provides the index of all twelve principle skills and ensures the right ones are invoked before any API design work begins.

Triggers from the description

which API design skill should I useshow me all API principleshelp me pick an API pattern
Original author description

This skill should be used when the user asks "which API design skill should I use", "show me all API principles", "help me pick an API pattern", or at the start of any RESTful API design conversation. Provides the index of all twelve principle skills and ensures the right ones are invoked before any API design work begins.

How it works

  1. How to Access Skills
  2. Available Skills
  3. When to Invoke Skills
  4. The Three Meta-Principles
Original SKILL.md headings · 49 lines, 443 words
SKILL.md preview
---
name: using-api-principles
description: This skill should be used when the user asks "which API design skill should I use", "show me all API principles", "help me pick an API pattern", or at the start of any RESTful API design conversation. Provides the index of all twelve principle skills and ensures the right ones are invoked before any API design work begins.
version: 1.0.0
---

<IMPORTANT>
When working on any RESTful API pattern — routes, naming, HTTP methods, error handling, authentication, pagination, caching, webhooks, versioning, or documentation — invoke the relevant api-design-principles skill BEFORE writing or reviewing code.

These are not suggestions. They are research-backed, opinionated principles drawn from Stripe, GitHub, Twilio, Shopify, Google, Microsoft, Zalando, Cloudflare, OWASP, and industry RFCs.
</IMPORTANT>

## How to Access Skills

Use the `Skill` tool to invoke any skill by name. When invoked, follow the skill's guidance directly.

## Available Skills

| Skill | Triggers On |
|-------|-------------|
| `api-design-principles:routes-and-naming` | URL design, endpoint naming, plural nouns, nesting depth, query vs path params, snake_case, field naming |
| `api-design-principles:http-methods` | GET/POST/PUT/PATCH/DELETE semantics, idempotency per verb, CRUD operations, method selection |
| `api-design-principles:prefixed-ids` | Type-safe identifiers, Stripe-style prefixed IDs (`cus_`, `ord_`), KSUID, ULID, ID generation |
| `api-design-principles:errors-and-status-codes` | HTTP status codes, error envelopes, per-field validation errors, RFC 9457, error formatting |
| `api-design-principles:response-design-and-pagination` | Response envelopes, cursor/offset/keyset pagination, expand patterns, list metadata |
| `api-design-principles:auth-and-api-keys` | API key design (`sk_live_`, `pk_test_`), OAuth 2.0, JWT, Bearer tokens, key rotation |
| `api-design-principles:rate-limiting-and-security` | Rate limiting algorithms/headers, OWASP API Top 10, CORS, input validation, request signing |
| `api-design-principles:versioning-and-evolution` | URL versioning (`/v1/`), date-based versioning, sunset headers, additive evolution, deprecation |
| `api-design-principles:caching-and-performance` | Cache-Control, ETags, conditional requests, CDN strategies, compression, circuit breakers |
| `api-design-principles:webhooks-and-events` | HMAC-SHA256 signing, retry logic, event naming (`resource.action`), webhook endpoints |
| `api-design-principles:documentation-and-dx` | API docs, interactive explorers, SDK generation, onboarding, time-to-first-call, changelogs |
| `api-design-principles:advanced-patterns` | Bulk/batch ops, REST vs GraphQL vs gRPC, SSE/WebSockets, multi-tenancy, API gateways, CQRS |

## When to Invoke Skills

Invoke a skill when there is even a small chance the work touches one of these areas:

- Designing or modifying any API endpoint, route, or resource
- Implementing authentication, authorization, or rate limiting
- Building error handling, response formatting, or pagination
- Reviewing existing API code for quality or consistency
- Making architectural decisions about caching, versioning, or real-time patterns
- Writing API documentation or designing developer onboarding

## The Three Meta-Principles

All twelve principles rest on three foundations:

1. **Consistency beats cleverness** — A predictable API that follows conventions everywhere is better than a clever API that surprises developers. Pick one pattern and apply it universally.

2. **Errors are part of the interface** — Every error response, status code, and validation message is as carefully designed as the happy path. Developers spend more time debugging than building.

3. **Optimize for the consumer, not the server** — API shape follows what makes client code simple, not what matches the database schema. The server does extra work so every client doesn't have to.

Versions

The database has no other skills named using-api-principles.

Database snapshot: 13.11.2026 · package version 015c3965d0a8 (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

  • 90using-saas-principles
    This skill should be used when the user asks "which SaaS design skill should I use", "show me all design principles", "help me pick a design pattern", or at the start of any SaaS-related conversation. Provides the index of all twelve principle skills and ensures the right ones…
  • 90using-visual-design-principles
    This skill should be used when the user asks 'which visual design skill should I use', 'show me all design principles', 'help me evaluate a design', or at the start of any visual design conversation. Provides the index of all eleven principle skills and ensures the right ones…
  • 90api-design-principles
    当用户需要设计新的 REST/GraphQL API、审查 API 规范或建立团队 API 设计标准时使用。此 Skill 提供直观的、可扩展的、可维护的 API 设计原则和最佳实践。
  • 100api-design-principles
    Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
  • 100api-design-principles
    Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
  • 100api-design-principles
    Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

Feedback and reports

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