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 API-specific client drafts; production readiness requires the actual contract, tests and target-language review.
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}
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}"
# No automatic replay of writes: add bounded retries only for operations
# documented as safe/idempotent, with API-supported idempotency keys.
resp = self._client.request(method, url, headers=self._headers, **kwargs)
if resp.is_error:
raise APIError(resp.status_code, "Request failed") # redact bodies/secrets
if resp.status_code == 204 or not resp.content:
return None
return resp.json() # validate against the endpoint response schema
def close(self):
self._client.close()
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 !== undefined ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(30_000),
});
if (!res.ok) {
throw new Error(`API request failed: HTTP ${res.status}`);
}
if (res.status === 204) return undefined as T;
return await res.json() as T; // A cast is not runtime schema validation.
}
}
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}")
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
def paginate_pages(fetch_page, max_pages=100):
"""fetch_page(page) must return {data: [...], total_pages: int}."""
for page in range(1, max_pages + 1):
result = fetch_page(page)
yield from result["data"]
if page >= result["total_pages"]:
return
raise RuntimeError("Pagination limit reached")
This helper requires a page-envelope endpoint, not UsersResource.list above, which returns a list. Adapt cursor/page semantics to the actual API, validate envelopes and bound total items/time. Encode path identifiers (including slashes), pass query values through the HTTP client's parameter encoder, constrain base URLs to trusted HTTPS origins and avoid leaking authorization to redirects. Close Python clients in a finally block or implement a context manager. The examples assume JSON success bodies other than 204; binary/text endpoints need separate response handling.
User-Agent header identifying the SDK name and version.