api-integration

API Integration Skill

Overview

Build reliable integrations with REST APIs: authentication, pagination, rate limiting, retries, and error handling. Covers the full lifecycle from first call to production-ready client.

Step-by-Step Process

Step 1: Read the API Docs

Before writing any code, identify:

• Base URL and API version (https://api.example.com/v2)
• Authentication method (API key header, Bearer token, OAuth 2.0, Basic auth)
• Rate limits (requests per minute/hour, burst limits)
• Pagination style (offset/limit, cursor, page number, Link header)
• Error response format (status codes, error body schema)

Step 2: Set Up Authentication

API Key (header)

import httpx

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
client = httpx.Client(base_url="https://api.example.com/v2", headers=headers)

OAuth 2.0 Client Credentials

import httpx

def get_access_token(client_id: str, client_secret: str, token_url: str) -> str:
    response = httpx.post(token_url, data={
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret,
    })
    response.raise_for_status()
    return response.json()["access_token"]

Basic Auth

client = httpx.Client(auth=(username, password))

Step 3: Make Requests with Retry Logic

import httpx
import time
from typing import Any

def api_request(
    client: httpx.Client,
    method: str,
    path: str,
    max_retries: int = 3,
    **kwargs: Any,
) -> dict:
    for attempt in range(max_retries):
        try:
            response = client.request(method, path, timeout=30, **kwargs)

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 60))
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except httpx.HTTPStatusError as e:
            if e.response.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # exponential backoff
                continue
            raise

    raise RuntimeError(f"Failed after {max_retries} attempts")