Skill api design

Skill saitarrun/sdlc-ai-workflow/skills/skill-api-design

A comprehensive Claude Code plugin that automates the complete Software Development Lifecycle with 20 role-specific agents, 12 knowledge skills, and 8 commands, all guided by principles.

Install

npx -y skills add saitarrun/sdlc-ai-workflow --skill 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.
2 stars2 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.

What its author says it does

Copied from the file, not written here

REST/gRPC API design, versioning strategies, error codes, request/response contracts, backward compatibility, rate limiting, OpenAPI specifications. Use when designing APIs, defining contracts, planning versioning, or ensuring API consistency.

SKILL.md

2.3 KB, as published. Nobody here has run it

Skill: API Design

Design APIs as contracts. Versions matter. Backward compatibility is non-negotiable.

REST Principles

Noun-based URLs: /users not /getUsers
HTTP methods: GET (read), POST (create), PUT (update), DELETE (remove)
Status codes: 200 (OK), 201 (created), 400 (bad request), 401 (auth), 404 (not found), 500 (error)
Consistency: Same patterns across all endpoints

Versioning Strategy

URL path (explicit, clear):

GET /api/v1/users   # v1 API
GET /api/v2/users   # v2 API (breaking change)

Header (less visible, prefer path):

GET /api/users
Header: API-Version: 2

Breaking Changes = Major Version

v1.0 → v2.0: User response format changed
v1.1 → v1.2: New optional field added (backward-compatible)
v1.0 → v1.1: Bug fix (patch)

API Contract (OpenAPI/Swagger)

paths:
  /users/{id}:
    get:
      summary: Get user
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Not found

Error Responses

{
  "error": "not_found",
  "message": "User not found",
  "code": 404,
  "details": {
    "resource": "user",
    "id": "user-123"
  }
}

Rate Limiting

Header: X-RateLimit-Limit: 1000
Header: X-RateLimit-Remaining: 999
Header: X-RateLimit-Reset: 1640000000

Pagination

GET /users?page=2&page_size=10

Response:
{
  "items": [...],
  "total": 245,
  "page": 2,
  "page_size": 10,
  "has_next": true
}

Deprecation Plan

1. Announce: Email, docs, API response header
2. Timeline: 6 months before removal
3. Header: X-API-Warn: "endpoint deprecated, use /v2/..."
4. Support: v1 and v2 endpoints run in parallel
5. Remove: After timeline expires

Status: Ready for API design
Best for: API contracts, versioning, error handling