Third-Party API Integration Skill

Purpose

Guide proper integration of third-party APIs with a documentation-first approach, preventing common mistakes and ensuring reliable integrations.

Automatic Activation

This skill is AUTOMATICALLY activated when user mentions:

• ✅ "ElevenLabs" / "OpenAI" / "Gemini" / "Vertex AI"

• ✅ "third-party API" / "第三方 API"

• ✅ "external API" / "外部 API"

• ✅ "API integration" / "API 整合"

• ✅ "documentation" (in API context)

Critical Rule: Documentation First

✅ MANDATORY: Read Official Docs FIRST

Before writing ANY integration code:

❌ WRONG Approach:

1. Search Google for "how to use X API"
2. Find random blog posts or Stack Overflow
3. Make assumptions based on similar APIs
4. Write code
5. Encounter errors
6. Read documentation (too late!)

✅ CORRECT Approach:

1. 需求確定 → 立即查官方文檔
2. Find correct API endpoint and parameter format
3. Review official example code
4. Write integration tests based on docs
5. Implement code
6. Test and verify

Why Documentation First:

• Official docs are always authoritative

• Prevents wasted commits from wrong assumptions

• Saves debugging time

• Ensures using latest API version

• Catches breaking changes early

Lesson Learned: Real Example

Case Study: ElevenLabs Language Code Issue

What Happened (2025-12-25):

❌ WRONG: Assumed language code based on web search

