google_youtube_api_v3

Gleam bindings for the YouTube Data API v3, code-generated from Google’s official discovery document.

Each of the 209 API resource types gets its own module under youtube/ with:

• a pub type with one field per API property (all optional, as the API itself treats them),
• schema-specific pub fn <schema>_decoder() functions built on gleam/dynamic/decode, using the original camelCase wire keys,
• matching pub fn <schema>_to_json() encoders,
• a real custom type plus to_string/decoder helpers for every string-enum field (e.g. PrivacyStatusPublic instead of a bare string).

The 32 API resources are grouped into 17 semantic fluent request-builder modules under youtube/api/ (all 83 methods), plus a Sans-IO runtime in google_youtube_api_v3/request (maintained source, not generated):

• video.videos_list(["snippet"]) |> video.videos_list_with_max_results(10) builds params; video.videos_list_request(params) renders a pure Request value (verb, path, query pairs, scopes, optional JSON body),
• request.authorize(req, request.ApiKey(key)) pins credentials,
• request.parse_response(status, body, decoder) decodes success bodies or Google’s standard error object.

This is a Sans-IO library: it never performs I/O. You execute the rendered Request with your own HTTP client — convert it with request.to_http_request into a standard gleam/http record and hand it to any ecosystem client such as gleam_httpc.

Quick Start

Add the package:

gleam add google_youtube_api_v3

The following single-file example uses gleam_httpc as the transport. This package remains Sans-IO and does not add gleam_httpc as a dependency; add it to your application if you want to run this example.

import gleam/httpc
import gleam/result
import gleam/string
import google_youtube_api_v3/request
import google_youtube_api_v3/youtube/api/video as video_api
import google_youtube_api_v3/youtube/video

pub fn most_popular(
  api_key: String,
) -> Result(video.VideoListResponse, String) {
  // 1. Build and authorize the request.
  let api_request =
    video_api.videos_list(["snippet"])
    |> video_api.videos_list_with_chart(
      video_api.VideosListChartMostPopular,
    )
    |> video_api.videos_list_with_max_results(10)
    |> video_api.videos_list_request
    |> request.authorize(request.ApiKey(api_key))

  // 2. Convert it to gleam/http and send it with httpc.
  use response <- result.try(
    api_request
    |> request.to_http_request
    |> httpc.send
    |> result.map_error(string.inspect),
  )

  // 3. Decode the HTTP response with the generated decoder.
  request.parse_response(
    response.status,
    response.body,
    video.video_list_response_decoder(),
  )
  |> result.map_error(string.inspect)
}

Further documentation can be found at https://hexdocs.pm/google_youtube_api_v3/.

Development

gleam test
gleam dev                   # Regenerate from discovery/
gleam format src test

Regenerating wipes and rewrites src/google_youtube_api_v3/youtube, and gleam dev also type-checks the tests — which import the generated modules. If the two drift apart mid-change, move test/generate_test.gleam aside, regenerate, format, and restore it.

Run gleam dev to regenerate the YouTube schema types and API request builders from the JSON document in discovery/. The generator is dev/google_youtube_api_v3_dev.gleam; it uses gleam/dynamic/decode to read the document and gleamgen to write Gleam modules. Regeneration overwrites the generated files under src/google_youtube_api_v3/youtube/, so modify the generator instead of editing those output files directly.

Disclosure: this project is AI-assisted, not vibe-coded. An AI coding agent (via OpenCode) wrote the generator and the generated code under human direction, and a human reviews what gets committed. Every representative generated decoders are exercised by round-trip tests, and gleam build plus gleam test pass clean — trust the test suite, not the author list.