Skip to content
Skills Library
Programming · Planning

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.

Repository
pokayokay ↗
Licence
MIT
Last repository change
28.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.09.2026, without references to retired models or APIs.

Licence

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

  1. When NOT to Use
  2. Core Principles
  3. Quick Start Checklist
  4. Design Quick Reference
  5. References
Original SKILL.md headings · 52 lines, 328 words
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

RepositoryScoreLicence
This page · srstomp/pokayokay100MIT
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.