srstomp/api-design
plugins/pokayokay/skills/api-design/SKILL.md
Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.
$ install --global
skillsauthnpx skillsauth add srstomp/pokayokay api-designInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 27, 2026, 7:03 AM71.7s12 files scanned
SKILL.md
- 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-integrationfor building clients to call third-party services (Stripe, Twilio, etc.) - Writing tests for APIs — Use
testing-strategyfor contract tests, integration tests, mocking strategies - Reviewing existing API security — Use
security-auditfor vulnerability scanning of live endpoints - Designing auth mechanisms that are the whole task — Use
security-auditif 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
- Identify resources and their relationships
- Define CRUD operations + custom actions with correct HTTP methods
- Design request/response schemas with consistent envelope
- Plan error format with status codes, error codes, and field-level details
- Write OpenAPI specification with examples
- 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 | URL design, HTTP methods, resource modeling | | requests-responses.md | Request/response formats, headers, content types | | status-codes.md | HTTP status codes, error handling patterns | | pagination-filtering.md | Pagination, filtering, sorting, searching | | versioning.md | API versioning strategies | | openapi.md | OpenAPI specification, documentation | | security.md | Authentication, authorization, rate limiting | | tdd-patterns.md | Test-first patterns for REST endpoints, supertest templates | | review-checklist.md | API design review checklist (validation, auth, performance, docs) |
Related Skills
srstomp/worktrees
development
VerifiedTrustedCommunity
Git worktree management for isolated task development
6SKILL.mdUpdated Apr 27, 2026
srstomp/work-session
development
VerifiedTrustedCommunity
Use when starting AI development sessions, resuming interrupted work, managing multi-session projects, or orchestrating work with human checkpoint control (supervised, semi-auto, auto, or unattended modes).
6SKILL.mdUpdated Apr 27, 2026
srstomp/verification-before-completion
testing
VerifiedTrustedCommunity
Use before claiming work is done, fixed, passing, ready to commit, ready to PR, or ready to mark complete. Requires fresh verification evidence and explicit command output before success claims.
6SKILL.mdUpdated Apr 27, 2026
srstomp/testing-strategy
development
VerifiedTrustedCommunity
Use when designing test architecture, building API test suites, validating API contracts, setting up component or E2E testing, managing test data, debugging flaky tests, reviewing coverage strategy, or organizing test files. Covers test pyramid, mocking (MSW), frontend (React Testing Library, Playwright), and CI integration.
6SKILL.mdUpdated Apr 27, 2026