mcpField

api-design

github.com/eddiebe147Development40 installs
Repository

About api-design

A REST API design reference for developers defining endpoints, request and response formats, status codes, versioning, and security practices.

Key features

  1. 01HTTP method and URL conventions
  2. 02Status code guidance
  3. 03Collection and error response formats
  4. 04Filtering, sorting, and pagination
  5. 05Idempotency and versioning
  6. 06Input validation and security guidance

Use cases

  1. 01Designing CRUD endpoints
  2. 02Standardizing API error responses
  3. 03Adding pagination and filtering
  4. 04Planning breaking API changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/eddiebe147/claude-settings --skill api-design

After installing, type/api-designin Claude Code to confirm it loaded.

Details

From the project README

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

CodeMeaningWhen to Use
200OKSuccessful GET, PUT, PATCH
201CreatedSuccessful POST (new resource)
204No ContentSuccessful DELETE
400Bad RequestValidation errors, malformed request
401UnauthorizedMissing or invalid authentication
403ForbiddenValid auth but no permission
404Not FoundResource doesn't exist
409ConflictDuplicate, state conflict
422UnprocessableSemantic errors
500Server ErrorUnexpected 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

Comments

Markdown supported