wehub-resource-sync
90 lines
3.1 KiB
Markdown
90 lines
3.1 KiB
Markdown
# REST API 5-Minute Preflight Runbook
|
|
|
|
Use this before deep debugging. It catches common Zoom REST API integration failures fast.
|
|
|
|
## Skill Doc Standard Note
|
|
|
|
- Agent-skill standard entrypoint is `SKILL.md`.
|
|
- This runbook is an operational convention (recommended), not a required skill file.
|
|
- `SKILL.md` is also a navigation convention for larger skill docs.
|
|
|
|
## 1) Confirm Auth Flow and Endpoint
|
|
|
|
- Choose matching OAuth flow for use case (S2S/User/PKCE/Device).
|
|
- Use token URL `https://zoom.us/oauth/token`.
|
|
|
|
Wrong flow or token endpoint causes immediate auth failures.
|
|
|
|
## 2) Confirm Scope and Account Context
|
|
|
|
- Verify token contains required scopes.
|
|
- For admin/account-level operations, verify app/account permissions.
|
|
- Re-authorize after scope changes.
|
|
|
|
## 3) Confirm ID Semantics
|
|
|
|
- Distinguish Meeting ID vs Meeting UUID.
|
|
- Apply required URL encoding (double-encoding for UUID where needed).
|
|
|
|
### ID Sanity Rules
|
|
|
|
- Use numeric Meeting ID for many standard meeting operations.
|
|
- Use Meeting UUID for some past-instance/recording/report operations.
|
|
- If endpoint docs mention UUID and your value contains `/` or `+`, encode carefully.
|
|
|
|
If a resource "exists" in UI but API returns not found, ID type/encoding mismatch is a top cause.
|
|
|
|
## 4) Confirm Pagination and Rate Limits
|
|
|
|
- Handle `next_page_token` where applicable.
|
|
- Implement retry/backoff on 429 and transient 5xx.
|
|
|
|
### Minimal Retry Policy
|
|
|
|
- 429 or 5xx: exponential backoff with jitter.
|
|
- Respect retry headers when provided.
|
|
- Put high-volume endpoints behind queue/batch workers.
|
|
|
|
## 5) Confirm Webhook-Driven Workflows
|
|
|
|
- If pipeline is event-driven, validate webhook signatures and retry behavior.
|
|
- Respond quickly and process asynchronously.
|
|
|
|
## 6) Quick Probes
|
|
|
|
- `GET /v2/users/me` succeeds with current token.
|
|
- Representative endpoint (e.g., list meetings) returns expected schema.
|
|
- Error payload includes actionable code/details (not HTML response).
|
|
|
|
### Copy/Paste Validation Commands
|
|
|
|
```bash
|
|
# 1) Get S2S access token
|
|
curl -X POST "https://zoom.us/oauth/token" \
|
|
-H "Authorization: Basic $(printf '%s:%s' "$ZOOM_CLIENT_ID" "$ZOOM_CLIENT_SECRET" | base64)" \
|
|
-H "Content-Type: application/x-www-form-urlencoded" \
|
|
-d "grant_type=account_credentials&account_id=$ZOOM_ACCOUNT_ID"
|
|
|
|
# 2) Validate token can access account context
|
|
curl -X GET "https://api.zoom.us/v2/users/me" \
|
|
-H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"
|
|
|
|
# 3) List meetings for current user (quick schema sanity)
|
|
curl -X GET "https://api.zoom.us/v2/users/me/meetings?page_size=30" \
|
|
-H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"
|
|
```
|
|
|
|
Expected: JSON responses with HTTP 200 (or clear JSON error codes), not HTML error pages.
|
|
|
|
## 7) Fast Decision Tree
|
|
|
|
- **401/invalid token** -> wrong flow, expired token, or scope mismatch.
|
|
- **404-like behavior** -> wrong endpoint path/version or wrong resource ID.
|
|
- **429 spikes** -> missing backoff/queue strategy.
|
|
|
|
## 8) Common Integration Mixups
|
|
|
|
- REST `join_url` is a browser link, not a Meeting SDK join payload.
|
|
- REST API creates/manages Zoom resources; Meeting SDK and Video SDK are separate integration surfaces.
|
|
- If auth works but operation fails, check scope and resource ownership before endpoint debugging.
|