Agent skill

api-integrator

Integrate external REST and GraphQL APIs with proper authentication (Bearer, Basic, OAuth), error handling, retry logic, and JSON schema validation. Use when making API calls, database queries, or integrating external services like Stripe, Twilio, AWS. Achieves 10-30x cost savings through direct execution vs LLM-based calls. Triggers on "API call", "REST API", "GraphQL", "external service", "API integration", "HTTP request".

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/api-integrator

SKILL.md

API Integrator

Purpose

Robust patterns for integrating external APIs and databases with authentication, error handling, retry logic, and response validation.

When to Use

  • Making REST or GraphQL API calls
  • Querying databases
  • Integrating external services (Stripe, Twilio, AWS, etc.)
  • Need robust error handling and retry logic
  • Require response schema validation
  • Bulk API operations

Core Instructions

REST API Pattern

python
import requests
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=1, max=10)
)
def call_api(endpoint, method="GET", headers=None, data=None):
    """
    Make API call with retries
    """
    if not headers:
        headers = {}
        # Auto-add auth from environment
        if os.getenv('API_TOKEN'):
            headers["Authorization"] = f"Bearer {os.getenv('API_TOKEN')}"

    response = requests.request(
        method=method,
        url=endpoint,
        headers=headers,
        json=data,
        timeout=30
    )
    response.raise_for_status()
    return response.json()

Error Handling Strategy

  • 2xx Success: Return data
  • 4xx Client Error: Log and raise (no retry - client's fault)
  • 5xx Server Error: Retry with exponential backoff
  • Timeout: Retry up to 3 times
  • Network Error: Retry with backoff

Authentication Methods

Bearer Token:

python
headers = {"Authorization": f"Bearer {token}"}

Basic Auth:

python
from requests.auth import HTTPBasicAuth
auth = HTTPBasicAuth('username', 'password')
response = requests.get(url, auth=auth)

OAuth 2.0:

python
from requests_oauthlib import OAuth2Session
oauth = OAuth2Session(client_id, token=token)
response = oauth.get(url)

GraphQL Pattern

python
def call_graphql(endpoint, query, variables=None):
    """
    Execute GraphQL query
    """
    payload = {
        'query': query,
        'variables': variables or {}
    }
    return call_api(endpoint, method='POST', data=payload)

Response Validation

python
from pydantic import BaseModel, ValidationError

class APIResponse(BaseModel):
    id: int
    name: str
    email: str

def validate_response(data):
    try:
        return APIResponse(**data)
    except ValidationError as e:
        # Handle validation errors
        log_error(e)
        raise

Integration Examples

Example 1: GitHub API

python
# Get user info
response = call_api('https://api.github.com/users/github')
print(f"GitHub created: {response['created_at']}")

Example 2: Stripe Payment

python
import stripe
stripe.api_key = os.getenv('STRIPE_KEY')

# Create payment intent
intent = stripe.PaymentIntent.create(
    amount=1000,
    currency='usd'
)

Example 3: Database Query (PostgreSQL)

python
import psycopg2

conn = psycopg2.connect(
    host=os.getenv('DB_HOST'),
    database=os.getenv('DB_NAME'),
    user=os.getenv('DB_USER'),
    password=os.getenv('DB_PASSWORD')
)

cursor = conn.cursor()
cursor.execute("SELECT * FROM users WHERE active = true")
results = cursor.fetchall()

Best Practices

  1. Use Environment Variables: Store credentials in .env, never hardcode
  2. Implement Retries: Use tenacity for automatic retry with backoff
  3. Validate Responses: Use Pydantic or JSON Schema
  4. Handle Rate Limits: Respect API rate limits, implement backoff
  5. Log Requests: Log all API calls for debugging
  6. Timeout Properly: Always set request timeouts (default: 30s)

Performance

  • 10-30x cost reduction vs calling LLM for each API operation
  • < 100ms overhead for request/retry logic
  • 95%+ success rate with proper retry strategy

Dependencies

  • Python 3.8+
  • requests - HTTP library
  • tenacity - Retry logic
  • pydantic - Response validation (optional)
  • requests-oauthlib - OAuth support (optional)

Version

v1.0.0 (2025-10-23)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results