# API conventions and coverage

`tuber` uses one naming and return-value grammar across its public API.

## Function names

`list_*()` functions correspond to YouTube list endpoints. They retrieve a collection and usually support pagination. `get_*()` functions return a derived, enriched, or singular result. Write functions use the operation as the verb, such as `create_playlist()`, `upload_video()`, `delete_comment()`, and `set_video_thumbnail()`.

The resource noun follows the verb. Names use full words where the API concept is not already familiar: `list_video_categories()` rather than an abbreviation, and `get_video_stats()` rather than a generic `get_stats()`.

## Arguments

Arguments use snake case. Plural ID arguments accept vectors, while singular ID arguments accept one value. Functions that expose several YouTube filters require exactly one primary filter and report conflicting combinations before making a request.

`max_results` always limits the total number of returned items. The function may make several requests because YouTube caps individual response pages. `page_token` selects the first page when a caller needs to resume a previous request.

Public reads use `auth = "key"` by default. Pass `auth = "token"` when the resource is private. Functions that always require OAuth, including writes and owner-only reads, do not expose an `auth` choice.

## Return values

Collection functions return a data frame by default and a collected API response when `simplify = FALSE`. Fixed simplified schemas use snake-case columns and preserve their columns even when no rows are returned.

`get_video_details()` is the deliberate exception. Its columns depend on the requested `part` values and retain YouTube’s field names. Use `simplify = FALSE` when you need the nested video resource or an owner-only part.

Write functions return the created or updated API resource. Upload functions return the final HTTP response, the parsed resource, and the relevant YouTube URL. Delete functions return the HTTP response invisibly.

## Endpoint coverage

The table records the public wrappers in this release. It is a support matrix, not a claim that `tuber` implements the entire YouTube API.

Resource | Read and analysis | Write
--- | --- | ---
Channels | `get_channel_details()`, `get_my_channel()`, `list_channel_activities()`, `list_channel_videos()` | `insert_channel_banner()`
Channel sections | `list_channel_sections()` | `delete_channel_section()`
Videos | `get_video_details()`, `get_video_stats()`, `list_popular_videos()`, `list_my_videos()` | `upload_video()`, `update_video_metadata()`, `set_video_thumbnail()`, `delete_video()`
Playlists | `list_playlists()`, `list_playlist_items()`, ID helpers | `create_playlist()`, `change_playlist_title()`, `add_video_to_playlist()`, delete functions
Comments | `list_comment_threads()`, `list_comments()`, `get_all_comments()` | `post_comment()`, `reply_to_comment()`, moderation and delete functions
Captions | `list_captions()`, `download_caption()` | `upload_caption()`, `delete_caption()`
Search | `yt_search()`, `search_short_videos()` | Not applicable
Live and monetization | `list_live_broadcasts()`, `list_live_chat_messages()`, `list_super_chat_events()`, `list_channel_members()` | Not implemented
Subscriptions | `list_subscriptions()` | Not implemented
Reference data | languages, regions, video categories, and abuse-report reasons | Not applicable

The package does not currently wrap playlist images, watermarks, caption updates, subscription mutations, or the write methods for live-streaming resources. Google has retired related-video search and guide categories, so this release does not expose wrappers for those endpoints.

## Renamed functions in 2.0.0

Version 2.0.0 removes ambiguous abbreviations and applies the `list_*()` rule.

Before 2.0.0 | 2.0.0
--- | ---
`get_comments()` | `list_comments()`
`get_comment_threads()` | `list_comment_threads()`
`get_playlist_items()` | `list_playlist_items()`
`get_playlists()` | `list_playlists()`
`get_subscriptions()` | `list_subscriptions()`
`get_live_chat_messages()` | `list_live_chat_messages()`
`get_super_chat_events()` | `list_super_chat_events()`
`get_stats()` | `get_video_stats()`
`get_channel_stats()` | `get_channel_details()`
`list_videos()` | `list_popular_videos()`
`list_videocats()` | `list_video_categories()`
`list_langs()` | `list_languages()`
`get_captions()` | `download_caption()`