API SDK & Codegen Skill

When to Use

Use this skill when you need generates client SDK code, API wrapper libraries, request/response models, and language-specific usage patterns for any REST API. Use whenever the user asks to "generate an SDK", "write a client library", "create API wrappers", "generate TypeScript types from my API", "write a Python...

Generate production-quality client libraries and SDK code for any API in any language.

---

SDK Structure (any language)

sdk/
├── client.{ext}          — main client class with base URL, auth, retry
├── resources/
│   ├── users.{ext}       — one file per API resource
│   ├── orders.{ext}
│   └── ...
├── models/
│   ├── user.{ext}        — request/response data models
│   └── ...
├── errors.{ext}          — typed error classes
└── utils/
    ├── retry.{ext}
    └── pagination.{ext}

---

Base Client Pattern

Python

import httpx
from typing import Optional
import time

class APIClient:
    def __init__(self, api_key: str, base_url: str = "https://api.example.com/v1"):
        self.base_url = base_url
        self._headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "User-Agent": "example-sdk-python/1.0.0"
        }
        self._client = httpx.Client(timeout=30.0)

    def _request(self, method: str, path: str, **kwargs) -> dict:
        url = f"{self.base_url}{path}"
        for attempt in range(3):
            try:
                resp = self._client.request(method, url, headers=self._headers, **kwargs)
                if resp.status_code == 429:
                    retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
                    time.sleep(retry_after)
                    continue
                resp.raise_for_status()
                return resp.json()
            except httpx.HTTPStatusError as e:
                raise APIError(e.response.status_code, e.response.json()) from e
        raise RateLimitError("Max retries exceeded")

TypeScript

class APIClient {
  private readonly baseUrl: string;
  private readonly headers: Record<string, string>;

  constructor(apiKey: string, baseUrl = 'https://api.example.com/v1') {
    this.baseUrl = baseUrl;
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    };
  }

  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      method,
      headers: this.headers,
      body: body ? JSON.stringify(body) : undefined,
    });
    if (!res.ok) {
      const err = await res.json();
      throw new APIError(res.status, err.message);
    }
    return res.json() as T;
  }
}

---

Resource Class Pattern

Python

from dataclasses import dataclass
from typing import Optional, List

@dataclass
class User:
    id: str
    name: str
    email: str
    created_at: str
    role: Optional[str] = None

class UsersResource:
    def __init__(self, client: APIClient):
        self._client = client

    def list(self, page: int = 1, limit: int = 20) -> List[User]:
        data = self._client._request("GET", f"/users?page={page}&limit={limit}")
        return [User(**u) for u in data["data"]]

    def get(self, user_id: str) -> User:
        data = self._client._request("GET", f"/users/{user_id}")
        return User(**data)

    def create(self, name: str, email: str, role: Optional[str] = None) -> User:
        payload = {"name": name, "email": email}
        if role:
            payload["role"] = role
        data = self._client._request("POST", "/users", json=payload)
        return User(**data)

    def delete(self, user_id: str) -> None:
        self._client._request("DELETE", f"/users/{user_id}")

---

Typed Error Classes

class APIError(Exception):
    def __init__(self, status_code: int, message: str):
        self.status_code = status_code
        self.message = message
        super().__init__(f"HTTP {status_code}: {message}")

class AuthenticationError(APIError): pass   # 401
class AuthorizationError(APIError): pass    # 403
class NotFoundError(APIError): pass         # 404
class ValidationError(APIError): pass       # 422
class RateLimitError(APIError): pass        # 429
class ServerError(APIError): pass           # 5xx

---

Pagination Helper

def paginate(resource_method, **kwargs):
    """Iterate through all pages of a paginated endpoint."""
    page = 1
    while True:
        result = resource_method(page=page, **kwargs)
        yield from result.data
        if page >= result.pagination.total_pages:
            break
        page += 1

# Usage:
for user in paginate(client.users.list):
    print(user.name)

---

Rules

• Always include retry logic with exponential backoff for 429 and 5xx.
• Always include a User-Agent header identifying the SDK name and version.
• All models must be typed (dataclasses in Python, interfaces in TypeScript, structs in Go).
• Resource classes should mirror the API resource hierarchy.
• Provide a usage example for every generated class.

---

Limitations

• Use this skill only when the task clearly matches its upstream source and local project context.
• Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
• Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.