Api design

Skill AndVl1/claude-plugin/skills/api-design

REST API design principles and patterns - use when designing new endpoints, creating DTOs, or planning API structureFrom its SKILL.md

Install

npx -y skills add AndVl1/claude-plugin --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.5 KB, as published. Nobody here has run it

REST API Design Principles

URL Structure

GET    /api/v1/resources           # List all
GET    /api/v1/resources/{id}      # Get one
POST   /api/v1/resources           # Create
PUT    /api/v1/resources/{id}      # Replace
PATCH  /api/v1/resources/{id}      # Partial update
DELETE /api/v1/resources/{id}      # Delete

# Nested resources
GET    /api/v1/parents/{id}/children
POST   /api/v1/parents/{id}/children

HTTP Status Codes

Code	Meaning	When to Use
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST (new resource)
204	No Content	Successful DELETE
400	Bad Request	Validation errors, malformed request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but no permission
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate, state conflict
422	Unprocessable	Semantic errors
500	Server Error	Unexpected errors

Request/Response Design

Collection Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}

Single Resource Response

{
  "id": "uuid",
  "name": "Resource Name",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": [
      {"field": "name", "message": "must not be blank"}
    ]
  }
}

Query Parameters

# Filtering
GET /api/v1/resources?status=active&type=premium

# Sorting
GET /api/v1/resources?sort=createdAt,desc

# Pagination
GET /api/v1/resources?page=1&pageSize=20

# Field selection
GET /api/v1/resources?fields=id,name,status

# Search
GET /api/v1/resources?search=query

Idempotency

POST with unique identifiers should return existing resource (200) if duplicate
PUT/DELETE should be idempotent
Use Pair<Result, Boolean> pattern to indicate created vs existing

Versioning

Use URL path versioning: /api/v1/, /api/v2/
Version when making breaking changes
Support old versions during migration period

Security Considerations

Always validate input at API boundary
Use parameterized queries (JOOQ handles this)
Check authorization in service layer
Never expose internal IDs or sensitive data
Rate limit public endpoints