api-design · git:20260923.ffaa29c · 2026-09-23 · sha256 a5cb0dbe5da92c75

api-design git:20260923.ffaa29cA

Immutable. This exact content never changes and is served at /api/v1/blob/a5cb0dbe5da92c75.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_zutslgyo7tfq5mak/a5cb0dbe5da92c7548a5afc9b2d42a00462804d3e62347ddb0d920c5ed6f4c48.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