#video #tmdb #sans-io #tv #search

tmdb-sans-io

The Movie Database (TMDb) API for Rust, sans io

1 unstable release

Uses new Rust 2024

new 0.1.0 May 5, 2025

#516 in Database interfaces

MIT license

24KB
448 lines

The Movie Database

The Movie Database

This is a fork of tmdb (Cir0X/tmdb-rs), following the sans-io approach to let you build a custom wrapper around TMDb API.

Bring your own I/O stack!

Motivation

Why yet another TMDb API library written in Rust?

For a throw-away hobby project, I needed to access TMDb API:

  • The search on lib.rs lists several crate implementations, great!
  • Looking among the results (at the time of writing) some require async runtimes... but tmdb (Cir0X/tmdb-rs) doesn't, nice!
    • N.B. I'm not hating on async, just for this project pulling an async runtime seemed like overkill. If I did pull in an async runtime, I wanted it to be on my terms.
  • Running cargo audit, it seems one dependency of the chosen library (the latest reqwest version 0.9.24 per the semver range, from 2019-12-11) has security advisories.

The situation is understandable: an older but still working API access library (last updated in 2021) that uses an older version of HTTP client library is bound to have a few security vulnerabilities reported deep in their dependency tree.

Security advisories (in this case, DDOS vulnerabilities) may not be critical for a hobby project but are still not ideal.

Instead of manually patching the API access library to use an updated HTTP client library, why not decouple the API models from the HTTP client?

Credit goes to the original authors for the data models, and API design. Building upon that, the finish method is crudely bolted on, returning an HttpGet struct containing the URL to be queried and a receive_response method to parse the JSON response.

Usage

See examples/basic for sample usage.

See the integration tests for more examples.

NOTE: All code examples are not rigorously checked, for reference only.

Actions

Currently there are 3 actions available:

  • Searching
  • Fetching
  • Finding

Searching

You can search for movies by title and year.

let page_request = tmdb.search()
    .title("Bicentennial Man")
    .year(1999)
    .finish();
let response = {
    let request_url = page_request.request_url();
    unimplemented!("INSERT YOUR HTTP CLIENT LIBRARY HERE");
};
let page = page_request.receive_response(response)?;

let movies = page.results;

Fetching

You can fetch a movie, when you know its ID. Then you get all the movie details.

let movie_request = tmdb.fetch()
    .id(157336)
    .finish();
let response = {
    let request_url = movie_request.request_url();
    unimplemented!("INSERT YOUR HTTP CLIENT LIBRARY HERE");
};
let movie = movie_request.receive_response(response)?;

When you don't have any movie ID, you can search for a movie and then easily fetch the full details.

let page_request = tmdb.search()
   .title("Bicentennial Man")
   .year(1999)
   .finish();
let response = {
    let request_url = page_request.request_url();
    unimplemented!("INSERT YOUR HTTP CLIENT LIBRARY HERE");
};
let page = page_request.receive_response(response)?;

let movies = page.results;
let movie_request = movies[0].fetch(&tmdb);
let response = {
    let request_url = movie_request.request_url();
    unimplemented!("INSERT YOUR HTTP CLIENT LIBRARY HERE");
};
let movie = movie_request.receive_response(response)?;

Furthermore you can request some more data with the append to response feature.

let movie_request = tmdb.fetch()
    .id(2277)
    .append_videos()
    .append_credits()
    .finish();

Finding

Finding a movie with an external ID is currently supported with IMDB IDs.

let find_result = tmdb.find()
    .imdb_id("tt0816692")
    .finish();

let response = {
    let request_url = find_request.request_url();
    unimplemented!("INSERT YOUR HTTP CLIENT LIBRARY HERE");
};
let find_result = find_request.receive_response(response);

let movies = find_result.movie_results;

Acknowledgements

Dependencies

~0.6–1.5MB
~33K SLoC