TMDB Java SDK

A modern Java client library for The Movie Database API.

The SDK provides a typed Java API for TMDB resources such as movies, TV series, people, search, discovery, genres, watch providers and configuration metadata.

Features

• Typed Java client for TMDB API v3
• Java 17+
• Builder-based client configuration
• Domain-specific service interfaces
• Typed IDs, language codes and regions
• Query objects for complex request parameters
• SDK-specific exception hierarchy
• Optional Spring Boot starter with autoconfiguration
• Optional Quarkus extension with CDI, health checks, metrics, Dev UI and native-image support

Modules

Module	Description
tmdb-core	Core Java SDK without framework dependencies
tmdb-spring-boot-starter	Spring Boot auto-configuration for the SDK
quarkus-tmdb	Quarkus extension for the SDK

Requirements

• Java 17 or newer
• A TMDB API read access token

Installation

Maven

<dependency>
    <groupId>dev.reuss.tmdb</groupId>
    <artifactId>tmdb-core</artifactId>
    <version>1.0.0</version>
</dependency>

Spring Boot

<dependency>
    <groupId>dev.reuss.tmdb</groupId>
    <artifactId>tmdb-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Quarkus

<dependency>
    <groupId>dev.reuss.tmdb</groupId>
    <artifactId>quarkus-tmdb</artifactId>
    <version>1.0.0</version>
</dependency>

Plain Java Usage

Create a TmdbClient through the builder:

import dev.reuss.tmdb.TmdbClient;

TmdbClient tmdb = TmdbClient.builder()
        .accessToken("your-access-token")
        .build();

The client exposes domain services:

ApiConfiguration configuration = tmdb.configuration().apiConfiguration();
MovieDetails movie = tmdb.movies().details(MovieId.of(550));
SearchMovieResponse results = tmdb.search().movies(MovieSearchQuery.of("Fight Club"));

Client Configuration

import dev.reuss.tmdb.TmdbClient;
import dev.reuss.tmdb.value.language.Language;
import dev.reuss.tmdb.value.region.Region;

import java.time.Duration;

TmdbClient tmdb = TmdbClient.builder()
        .accessToken("your-access-token")
        .defaultLanguage(Language.of("de-DE"))
        .defaultRegion(new Region("DE"))
        .connectTimeout(Duration.ofSeconds(5))
        .requestTimeout(Duration.ofSeconds(10))
        .build();

Default values:

Option	Default
Base URL	https://api.themoviedb.org/3
Default language	en-US
Connect timeout	5s
Request timeout	10s

Spring Boot Starter

The Spring Boot starter automatically configures a TmdbClient bean.

Configuration

tmdb:
  access-token: ${TMDB_ACCESS_TOKEN}
  default-language: de-DE
  default-region: DE
  connect-timeout: 5s
  request-timeout: 10s

Inject the Client

import dev.reuss.tmdb.TmdbClient;
import org.springframework.stereotype.Service;

@Service
class MovieLookupService {

    private final TmdbClient tmdbClient;

    MovieLookupService(TmdbClient tmdbClient) {
        this.tmdbClient = tmdbClient;
    }
}

Inject Domain Services Directly

The starter also exposes the SDK domain services as Spring beans.

import dev.reuss.tmdb.domain.movie.MovieService;
import org.springframework.stereotype.Service;

@Service
class MovieLookupService {

    private final MovieService movieService;

    MovieLookupService(MovieService movieService) {
        this.movieService = movieService;
    }
}

Actuator Health

If Spring Boot Actuator is on the classpath, the starter registers a tmdb health indicator automatically. The check reports whether the TmdbClient bean is configured; it does not call the external TMDB API.

management.health.tmdb.enabled=true

Actuator Metrics

If Micrometer is available, the starter records TMDB client request metrics automatically. With Spring Boot Actuator, metrics are available through the regular actuator endpoints.

management.endpoints.web.exposure.include=health,metrics,prometheus

For Prometheus output, add micrometer-registry-prometheus to your application and open /actuator/prometheus.

Spring Boot Properties

Property	Default	Description
tmdb.access-token	required	TMDB API read access token
tmdb.base-url	https://api.themoviedb.org/3	TMDB API base URL
tmdb.default-language	en-US	Default language tag, for example en-US or de-DE
tmdb.default-region	none	Default region code, for example US or DE
tmdb.connect-timeout	5s	HTTP connection timeout
tmdb.request-timeout	10s	HTTP request timeout

Quarkus Extension

The Quarkus extension exposes TmdbClient and all SDK domain services as CDI beans.

tmdb.access-token=${TMDB_ACCESS_TOKEN}
tmdb.default-language=de-DE
tmdb.default-region=DE
tmdb.connect-timeout=5s
tmdb.request-timeout=10s

import dev.reuss.tmdb.domain.movie.MovieService;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
class MovieLookupService {

    @Inject
    MovieService movieService;
}

If quarkus-smallrye-health or a Quarkus metrics extension such as Micrometer is present, the extension registers health checks and TMDB client metrics automatically. In dev mode, the TMDB card is available in the Quarkus Dev UI.

Error Handling

The SDK maps transport, mapping and TMDB API errors to SDK-specific exceptions.

All SDK exceptions extend TmdbException.

Common exception types include:

• TmdbClientException
• TmdbApiException
• TmdbUnauthorizedException
• TmdbNotFoundException
• TmdbRateLimitException
• TmdbServerException
• TmdbMappingException

Javadoc

The generated Javadoc is available at:

https://reussio.github.io/tmdb-sdk/

To generate the Javadoc locally:

mvn -pl tmdb-core javadoc:javadoc
open tmdb-core/target/reports/apidocs/index.html

License

This project is licensed under the MIT License.