Skill

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.

Install

npx claudepluginhub srstomp/pokayokay --plugin pokayokay

Tool Access

This skill uses the workspace's default tool permissions.

Preview

Design clear, consistent, and developer-friendly REST APIs.

Supporting Assets

eval-log.mdeval.jsonreferences/endpoints.mdreferences/openapi.mdreferences/pagination-filtering.mdreferences/requests-responses.mdreferences/review-checklist.mdreferences/security.mdreferences/status-codes.mdreferences/tdd-patterns.mdreferences/versioning.md

SKILL.md

Similar Skills

kotlin-ktor-patterns

Provides Ktor server patterns for routing DSL, plugins (auth, CORS, serialization), Koin DI, WebSockets, services, and testApplication testing.

everything-claude-code

163.2k

deep-research

Conducts multi-source web research with firecrawl and exa MCPs: searches, scrapes pages, synthesizes cited reports. For deep dives, competitive analysis, tech evaluations, or due diligence.

everything-claude-code

163.2k

inventory-demand-planning

Provides demand forecasting, safety stock optimization, replenishment planning, and promotional lift estimation for multi-location retailers managing 300-800 SKUs.

everything-claude-code

163.2k

Stats

Parent Repo Stars4

Parent Repo Forks0

Last CommitFeb 8, 2026

Actions

View Source View Plugin View on GitHub View README

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

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)