thetvdb-java-api

       

A simple connector for an easy integration of the TheTVDB.com RESTful API in Java projects.

Table of contents

• Introduction
• Technologies
• Features
• Setup
• Code Examples
• Development
• Status
• License

Introduction

With more than 300,000+ TV Series and movies TheTVDB.com is probably one of the largest digital media metadata databases in the world. Moreover, they offer the opportunity to access this vast amount of data on M2M-level by providing a RESTful API, which I think is pretty cool as it enables developers to virtually include all this data into their own applications. However, the majority of these applications will probably intend to actually make some good use of this information in order to create something beneficial for the end user. Talking about Java applications, that's where this connector might come in handy.

One of the main objectives of this little project was to keep the code of these aforementioned applications clean. Communicating with the TheTVDB.com API to gather information is a necessity, but most likely not the end of whatever you're aiming to create. So in order to not bloat the code with opening connections, preparing requests, process and evaluate responses and finally parse its JSON content, all of this may be handled by the thetvdb-java-api connector, leaving you with only a few (but unavoidable) lines of code describing what you actually want to achieve (e.g. query a TV Series by name).

However, where there is light there is also shadow, they say. Simplifying things often means to also restrict their functionality to only some basics. And although this might be quite an acceptable trade-off for many people, there will always be someone who is ruled out from using certain tools due to the need of some more advanced functionality. So another important goal was to promote this simplified usage while maintaining the usability for more complex use-cases at the same time. So it's actually up to the developer whether to query by some common parameters in just a one-liner and to work with the prefabbed Java DTOs or to run more complex queries by providing a set of parameters and maybe even parse the raw JSON content returned by the TheTVDB.com API all by yourself. Your decision!

Technologies

• Java (10) - Class-based, object-oriented programming language
• Apache Maven (3.6.0) - Software project management and comprehension tool

Features

In general, this connector is fully compatible with all available TheTVDB.com API endpoints. However, as new versions of the RESTful API might not always be backwards compatible, each major thetvdb-java-api release is invariantly linked to a specific version of the TheTVDB.com remote API. The API version a specific connector release is using can be derived from its version number. For example, v3.x uses the TheTVDB.com APIv3 whereas the (not yet existent) v4.x would use the upcoming APIv4.

Supported TheTVDB.com APIv3 endpoints (thetvdb-java-api v3.x)

• Authentication
  • /login
  • /refresh_token
• Episodes
  • /episodes/{id}
• Languages
  • /languages
  • /languages/{id}
• Movies
  • /movies/{id}
  • /movieupdates
• Search
  • /search/series
  • /search/series/params
• Series
  • /series/{id}
  • /series/{id} (HEAD)
  • /series/{id}/actors
  • /series/{id}/episodes
  • /series/{id}/episodes/query
  • /series/{id}/episodes/query/params
  • /series/{id}/episodes/summary
  • /series/{id}/filter
  • /series/{id}/filter/params
  • /series/{id}/images
  • /series/{id}/images/query
  • /series/{id}/images/query/params
• Updates
  • /updated/query
  • /updated/query/params
• Users
  • /user
  • /user/favorites
  • /user/favorites/{id} (DELETE)
  • /user/favorites/{id} (PUT)
  • /user/ratings
  • /user/ratings/query
  • /user/ratings/query/params
  • /user/ratings/{itemType}/{itemId}
  • /user/ratings/{itemType}/{itemId}/{itemRating}

WIP: Supported TheTVDB.com APIv4 endpoints (thetvdb-java-api v4.x)

• Artwork Statuses
  • /artwork/statuses
• Artwork Types
  • /artwork/types
• Artwork
  • /artwork/{id}
  • /artwork/{id}/extended
• Award Categories
  • /awards/categories/{id}
  • /awards/categories/{id}/extended
• Awards
  • /awards
  • /awards/{id}
  • /awards/{id}/extended
• Characters
  • /characters/{id}
• Companies
  • /companies
  • /companies/types
  • /companies/{id}
  • /companies/{id}/movies (not yet available)
  • /companies/{id}/episodes (not yet available)
  • /companies/{id}/series (not yet available)
  • /companies/{id}/seriesRollup (not yet available)
• Content Ratings
  • /content/ratings
• Countries
  • /countries (marked for deletion)
  • /countries/{id}/series (not yet available)
  • /countries/{id}/movies (not yet available)
  • /countries/{id}/networks (not yet available)
• Entity Types
  • /entities
• Episodes
  • /episodes
  • /episodes/{id}
  • /episodes/{id}/extended
  • /episodes/{id}/translations/{language}
• Genders
  • /genders
• Genres
  • /genres
  • /genres/{id}
  • /genres/{id}/movies (not yet available)
  • /genres/{id}/series (not yet available)
• Inspiration Types
  • /inspiration/types
• Languages
  • /languages (marked for deletion)
• Lists
  • /lists/{id}/translations/{language}
  • /lists
  • /lists/{id}
  • /lists/{id}/extended
• Login
  • /login
• Movie Statuses
  • /movies/statuses
