API Integration Skill

When to Activate

Activate this skill when:

• Integrating external APIs

• Building API clients or wrappers

• Handling API authentication

• Implementing rate limiting

• Caching API responses

Core Principles

• Respect rate limits - APIs are shared resources

• Secure authentication - Keys in secrets.json, never in code

• Handle errors gracefully - Implement retries and backoff

• Cache responses - Reduce redundant requests

Authentication Setup

secrets.json

{ "github_token": "ghp_your_token_here", "openweather_api_key": "your_key_here", "comment": "Never commit this file" }

Python Loading

import os import json from pathlib import Path

def load_secrets(): secrets_path = Path(file).parent / "secrets.json" try: with open(secrets_path) as f: return json.load(f) except (FileNotFoundError, json.JSONDecodeError): return {}

secrets = load_secrets() API_KEY = secrets.get("github_token", os.getenv("GITHUB_TOKEN", ""))

if not API_KEY: raise ValueError("No API key found")

Request Patterns

Basic GET (Python)

import requests

def api_request(url: str, api_key: str) -> dict: headers = { "Authorization": f"Bearer {api_key}", "Accept": "application/json" } response = requests.get(url, headers=headers, timeout=10) response.raise_for_status() return response.json()

With Retry and Backoff

import time from typing import Optional

def api_request_with_retry( url: str, api_key: str, max_retries: int = 3 ) -> Optional[dict]: headers = {"Authorization": f"Bearer {api_key}"} wait_time = 1

for attempt in range(max_retries):
    try:
        response = requests.get(url, headers=headers, timeout=10)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            wait_time *= 2
        else:
            print(f"Error: HTTP {response.status_code}")
            return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        time.sleep(wait_time)
        wait_time *= 2

return None

Bash Request

#!/bin/bash API_KEY=$(python3 -c "import json; print(json.load(open('secrets.json'))['github_token'])")

curl -s -H "Authorization: Bearer $API_KEY"
-H "Accept: application/json"
"https://api.github.com/user" | jq '.'

Error Handling

try: response = requests.get(url, headers=headers, timeout=10) response.raise_for_status() data = response.json() except requests.exceptions.HTTPError as e: if e.response.status_code == 429: print("Rate limited - waiting") elif e.response.status_code == 401: print("Unauthorized - check API key") else: print(f"HTTP error: {e}") except requests.exceptions.ConnectionError: print("Connection error") except requests.exceptions.Timeout: print("Request timeout")

HTTP Status Codes

Code Meaning Action

200 Success Process response

401 Unauthorized Check API key

403 Forbidden Check permissions

404 Not found Verify endpoint

429 Rate limited Wait and retry

5xx Server error Retry with backoff

Caching

import time

cache = {} CACHE_TTL = 3600 # 1 hour

def cached_request(url: str, api_key: str) -> dict: now = time.time()

if url in cache:
    data, timestamp = cache[url]
    if now - timestamp < CACHE_TTL:
        return data

data = api_request(url, api_key)
cache[url] = (data, now)
return data

Rate Limiting

Check Headers

curl -I -H "Authorization: Bearer $API_KEY" "https://api.github.com/user" | grep -i rate

x-ratelimit-limit: 5000

x-ratelimit-remaining: 4999

Implement Delays

import time

def bulk_requests(urls: list, api_key: str, delay: float = 1.0): results = [] for url in urls: result = api_request(url, api_key) results.append(result) time.sleep(delay) return results

Pagination

def fetch_all_pages(base_url: str, api_key: str) -> list: all_items = [] page = 1

while True:
    url = f"{base_url}?page={page}&per_page=100"
    data = api_request(url, api_key)

    if not data:
        break

    all_items.extend(data)
    page += 1
    time.sleep(1)  # Respect rate limits

return all_items

Best Practices

DO ✅

• Store keys in secrets.json

• Implement retry with exponential backoff

• Cache responses when appropriate

• Respect rate limits

• Handle errors gracefully

• Log requests (without sensitive data)

DON'T ❌

• Hardcode API keys

• Ignore rate limits

• Skip error handling

• Make requests in tight loops

• Log API keys

API Etiquette Checklist

• Read API documentation and ToS

• Check rate limits

• Store keys securely

• Implement rate limiting

• Add error handling

• Cache appropriately

• Monitor usage

Grove API Error Responses (MANDATORY)

When building API routes in Grove applications, all error responses MUST use Signpost error codes. Never return ad-hoc JSON error shapes.

import { API_ERRORS, buildErrorJson, logGroveError, } from "@autumnsgrove/lattice/errors"; import { json } from "@sveltejs/kit";

export const POST: RequestHandler = async ({ request, locals }) => { if (!locals.user) { logGroveError("Engine", API_ERRORS.UNAUTHORIZED, { path: "/api/resource" }); return json(buildErrorJson(API_ERRORS.UNAUTHORIZED), { status: 401 }); }

const body = schema.safeParse(await request.json()); if (!body.success) { return json(buildErrorJson(API_ERRORS.INVALID_REQUEST_BODY), { status: 400, }); }

// ... business logic };

Client-side, use apiRequest() (handles CSRF + credentials) and show toast feedback:

import { toast } from "@autumnsgrove/lattice/ui";

try { await apiRequest("/api/resource", { method: "POST", body }); toast.success("Created!"); } catch (err) { toast.error(err instanceof Error ? err.message : "Something went wrong"); }

See AgentUsage/error_handling.md for the complete Signpost error code reference.

Related Resources

See AgentUsage/api_usage.md for complete documentation including:

• Bash request patterns

• Conditional requests (ETags)

• Advanced caching strategies

• Specific API examples (GitHub, OpenWeather)