api-design

Category: Testing & Security | Uploader: srstomp | Downloads: 0 | Version: v1.0（Latest）

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

Changelog: Source: GitHub https://github.com/srstomp/pokayokay

Directory Structure

Current level: plugins/pokayokay/skills/api-design/

📁 references/
- 📄 endpoints.md 10.6 KB
- 📄 openapi.md 18.0 KB
- 📄 pagination-filtering.md 8.9 KB
- 📄 requests-responses.md 8.8 KB
- 📄 review-checklist.md 1.4 KB
- 📄 security.md 12.6 KB
- 📄 status-codes.md 11.5 KB
- 📄 tdd-patterns.md 2.0 KB
- 📄 versioning.md 11.1 KB
📄 SKILL.md 2.7 KB

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-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) |

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

api-design

Directory Structure

SKILL.md

Report

Notice