• Movies
  • /movies
  • /movies/{id}
  • /movies/{id}/extended
  • /movies/filter
  • /movies/{id}/translations/{language}
• People Types
  • /people/types
• People
  • /people
  • /people/{id}
  • /people/{id}/extended
  • /people/{id}/translations/{language}
• Search
  • /search
  • /search/remoteid/{remoteid}
• Seasons
  • /seasons
  • /seasons/{id}
  • /seasons/{id}/extended
  • /seasons/types
  • /seasons/{id}/translations/{language}
• Series
  • /series
  • /series/{id}
  • /series/{id}/artworks
  • /series/{id}/nextAired
  • /series/{id}/extended
  • /series/{id}/episodes/{season-type}
  • /series/{id}/episodes/{season-type}/{lang}
  • /series/filter
  • /series/{id}/translations/{language}
• Series Statuses
  • /series/statuses
• Source Types
  • /source/types
• Updates
  • /updates
• User info
  • /user
  • /user/{id}
• Favorites
  • /user/favorites

The latest documentation can be found here: TheTVDB Java 3.x API

Setup

Maven

The artifact is not available through the central maven repository, but you may still include the connector into your maven project via the jitpack.io repository.

1. Add the JitPack repository to your build file

       <repositories>
           <repository>
               <id>jitpack.io</id>
               <url>https://jitpack.io</url>
           </repository>
       </repositories>

2. Add the dependency

       <dependency>
           <groupId>com.github.m0nk3y2k4</groupId>
           <artifactId>thetvdb-java-api</artifactId>
           <version>3.0.4</version>
       </dependency>

Other build automation tools

For other tools like e.g. gradle please check out the documentation at https://jitpack.io/.

Manually include artifact

In case your build tool isn't supported, or you're not using any build framework at all you can still include the artifact manually as .jar file. The files (with and without dependencies) can either be obtained from the assets section of the corresponding release or by cloning the repository and building the artifacts locally:

mvn clean install

Code Examples

Basics

When it comes to using the connector, there's only one entry point where all your activities start:

com.github.m0nk3y2k4.thetvdb.TheTVDBApiFactory

This class provides factory methods to create all the objects needed for working with the connector, including new API instances, free configurable query parameters and proxies.

So let's create a new API instance using the factory methods.

// "Simple" authentication with API-Key only
TheTVDBApi api = TheTVDBApiFactory.createApi("API_KEY");

// or...

// "Advanced" authentication with API-Key, user key and user name
TheTVDBApi usersApi = TheTVDBApiFactory.createApi("API_KEY", "Userkey", "Username");

Please keep in mind that the username and key are ONLY required for the /user routes.

Now we're going to use the simple API object to actually request data from the TheTVDB.com REST endpoints. First and foremost we have to invoke the /login route once. This will induce the remote API to issue a brand new JSON Web Token which will be needed for further authentication. After we have successfully requested a JWT, we can now go on to actually retrieve some data from the API.

api.login();    // We could also use "api.init()" which does exactly the same

// Set the preferred language. If possible the remote API will return the requested data in this language
// If not set, "en"' is the default
api.setLanguage("it");

// Alternatively: invoking the "/languages" endpoint will get us a list of all supported languages
List<Language> allLanguages = api.getAvailableLanguages();
Language italian = allLanguages.stream()
        .filter(l -> l.getName().equals("italiano")).findFirst().get();
api.setLanguage(italian.getAbbreviation());

The connector comes with some integrated auto-login functionality, which will automatically try to request a new JWT in case the authorization failed. Although this might come in handy at times, it is strongly recommended to manually call "/login" route before requesting any data from the TheTVDB.com API.

As you can see the JSON content received from the remote API has already been mapped into a Language DTO. These objects are available for all routes returning complex values like TV Series information, movies or actors. The actual metadata can be accessed through various getters in the usual object-oriented way.

Finally, let's see how to query for specific information. Let's imagine we would like to get all episodes of season 3 for a specific TV Series. We can do that by using a corresponding set of QueryParameters.

long seriesID = 296762;
QueryParameters query = TheTVDBApiFactory.createQueryParameters();
query.addParameter(Query.Series.AIREDSEASON, "3");

// Use your own custom set of query parameters
List<Episode> seasonThree = api.queryEpisodes(seriesID, query);

System.out.println("Here come all the episodes of season 3:");
seasonThree.stream().forEach(e -> System.out.println(
        e.getAiredSeason() + "." + e.getAiredEpisodeNumber() + ": " + e.getEpisodeName()));

Here come all the episodes of season 3:
3.1: Parce Domine
3.2: The Winter Line
3.3: The Absence of Field
...

For certain use cases the connector provides additional shortcut methods. Querying for a specific season is one of them, so we could do the exact same example with even less code.

long seriesID = 296762;

List<Episode> seasonThree = api.queryEpisodesByAiredSeason(seriesID, 3);

System.out.println("And again, all the episodes of season 3:");
seasonThree.stream().forEach(e -> System.out.println(
            e.getAiredSeason() + "." + e.getAiredEpisodeNumber() + ": " + e.getEpisodeName()));

