api-design

Original：🇺🇸 English

Translated

Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.

1installs

Sourcesrstomp/pokayokay

Added on2026-02-18

NPX Install

npx skill4agent add srstomp/pokayokay api-design

SKILL.md Content

View Translation Comparison →

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)