How do I install the Skill API Design skill?

Run npx skillmds@latest add saitarrun/skill-api-design in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Skill API Design safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Skill API Design?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Skill API Design free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Skill API Design?

saitarrun (@saitarrun) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Skill API Design by saitarrun — Agent Skill

Name: Skill API Design
Author: saitarrun

Skill API Design

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.

saitarrun d895109 2.3 KB Updated Sep 17, 2026

File contents

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

---name: skill-api-designdescription: 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: API DesignDesign 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 APIGET /api/v2/users # v2 API (breaking change)```**Header** (less visible, prefer path):```GET /api/usersHeader: API-Version: 2```## Breaking Changes = Major Version```v1.0 → v2.0: User response format changedv1.1 → v1.2: New optional field added (backward-compatible)v1.0 → v1.1: Bug fix (patch)```## API Contract (OpenAPI/Swagger)```yamlpaths: /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```json{ "error": "not_found", "message": "User not found", "code": 404, "details": { "resource": "user", "id": "user-123" }}```## Rate Limiting```Header: X-RateLimit-Limit: 1000Header: X-RateLimit-Remaining: 999Header: X-RateLimit-Reset: 1640000000```## Pagination```GET /users?page=2&page_size=10Response:{ "items": [...], "total": 245, "page": 2, "page_size": 10, "has_next": true}```## Deprecation Plan```1. Announce: Email, docs, API response header2. Timeline: 6 months before removal3. Header: X-API-Warn: "endpoint deprecated, use /v2/..."4. Support: v1 and v2 endpoints run in parallel5. Remove: After timeline expires```---**Status**: Ready for API design **Best for**: API contracts, versioning, error handling

Frequently asked questions