And again, all the episodes of season 3:
3.1: Parce Domine
3.2: The Winter Line
3.3: The Absence of Field
...

And that's basically it! Go and check out the documentation of the main API interface to find more details on the various endpoint and shortcut methods.

Advanced

We could already see that the connector automatically converts the JSON content into a matching DTO. This is the default behavior as it should be quite suitable for most cases, the so called default layout. However, two additional layouts are available to support a wide variety of operational areas: JSON and Extended

JSON layout

If the prefabbed DTO's do not meet your requirements or if you prefer to take care of the JSON parsing yourself, this is the layout to go with. It supports all basic routes (without shortcut methods though) but instead of mapping the metadata into a DTO it will simply return the raw JSON as it was received from the remote API.

// Create a new API instance the usual way
TheTVDBApi api = TheTVDBApiFactory.createApi("API_KEY");

// Create a JSON layout from the existing API by invoking the "json()" method
TheTVDBApi.JSON jsonApi = api.json();

long seriesID = 296762;
QueryParameters query = TheTVDBApiFactory.createQueryParameters(Map.of(Query.Series.AIREDSEASON, "3"));

JsonNode seasonThreeJSON = jsonApi.queryEpisodes(seriesID, query);
// jsonApi.queryEpisodesByAiredSeason(seriesID, 3);   --> This wont work! Shortcut methods are only available in the default layout

Extended layout

This layout is basically just an extension of the default layout and provides access to additional (though optional) information received from the remote API, namely the "errors" and the "links" JSON nodes. Just like the JSON layout, it supports all basic routes (without shortcut methods). All methods of this layout will return an APIResponse<T> object which wraps the actual metadata DTO together with the error and pagination information.

// Again, create the layout from any existing API
TheTVDBApi.Extended extendedApi = api.extended();

// Get the 2nd page of all episodes for this TV Series (max. 100 per page)
final long page = 2;
QueryParameters query = TheTVDBApiFactory.createQueryParameters()
        .addParameter(Query.Series.PAGE, String.valueOf(page));

APIResponse<List<Episode>> response = extendedApi.queryEpisodes(75760, query);

// Get the metadata. This is actually what the default layout does.
List<Episode> episodesSecondPage = response.getData();

// Errors and Links will not always be available and therefore will be returned as Optionals
response.getErrors().map(Errors::getInvalidQueryParams).ifPresent(System.err::println);
boolean morePages = response.getLinks().map(Links::getLast).map(lastPage -> lastPage > page).orElse(false);

Please note that Errors and Links are not always available but only for certain endpoints. See the TheTVDB.com API documentation for detailed information.

Proxy

The connector will send all requests directly towards the TheTVDB.com RESTful API. In case your runtime environment is not able to access this resource directly, you can instruct the connector to send its requests to a different host which will forward them to the remote API.

Proxy localProxy = TheTVDBApiFactory.createProxy("https", "my.local.proxy", 10000);
TheTVDBApi proxiedApi = TheTVDBApiFactory.createApi("API_KEY", localProxy);

// Data will be requested from "https://my.local.proxy:10000/movies/2559"
Movie excellent = proxiedApi.getMovie(2559);

Development

Build

After cloning the repository the connector can be build via Apache Maven:

mvn clean install

The build process will generate the following content, all stored inside the /target folder:

• Artifacts
  • thetvdb-java-api-{VERSION}.jar contains the actual connector artifact without dependencies
  • thetvdb-java-api-{VERSION}-jar-with-dependencies.jar contains the actual connector artifact will all runtime dependencies included
  • thetvdb-java-api-{VERSION}-javadoc.jar contains the packed JavaDoc documentation
  • thetvdb-java-api-{VERSION}-sources.jar contains the packed source code of the connector
• Documentation
  • Available through the -javadoc.jar artifact or directly at /apidocs/index.html
• Tests
  • jacoco code coverage report available at /site/jacoco/index.html

Integration Tests

Integration tests are not part of the default build process as they are executed against the actual TheTVDB.com remote API and thus require some additional configuration as well as an active Internet connection. Integration tests can be setup and executed with the following steps:

1. Create a new file /src/integration-tests/resources/thetvdbapi.properties and set the TheTVDB.com API-Key, user key and user name you'd like to be used for the tests. You can use the available thetvdbapi.properties.sample file as a template.

2. Build the project with the integration-tests maven profile:

   mvn verify -P integration-tests

3. OPTIONAL: Instead of providing the authentication settings via the thetvdbapi.properties file you may also set them directly as command line arguments:

   mvn verify -P integration-tests -Dintegration.thetvdb.com.v3.apikey=APIKEY -Dintegration.thetvdb.com.v3.userkey=USERKEY -Dintegration.thetvdb.com.v3.username=USERNAME

Status

Project is: in progress

Ongoing development of a connector compliant to the upcoming TheTVDB.com APIv4 interface.

License

This project is licensed under the Apache License, Version 2.0

Bear in mind that you might have to negotiate a distinct license model with TheTVDB.com, LLC., e.g. when using their API service as part of a commercial product.