---
name: external-api-contract-validation
description: Validate external API contracts against expected schemas — verify response shapes, required fields, types, error codes, and edge cases for third-party API integrations (Debrid, Stremio addons, Trakt, TMDB, Supabase).
domain: software-development
metadata:
  hermes:
    requires_toolsets: [terminal, web]
---

# External API Contract Validation

Validate third-party API responses against expected schemas to catch breaking changes, mismatches, and regressions before they reach production.

## When to Load

Use this skill when:
- Integrating a new debrid provider (Real-Debrid, Premiumize, AllDebrid, TorBox, EasyDebrid)
- Adding a new Stremio addon to the scraper pipeline
- Verifying Trakt API contract changes after an API version bump
- Testing TMDB API response shapes against your app's models
- Validating Supabase auth/schema responses
- Debugging API response mismatches (e.g., field renamed, type changed, null vs absent)

## Workflow

1. **Identify the API endpoint** and its expected response schema
2. **Fetch a real response** using `curl` or a script with valid auth
3. **Compare against the expected model** — check required fields, types, nullable handling
4. **Test edge cases** — missing auth, expired tokens, invalid IDs, rate limits
5. **Document findings** — what matches, what diverges, what needs defensive handling

## Common Patterns

### Debrid Provider Contracts
- **Real-Debrid**: `addMagnet` response, `torrents/info` status transitions, `unrestrict/link` shape
- **Premiumize**: `cache/check` response, `transfer/directdl` shape, folder structure
- **AllDebrid**: `magnet/upload` response, `magnet/status` polling, `link/streaming` shape

### Stremio Addon Protocol
- `manifest.json` schema — resources, types, idPrefixes, behaviorHints
- `stream/{type}/{id}.json` response — streams array with infoHash, name, title, behaviorHints
- Catalog responses — metas array shape, pagination

### API-Specific Gotchas
- **RD `instantAvailability` is DEPRECATED** — returns error 37, use addMagnet + check status
- **RD API keys contain `!`** — shell escaping required
- **Debrid APIs return MKV links** — browsers can't play MKV natively
- **Some APIs return 200 with error in body** — check `status`/`message` fields, not just HTTP status
- **Null vs missing fields** — some APIs omit optional fields, others send `null`

## Verification

- [ ] All required fields present in real API responses
- [ ] Optional fields handled with safe defaults
- [ ] Error responses parsed correctly (not mistaken for success)
- [ ] Auth failure responses handled gracefully
- [ ] Rate limit responses detected and retried
- [ ] Schema changes documented if API version bumped