api-design · git:20260923.82a4143 · 2026-09-23 · sha256 1ada65f91b8ce695
api-design git:20260923.82a4143A
Immutable. This exact content never changes and is served at /api/v1/blob/1ada65f91b8ce695.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_zutslgyo7tfq5mak/1ada65f91b8ce6950cf9bb2ae9420611b9f6670d8b434cc2fa57164056628bc3.json
Then /plugin install api-design@markdownregistry-zutslgyo7tfq5mak in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: api-design
description: RESTful and GraphQL API design: OpenAPI specs, pagination, rate limiting, error schemas, versioning, and backwards compatibility.
---
# API Design Skill
Design clean, consistent, and maintainable APIs.
## RESTful Design Principles
- Use nouns for resources, HTTP verbs for actions
- Consistent URL patterns: `/resources/{id}/sub-resources`
- Proper HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 500)
- Stateless: each request contains all needed info
- HATEOAS: include links for discoverability
## API Response Schema
```json
{
"data": {},
"meta": { "page": 1, "per_page": 20, "total": 100 },
"links": { "self": "...", "next": "...", "prev": "..." },
"errors": []
}
```
## Error Schema
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [{"field": "email", "issue": "invalid format"}]
}
}
```
## Key Patterns
- **Pagination**: cursor-based for large datasets, offset for small
- **Filtering**: query params `?status=active&created_after=2024-01-01`
- **Sorting**: `?sort=-created_at,name`
- **Rate Limiting**: 429 + Retry-After header
- **Versioning**: URL path (`/v2/`) or header
- **Idempotency**: idempotency keys for safe retries