explore-api

Files (1)

• SKILL.md

SKILL.md (first lines)

# Explore External API

## Mission
Systematically research external APIs to prevent integration bugs and validate assumptions before implementation.

## When to Use
- Integrating with unfamiliar external APIs or SDKs
- Using new features of existing APIs
- Switching between API versions or providers
- Any time API documentation needs verification

## Research Workflow

### Phase 1: Documentation Discovery
1. **Official Documentation**
   - Primary API reference: [URL]
   - SDK documentation: [URL]
   - Authentication guide: [URL]
   - Rate limits and quotas: [URL]

2. **Compatibility Matrix**
   - Supported versions: [list]
   - Language SDK versions: [list]
   - Known limitations: [list]
   - Deprecation notices: [check]

3. **Community Resources**
   - GitHub issues for known bugs
   - Stack Overflow common problems
   - Blog posts with integration examples

### Phase 2: API Capability Verification
1. **Endpoint/Feature Support**
   - Required feature: [name] - Supported? ✓/✗
   - API method: [name] - Available in version X? ✓/✗
   - Event types (for streaming): [list actual types]

2. **Authentication & Configuration**
   - Auth method: [API key, OAuth, JWT, etc.]
   - Required environment variables: [list]
   - Configuration precedence: [env vars > config file > defaults]

3. **Request/Response Formats**
   - Request parameters: [required, optional, defaults]
   - Response structure: [schema or example]
   - Error response format: [structure]
   - Pagination pattern (if applicable): [method]

### Phase 3: Integration Pattern Research
1. **Official SDK Usage**
   - Initialization pattern: [code example]
   - Basic request example: [code]
   - Error handling pattern: [code]
   - Async/streaming pattern: [code if applicable]

2. **Environment Setup**
   - Import order requirements: [if any]
   - Initialization timing: [when to init client]
   - Configuration loading: [before/during/after init]

3. **Existing Examples**
   - Official examples: [URLs]
   - Working code samples: [URLs]
   - Integration tutorials: [URLs]

### Phase 4: Proof of Concept
Create minimal working example to validate understanding:

```python
# Minimal POC to verify API works as expected
# Test: [what this proves]
```

**Expected Outcome:** [describe success criteria]
**Fallback Plan:** [alternative if POC fails]

### Phase 5: Risk Assessment
1. **Known Issues**
   - Issue: [description]
     - Impact: [high/medium/low]
     - Mitigation: [approach]

2. **Breaking Changes**
   - Version X → Y changes: [list]
   - Migration required: ✓/✗
   - Backward compatibility: ✓/✗

3. **Rate Limits & Quotas**
   - Requests per minute: [limit]
   - Daily quota: [limit]
   - Retry strategy: [approach]

## Output Format

### API Research Document
Create file: `.agents/research/[api-name]-research.md`

Contents:
- API Overview & Version
- Supported Features Matrix
- Integration Patterns & Code Examples
- Configuration Requirements
- Validation Strategy
- Known Issues & Mitigations
- Reference Links

### Quick Reference for Plan
Generate summary block for embedding in plan-feature.md:

```markdown
## API: [Name] v[Version]

**Documentation:** [Primary URL]
**SDK:** [Library] v[Version] - Compatible: ✓/✗

**Key Findings:**
- Feature [X] supported via [method]
- Event type: [actual name] (not [assumed name])
- Requires: [specific config/setup]

From giladresisi/ai-dev-env, MIT.

More from giladresisi/ai-dev-env