api-design
/api-design
Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.
- Author
- srstomp ↗
- Repository
- pokayokay ↗
- Licence
- MIT
- Last repository change
- 28.09.2026
Assessment and security
- Files in this package
- 12
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 28.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.
Original author description
Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.
How it works
- When NOT to Use
- Core Principles
- Quick Start Checklist
- Design Quick Reference
- References
SKILL.md preview
--- name: api-design description: Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications. --- # API Design Design clear, consistent, and developer-friendly REST APIs. ## When NOT to Use - **Consuming external APIs** — Use `api-integration` for building clients to call third-party services (Stripe, Twilio, etc.) - **Writing tests for APIs** — Use `testing-strategy` for contract tests, integration tests, mocking strategies - **Reviewing existing API security** — Use `security-audit` for vulnerability scanning of live endpoints - **Designing auth mechanisms** that are the whole task — Use `security-audit` if reviewing, this skill if designing from scratch ## Core Principles - **Resource-oriented** — Design around nouns (resources), not verbs (actions) - **Predictable patterns** — Consistent URL structure, response format, and behavior - **Clear contracts** — Explicit schemas, documented errors, versioned endpoints - **Developer experience** — Meaningful errors, helpful examples, logical defaults ## Quick Start Checklist 1. Identify resources and their relationships 2. Define CRUD operations + custom actions with correct HTTP methods 3. Design request/response schemas with consistent envelope 4. Plan error format with status codes, error codes, and field-level details 5. Write OpenAPI specification with examples 6. Review for consistency, security, and usability ## Design Quick Reference | Method | Purpose | Idempotent | Body | |--------|---------|------------|------| | GET | Read | Yes | No | | POST | Create | No | Yes | | PUT | Replace | Yes | Yes | | PATCH | Partial update | Yes* | Yes | | DELETE | Remove | Yes | No | ## References | Reference | Description | |-----------|-------------| | [endpoints.md](references/endpoints.md) | URL design, HTTP methods, resource modeling | | [requests-responses.md](references/requests-responses.md) | Request/response formats, headers, content types | | [status-codes.md](references/status-codes.md) | HTTP status codes, error handling patterns | | [pagination-filtering.md](references/pagination-filtering.md) | Pagination, filtering, sorting, searching | | [versioning.md](references/versioning.md) | API versioning strategies | | [openapi.md](references/openapi.md) | OpenAPI specification, documentation | | [security.md](references/security.md) | Authentication, authorization, rate limiting | | [tdd-patterns.md](references/tdd-patterns.md) | Test-first patterns for REST endpoints, supertest templates | | [review-checklist.md](references/review-checklist.md) | API design review checklist (validation, auth, performance, docs) |
Files in this package (12)
- SKILL.md 3 KB
- eval-log.md 60 KB
- eval.json 17 KB
- references/endpoints.md 10 KB
- references/openapi.md 10 KB
- references/pagination-filtering.md 8 KB
- references/requests-responses.md 8 KB
- references/review-checklist.md 1 KB
- references/security.md 10 KB
- references/status-codes.md 8 KB
- references/tdd-patterns.md 2 KB
- references/versioning.md 10 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · srstomp/pokayokay | 100 | MIT |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Database snapshot: 13.11.2026 · package version 4408daccc7f7 (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-designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards. - 100api-designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards. - 100api-design-patterns
REST API design, versioning, error responses, pagination, OpenAPI conventions. Use when designing new API endpoints, reviewing API contracts, or setting up Swagger/OpenAPI documentation. - 100api-design-document
Design a production-ready API specification aligned with OpenAPI 3.1 standards. Covers resource modeling, endpoint design, request/response contracts, authentication, versioning strategy, error handling, rate limiting, and pagination. Use when designing a new REST, GraphQL, or event-driven API. - 90api-contract-design
REST and GraphQL API design patterns, OpenAPI/Swagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints. - 100api-designer
Use this agent when designing new APIs, creating API specifications, or refactoring existing API architecture for scalability and developer experience. Invoke when you need REST/GraphQL endpoint design, OpenAPI documentation, authentication patterns, or API versioning strategies.