# Best Practices

Short recommendations for integrating with the Rad TV API.

## Use DIDs everywhere

Use **DIDs** as the canonical ID for channels and content (e.g. `did:rad.live:channel/<uuid>`, `did:rad.live:content/feature/<id>`). Do not mix raw content-metadata or 12core IDs with DIDs in client flows.

## Channel catalog: use features, not content

Channels do **not** have a legacy `content` field. Use:

* `channel.features(limit, start)`
* `channel.series(limit, start)`
* `channel.episodes(limit, start)`
* `channel.streams(limit, start)`
* `channel.seasons(limit, start)`
* `channel.miniseries(limit, start)`

Catalog types (Feature, Episode, Stream, Serie, Season, Miniseries) implement Likeable and Commentable (id, likes, commentCount, comments).

## Rely on nullability in the schema

The schema uses `!` for non-null fields. Use this when writing clients:

* **Content:** `metadata`, `assets`, `likes`, and `commentCount` are never null. `assets` may have empty `videos`/`images` before upload. `transcodeJob` and `outputAssets` are null when not processing or not available.
* **Single-entity queries:** `channel(id)`, `feature(id)`, `stream(id)`, etc. return **null** when the entity is not found or not accessible. Check for null before using the result.

Generated TypeScript types (from `npm run codegen`) reflect the schema.

## Handle both data and errors

* **GraphQL:** Responses are `{ data?, errors? }`. Always check `response.errors`; the HTTP status may still be 200 when there are field errors. Use `response.data` for the result.
* **REST/Internal:** Success uses `{ data: <payload> }`; errors use `{ errors: [ { message, code? } ] }`.

## Use API keys for automation

For MCP, scripts, or long-lived access, use an **API key** (from `POST /internal/v0/generate-api-key`) instead of a user JWT. JWTs are for user sessions; API keys are for programmatic and IDE integration.

## Discover the schema

Use **introspection** against `POST /graphql` or the Altair playground at `/altair` (in development) to explore the full schema. This helps avoid trial-and-error when building queries.

## Pagination

List queries use `limit` and `start` (offset). There is no cursor-based pagination or total count in the schema. Implement "next page" by incrementing `start` by `limit` until you get fewer results than `limit` or an empty list.