{ "language": "cmn" # or "zho" # Assumption: Chinese = "cmn" (Mandarin) or "zho" (Chinese) # Source: Generic ISO 639-3 lists from Google }

✅ CORRECT: Checked Realtime v2 docs

{ "language": "zh" # ISO 639-1 code # Source: https://elevenlabs.io/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime # Realtime v2 uses ISO 639-1, not ISO 639-3! }

Impact:

• ❌ 2 commits wasted

• ❌ Deployment delays

• ❌ Testing time lost

• ✅ Could have been avoided by reading docs first

Rule: "When in doubt, RTFM (Read The F*ing Manual)"**

Supported Third-Party Services

Key Services & Official Documentation

1. ElevenLabs (Voice AI)

Text-to-Speech:

• Docs: https://elevenlabs.io/docs/api-reference/text-to-speech

• Language codes: Various formats

Realtime v2 Speech-to-Text ⚠️ Special attention:

• Docs: https://elevenlabs.io/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime

• Language codes: ISO 639-1 (e.g., zh for Chinese)

• ⚠️ Different from TTS language codes!

• Always check version-specific docs

2. OpenAI

• Official Docs: https://platform.openai.com/docs/api-reference

• Key Points:

• Always check model-specific parameters

• Rate limits vary by tier

• Different models have different capabilities

• Check deprecation notices

3. Google Gemini / Vertex AI

• Official Docs: https://cloud.google.com/vertex-ai/docs

• Key Points:

• Check regional availability

• Authentication uses service accounts

• Different pricing by region

• Model versions and updates

4. Other Services

When integrating any third-party service:

• Find official API documentation

• Check API version (v1, v2, etc.)

• Review authentication methods

• Check rate limits and quotas

• Read example code in official docs

Development Process (Documentation-First)

Step-by-Step Integration

1. 需求確定 → 立即查官方文檔

   • What feature do we need?
   • Which API endpoint provides it?
   • What's the current API version? ↓

2. 找到正確的 API endpoint 和參數格式

   • Read endpoint documentation
   • Check required vs. optional parameters
   • Understand request/response formats
   • Note authentication requirements ↓

3. 查看官方範例代碼

   • Copy official examples
   • Understand the pattern
   • Check error handling
   • Review best practices ↓

4. 實作並測試 (TDD)

   • Write test FIRST (based on docs)
   • Implement integration
   • Verify with official examples
   • Handle errors properly ↓

5. ✅ Integration complete ❌ NOT: Write code first, read docs later!

Integration with TDD

Test Third-Party APIs Properly

Write tests based on official documentation:

Example: ElevenLabs Realtime v2 STT integration test

@pytest.mark.asyncio async def test_elevenlabs_realtime_stt(): """ Test ElevenLabs Realtime v2 Speech-to-Text

Official docs:
https://elevenlabs.io/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime

Key parameters (from official docs):
- language: ISO 639-1 code (e.g., 'zh' for Chinese)
- model: realtime-v2
"""
config = {
    "language": "zh",  # ISO 639-1 (from official docs)
    "model": "realtime-v2"
}

# Test based on official API contract
result = await stt_service.transcribe(audio_data, config)

assert result["text"] is not None
assert result["language"] == "zh"

Best Practices:

Include documentation link in test comments

""" Test X API endpoint

Official docs: https://example.com/docs/api/endpoint Parameters based on v2.0 specification """

Use official examples as test cases

• Copy request/response from docs

• Verify your code matches official behavior

• Helps catch API version mismatches

Validate API contract

• Test required fields

• Verify response structure

• Check error codes match docs

Keep docs link updated

• When API version changes

• When docs URL changes

• When parameters update

Common Mistakes to Avoid

❌ Anti-Pattern 1: Google-First Approach

❌ WRONG

Googles "python elevenlabs language code"

Finds Stack Overflow from 2023

Uses outdated information

API has changed since then

Code breaks

✅ CORRECT

Goes directly to official docs

Finds current API specification

Uses correct parameters

Code works

❌ Anti-Pattern 2: Assumption-Based Development

❌ WRONG

"OpenAI uses X format, so Gemini probably does too"

Makes assumptions without checking

Code breaks because APIs are different

✅ CORRECT

Reads Gemini-specific documentation

Understands Gemini's specific requirements

Implements correctly from the start

❌ Anti-Pattern 3: Skipping Error Handling

❌ WRONG

response = api.call(params) return response.data # No error checking

✅ CORRECT (based on official docs)

try: response = api.call(params) if response.status_code == 200: return response.data else: # Handle errors as documented in API docs raise APIError(f"API returned {response.status_code}") except Exception as e: # Error handling based on official documentation logger.error(f"API call failed: {e}") raise

❌ Anti-Pattern 4: Hardcoding API Versions

❌ WRONG

url = "https://api.example.com/v1/endpoint" # Hardcoded v1

✅ CORRECT

Use config/environment variables

API_VERSION = os.getenv("API_VERSION", "v2") url = f"https://api.example.com/{API_VERSION}/endpoint"

Documentation Checklist

Before Writing Integration Code

• Found official API documentation

• Verified API version (v1, v2, beta, etc.)

• Read endpoint-specific documentation

• Reviewed official example code

• Checked authentication requirements

• Noted rate limits and quotas

• Checked for version deprecations

During Implementation

• Using parameters exactly as documented

• Following official authentication pattern

• Handling errors as documented

• Testing with official example data

• Including docs link in comments

After Implementation

• Test passes with real API calls

• Error handling covers documented errors

• Rate limiting implemented (if needed)

• Documentation link in test comments

• API version noted in code

Service-Specific Guidelines

ElevenLabs Realtime v2

✅ CORRECT configuration (from official docs)

config = { "language": "zh", # ISO 639-1 "model": "realtime-v2", # Realtime v2 model "encoding": "pcm_16000" # Audio format }

⚠️ IMPORTANT

- Language code differs between TTS and STT

- Realtime v2 uses ISO 639-1 ('zh')

- TTS might use different codes

- Always check version-specific docs

Docs: https://elevenlabs.io/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime

OpenAI GPT

✅ CORRECT (based on official docs)

response = openai.ChatCompletion.create( model="gpt-4", # Check model availability messages=[...], temperature=0.7, # As documented max_tokens=1000 # Check model limits )

⚠️ IMPORTANT

- Different models have different limits

- Check rate limits for your tier

- Handle API errors properly

- Monitor token usage

Docs: https://platform.openai.com/docs/api-reference

Google Gemini / Vertex AI

✅ CORRECT (based on official docs)

from google.cloud import aiplatform

aiplatform.init( project="your-project-id", location="us-central1" # Check regional availability )

⚠️ IMPORTANT

- Requires service account authentication

- Check model availability by region

- Different pricing by region

- Use official Python SDK

Docs: https://cloud.google.com/vertex-ai/docs

Testing Third-Party Integrations

Integration Test Pattern

import pytest from unittest.mock import Mock, patch

@pytest.mark.asyncio async def test_third_party_api_integration(): """ Test integration with ThirdParty API

Official docs: https://example.com/docs/api
API version: v2.0
Parameters based on official specification
"""

# 1. Test with real API (integration test)
# Use test API keys (not production)
result = await service.call_api({
    "param1": "value1",  # From official docs
    "param2": "value2"   # From official docs
})

# Verify based on official API contract
assert result.status == "success"
assert "expected_field" in result.data

@pytest.mark.asyncio async def test_third_party_api_error_handling(): """ Test error handling based on official docs

Expected errors (from API docs):
- 400: Bad Request
- 401: Unauthorized
- 429: Rate Limit Exceeded
- 500: Server Error
"""

# Test each documented error case
with pytest.raises(APIError) as exc_info:
    await service.call_api(invalid_params)

assert exc_info.value.code == 400

Mocking External APIs

@patch('app.services.third_party.ThirdPartyClient') async def test_api_with_mock(mock_client): """ Mock external API for unit testing

Use official example response from docs
"""

# Use official example response from documentation
mock_client.return_value.call.return_value = {
    "status": "success",
    "data": {...}  # Copied from official docs
}

result = await service.process_with_api()
assert result is not None

Rate Limiting & Error Handling

Implement Rate Limiting

from tenacity import retry, stop_after_attempt, wait_exponential

@retry( stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10) ) async def call_third_party_api(params): """ Call third-party API with automatic retry

Retry strategy based on API documentation:
- Max 3 attempts
- Exponential backoff (2s, 4s, 8s)
- As recommended in official docs
"""
try:
    response = await client.call(params)
    return response
except RateLimitError:
    # Handle as documented
    logger.warning("Rate limit hit, retrying...")
    raise  # Retry will handle
except Exception as e:
    logger.error(f"API call failed: {e}")
    raise

Handle API Errors Properly

async def safe_api_call(params): """ Safe API call with proper error handling

Error codes based on official documentation
"""
try:
    response = await api_client.call(params)

    # Success codes from docs
    if response.status_code == 200:
        return response.data

    # Error codes from official docs
    elif response.status_code == 400:
        raise BadRequestError("Invalid parameters")
    elif response.status_code == 401:
        raise AuthenticationError("Invalid API key")
    elif response.status_code == 429:
        raise RateLimitError("Rate limit exceeded")
    else:
        raise APIError(f"Unexpected error: {response.status_code}")

except Exception as e:
    logger.error(f"API integration error: {e}")
    # Fallback behavior based on requirements
    return None

Environment Configuration

API Keys and Secrets

✅ CORRECT: Use environment variables

import os

ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY") OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") GEMINI_PROJECT_ID = os.getenv("GEMINI_PROJECT_ID")

❌ NEVER hardcode API keys

API_KEY = "sk-abc123..." # NEVER DO THIS

Configuration File

config/third_party.py

class ThirdPartyConfig: """ Third-party API configuration

All values from environment variables
Never commit API keys to git
"""

# ElevenLabs
ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
ELEVENLABS_API_VERSION = os.getenv("ELEVENLABS_API_VERSION", "v2")

# OpenAI
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
OPENAI_ORG_ID = os.getenv("OPENAI_ORG_ID")

# Google
GOOGLE_PROJECT_ID = os.getenv("GOOGLE_PROJECT_ID")
GOOGLE_LOCATION = os.getenv("GOOGLE_LOCATION", "us-central1")

Related Skills

• tdd-workflow - Test-first development for API integrations

• api-development - General API development patterns

• quality-standards - Code quality and testing standards

Quick Reference: Official Docs

Always Check These First

Service Official Docs URL

ElevenLabs Realtime v2 STT https://elevenlabs.io/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime

ElevenLabs TTS https://elevenlabs.io/docs/api-reference/text-to-speech

OpenAI API https://platform.openai.com/docs/api-reference

Google Gemini / Vertex AI https://cloud.google.com/vertex-ai/docs

FastAPI (our framework) https://fastapi.tiangolo.com/

When Docs Change

• Update test comments with new URL

• Verify parameters still match

• Check for breaking changes

• Update configuration if needed

Remember: "When in doubt, RTFM (Read The F***ing Manual)"

Skill Version: v1.0 Last Updated: 2025-12-25 Project: career_ios_backend (Prototype Phase)