Package com.github.m0nk3y2k4.thetvdb.api

Interface TheTVDBApi

  • All Known Implementing Classes:
    TheTVDBApiImpl
    public interface TheTVDBApi
    Main interface of the TheTVDB API connector.


    This interface provides access to all available routes of the remote TheTVDB.com REST API. Routes which accept additional optional and mandatory query parameters can either be invoked with a given set of QueryParameters or via some predefined shortcut-methods. These shortcut-methods will accept certain values as direct method parameters which will then be forwarded to the REST API as regular URL query parameters. Please note that shortcut-methods exist for most of the common query scenarios but maybe not for all. In case of more complex query setups the user has to take care of creating a properly configured QueryParameters object, which is slightly more effort than using the shortcut-methods but gives the user unlimited configuration options.


    In order to create a new API instance the TheTVDBApiFactory should be used. This factory also provides additional helper methods, for example to easily create new QueryParameters.


    To cover a wide range of possible applications, this API connector provides multiple layouts in order to allow an easy integration regardless of your actual project requirements. It gives you the option to use prefabbed DTO's which will be parsed from the actual JSON returned by the remote service. In case you need advanced exception handling or you prefer to parse the JSON into your own data models (or don't want to parse it at all), other API layouts will provide you with extended API response DTO's or even with the raw JSON. The following API layouts are currently available:

    • TheTVDBApi
      This is probably the most common layout. It provides various shortcut-methods and automatically maps the received JSON data content into simple Java DTO's (at least for more complex response data). The user does not have to worry about JSON parsing but can simply work with the returned DTO's like he works with every other Java object. However, these objects do only contain the actually requested data and will not include any additional contextual information that may be returned by the remote service (e.g. Pagination information, additional validation or error data). Furthermore they will only provide access to properties that are formally declared by the API (version "v3.0.0") .
    • TheTVDBApi.Extended
      This layout may be used for slightly advance API integration. Like the common layout it'll take care of parsing the received JSON into Java DTO's but it will also provide access to any additional contextual information. Methods of this layout will always return a single APIResponse object which consists of the actual data, parsed as DTO, as well as all additional information which is available in the given context, like additional error or pagination information. This layout does not provide any shortcut-methods.
    • TheTVDBApi.JSON
      This layout may be used if you do not want any post-processing being applied to the actual remote service response data. All methods within this layout will return the raw, unmodified JSON data as it was received from the API. This might be useful if you prefer to map the JSON data yourself, want to use your own Java data models or if you don't want to parse the JSON data at all (but forward it to some other service for example). It would also be the preferred layout in case you need access to additional (e.g. experimental) properties that are not yet officially declared by the formal API description. This layout does not provide any shortcut-methods though.


    Once an API instance has been created, the additional layouts can be accessed via the extended() or json() method.

    • Method Detail

      • init

        void init()
   throws APIException
        Initializes the current API session by requesting a new token from the remote API. This token will be used for authentication of all requests that are sent to the remote service by this API instance. The initialization will be performed based on the constructor parameters used to create this API instance. Actually this method will do the same as login().
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

      • init

        void init​(@Nonnull
          String token)
   throws APIException
        Initializes the current API with the given token. This token will be used for authentication of all requests that are sent to the remote service by this API instance. The given string must be a valid Base64 encoded token in the regular JWT format "{header}.{payload}.{signature}".


        If the given token is (or becomes) expired it will be replaced by a new JWT automatically. The new token will be requested from the remove service based on the constructor parameters used to create this API instance.

        Parameters:
        token - JSON Web Token to be used for remote API communication/authorization
        Throws:
        APIException - If the given string does not match the JSON Web Token format

      • getToken

        Optional<String> getToken()
        Returns the JSON Web Token used for authentication of all requests that are sent to the remote service by this API instance. If the current API has not yet been initialized an empty Optional instance will be returned.
        Returns:
        The JWT used by this API or an empty Optional if the API has not been initialized

      • setLanguage

        void setLanguage​(String languageCode)
        Sets the preferred language to be used for communication with the remote service. Some of the API calls might use this setting in order to only return results that match the given language. If available, the data returned by the remote API will be translated to the given language. The default language code is "en". For a list of supported languages see getAvailableLanguages().
        Parameters:
        languageCode - The language in which the results are to be returned
        See Also:
        getAvailableLanguages()

      • login

        void login()
    throws APIException
        Initializes the current API session by requesting a new token from the remote API. This token will be used for authentication of all requests that are sent to the remote service by this API instance. The initialization will be performed based on the constructor parameters used to create this API instance. It is recommended to login/initialize the session before making the first API call. However, if an API call is made without proper initialization, an implicit login will be performed.


        Corresponds to remote API route: [POST] /login

        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

      • refreshToken

        void refreshToken()
           throws APIException
        Refreshes the current, valid JWT session token. This method can be used to extend the expiration date (24 hours) of the current session token without the need of a complete new login.


        Corresponds to remote API route: [GET] /refresh_token

        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

      • getLanguage

        Language getLanguage​(long languageId)
              throws APIException
        Returns further language information for a given language ID mapped as Java DTO. The language abbreviation can be used to set the preferred language for the communication with the remote service (see setLanguage(String).


        Corresponds to remote API route: [GET] /languages/{id}

        Parameters:
        languageId - The ID of the language
        Returns:
        Mapped Java DTO containing detailed language information based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if the given language ID does not exist.
        See Also:
        TheTVDBApi.JSON.getLanguage(languageId), TheTVDBApi.Extended.getLanguage(languageId)

      • searchSeriesByName

        List<SeriesSearchResult> searchSeriesByName​(@Nonnull
                                            String name)
                                     throws APIException
        Search for series by name. Returns a list of series search results mapped as Java DTO. The search results contain basic information of all series matching the given name. This is a shortcut-method for searchSeries(queryParameters) with a single "name" query parameter.
        Parameters:
        name - The name of the series to search for
        Returns:
        List of series search results mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

      • searchSeriesByImdbId

        List<SeriesSearchResult> searchSeriesByImdbId​(@Nonnull
                                              String imdbId)
                                       throws APIException
        Search for series by IMDB-Id. Returns a list of series search results mapped as Java DTO. The search results contain basic information of all series matching the given IMDB-Id. This is a shortcut-method for searchSeries(queryParameters) with a single "imdbId" query parameter.
        Parameters:
        imdbId - The IMDB-Id of the series to search for
        Returns:
        List of series search results mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

      • searchSeriesByZap2itId

        List<SeriesSearchResult> searchSeriesByZap2itId​(@Nonnull
                                                String zap2itId)
                                         throws APIException
        Search for series by Zap2it-Id. Returns a list of series search results mapped as Java DTO. The search results contain basic information of all series matching the given Zap2it-Id. This is a shortcut-method for searchSeries(queryParameters) with a single "zap2itId" query parameter.
        Parameters:
        zap2itId - The Zap2it-Id of the series to search for
        Returns:
        List of series search results mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

      • getEpisodes

        List<Episode> getEpisodes​(long seriesId)
                   throws APIException
        Returns the first 100 episodes of a specific series mapped as Java DTO. Note that this method is deterministic and will always return the first result page of the available episodes. This is a shortcut-method for getEpisodes(seriesId, queryParameters) with an empty query parameter.
        Parameters:
        seriesId - The TheTVDB.com series ID
        Returns:
        List of episodes mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.
        See Also:
        getEpisodes(seriesId, page)

      • getEpisodes

        List<Episode> getEpisodes​(long seriesId,
                          long page)
                   throws APIException
        Returns a list of episodes of a specific series mapped as Java DTO. The result list will contain 100 episodes at most. For series with more episodes use the page parameter to browse to a specific result page. This is a shortcut-method for getEpisodes(seriesId, queryParameters) with a single "page" query parameter.
        Parameters:
        seriesId - The TheTVDB.com series ID
        page - The result page to be returned
        Returns:
        List of episodes mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.
        See Also:
        getEpisodes(seriesId)

      • queryEpisodesByAiredSeason

        List<Episode> queryEpisodesByAiredSeason​(long seriesId,
                                         long airedSeason)
                                  throws APIException
        Returns all episodes of a specific series and season mapped as Java DTO. Results will be paginated. Note that this method is deterministic and will always return the first result page of the available episodes. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a single "airedSeason" query parameter.
        Parameters:
        seriesId - The TheTVDB.com series ID
        airedSeason - The number of the aired season to query for
        Returns:
        List of episodes for a specific season, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.
        See Also:
        queryEpisodesByAiredSeason(seriesId, airedSeason, page)

      • queryEpisodesByAiredSeason

        List<Episode> queryEpisodesByAiredSeason​(long seriesId,
                                         long airedSeason,
                                         long page)
                                  throws APIException
        Returns all episodes of a specific series and season mapped as Java DTO. Results will be paginated. For seasons with a high number of episodes use the page parameter to browse to a specific result page. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a "airedSeason" and "page" query parameter.
        Parameters:
        seriesId - The TheTVDB.com series ID
        airedSeason - The number of the aired season to query for
        page - The result page to be returned
        Returns:
        List of episodes for a specific season, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.
        See Also:
        queryEpisodesByAiredSeason(seriesId, airedSeason)

      • queryEpisodesByAiredEpisode

        List<Episode> queryEpisodesByAiredEpisode​(long seriesId,
                                          long airedEpisode)
                                   throws APIException
        Returns all episodes of a specific series, matching the airedEpisode parameter, mapped as Java DTO. Results will be paginated. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a single "airedEpisode" query parameter.


        Note that an aired episode number might be associated with a specific season. If the series consists of more than one season this method will return the matching aired episodes from all the seasons. Use queryEpisodesByAbsoluteNumber(long, long) in order to query for a single episode.

        Parameters:
        seriesId - The TheTVDB.com series ID
        airedEpisode - The number of the aired episode to query for
        Returns:
        List of episodes for a specific season and aired episode number, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.
        See Also:
        queryEpisodesByAbsoluteNumber(seriesId, absoluteNumber)

      • queryEpisodesByAbsoluteNumber

        List<Episode> queryEpisodesByAbsoluteNumber​(long seriesId,
                                            long absoluteNumber)
                                     throws APIException
        Returns a specific episode of a series, mapped as Java DTO. Results will be paginated. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a single "absoluteNumber" query parameter.


        Note that (unlike an aired episode number) an absolute episode number should most likely be unique throughout all episodes of a specific series. So in most cases the returned list will consist of only one element. However, as the remote API doesn't give any guarantees that querying with an "absoluteNumber" parameter always returns one episode record at most this method will return all episode data as received from the remote service.

        Parameters:
        seriesId - The TheTVDB.com series ID
        absoluteNumber - The absolute number of the episode to query for (this is not the episode ID!)
        Returns:
        List of episodes for an absolute episode number, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.
        See Also:
        getEpisode(episodeId)

      • filterSeries

        Series filterSeries​(long seriesId,
                    @Nonnull
                    String filterKeys)
             throws APIException
        Returns a series records, filtered by the supplied comma-separated list of keys, mapped as Java DTO. This is a shortcut-method for filterSeries(seriesId, queryParameters) with a single "keys" query parameter.
        Parameters:
        seriesId - The TheTVDB.com series ID
        filterKeys - Comma-separated list of keys to filter by
        Returns:
        A filtered series record, mapped as Java DTO based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

      • queryImages

        List<Image> queryImages​(long seriesId,
                        @Nonnull
                        String keyType,
                        @Nonnull
                        String resolution)
                 throws APIException
        Returns all images for a specific series, matching the given parameters, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a "keyType" and "resolution" query parameter.


        Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

        Parameters:
        seriesId - The TheTVDB.com series ID
        keyType - Type of image you're querying for (fanart, poster, etc.)
        resolution - Resolution to filter by (1280x1024, for example)
        Returns:
        List of images that matched the given parameters, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.
        See Also:
        queryImages(seriesId, keyType, resolution, subKey)

      • queryImages

        List<Image> queryImages​(long seriesId,
                        @Nonnull
                        String keyType,
                        @Nonnull
                        String resolution,
                        @Nonnull
                        String subKey)
                 throws APIException
        Returns all images for a specific series, matching the given parameters, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a "keyType", a "resolution" and a "subKey" query parameter.


        Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

        Parameters:
        seriesId - The TheTVDB.com series ID
        keyType - Type of image you're querying for (fanart, poster, etc.)
        resolution - Resolution to filter by (1280x1024, for example)
        subKey - Subkey for the other method query parameters
        Returns:
        List of images that matched the given parameters, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.
        See Also:
        queryImages(seriesId, keyType, resolution)

      • queryImagesByKeyType

        List<Image> queryImagesByKeyType​(long seriesId,
                                 @Nonnull
                                 String keyType)
                          throws APIException
        Returns all images of a specific type for a series, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a single "keyType" query parameter.


        Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

        Parameters:
        seriesId - The TheTVDB.com series ID
        keyType - Type of image you're querying for (fanart, poster, etc.)
        Returns:
        List of images of the given key type, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

      • queryImagesByResolution

        List<Image> queryImagesByResolution​(long seriesId,
                                    @Nonnull
                                    String resolution)
                             throws APIException
        Returns all images of a specific resolution for a series, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a single "resolution" query parameter.


        Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

        Parameters:
        seriesId - The TheTVDB.com series ID
        resolution - Resolution to filter by (1280x1024, for example)
        Returns:
        List of images with the given resolution, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

      • queryImagesBySubKey

        List<Image> queryImagesBySubKey​(long seriesId,
                                @Nonnull
                                String subKey)
                         throws APIException
        Returns all images of a specific sub key for a series, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a single "subKey" query parameter.


        Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

        Parameters:
        seriesId - The TheTVDB.com series ID
        subKey - Subkey to query for
        Returns:
        List of images matching the given sub key, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

      • queryLastUpdated

        Map<Long,Long> queryLastUpdated​(QueryParameters queryParameters)
                         throws APIException
        Returns a map of series that have changed in a maximum of one week blocks since the provided fromTime query parameter. The key/value pairs of the returned map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. Note that the given query parameters must always contain a valid fromTime Epoch timestamp key.


        The user may specify an additional toTime query key to grab results for less than a week. Any timespan larger than a week will be reduced down to one week automatically.


        Corresponds to remote API route: [GET] /updated/query

        Parameters:
        queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableLastUpdatedQueryParameters().
        Returns:
        A map of updated objects that match the given timeframe, based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.
        See Also:
        TheTVDBApi.JSON.queryLastUpdated(queryParameters), TheTVDBApi.Extended.queryLastUpdated(queryParameters)

      • queryLastUpdated

        Map<Long,Long> queryLastUpdated​(long fromTime)
                         throws APIException
        Returns a map of series that have changed in the (one) week since the provided fromTime query parameter. The key/value pairs of the returned map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. This is a shortcut-method for queryLastUpdated(queryParameters) with a single "fromTime" query parameter.
        Parameters:
        fromTime - Epoch time to start your date range
        Returns:
        A map of updated objects beginning at the given fromTime, based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.
        See Also:
        queryLastUpdated(fromTime, toTime)

      • queryLastUpdated

        Map<Long,Long> queryLastUpdated​(long fromTime,
                                long toTime)
                         throws APIException
        Returns a map of series that have changed in between the given timeframe, but with a maximum of one week, starting at the provided fromTime query parameter. The toTime parameter may be specified to grab results for less than a week. Any timespan larger than a week will be reduced down to one week automatically. The key/value pairs of the returned map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. This is a shortcut-method for queryLastUpdated(queryParameters) with a "fromTime" and a "toTime" query parameter.
        Parameters:
        fromTime - Epoch time to start your date range
        toTime - Epoch time to end your date range. Must not be greater than one week from fromTime.
        Returns:
        A map of updated objects matching the given timeframe, based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.
        See Also:
        queryLastUpdated(fromTime)

      • getUser

        User getUser()
      throws APIException
        Returns basic information about the currently authenticated user, mapped as Java DTO.


        Corresponds to remote API route: [GET] /user

        Returns:
        Basic user information, mapped as Java DTO based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user
        See Also:
        TheTVDBApi.JSON.getUser(), TheTVDBApi.Extended.getUser()

      • queryRatingsByItemType

        List<Rating> queryRatingsByItemType​(@Nonnull
                                    String itemType)
                             throws APIException
        Returns a list of ratings for a given user that match the itemType parameter, mapped as Java DTO. This is a shortcut-method for queryRatings(queryParameters) with a single "itemType" query parameter.
        Parameters:
        itemType - Item to query. Can be either 'series', 'episode', or 'banner'.
        Returns:
        List of user ratings with the given item type, mapped as Java DTO's based on the JSON data returned by the remote service
        Throws:
        APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

      • json

        TheTVDBApi.JSON json()
        Provides access to the API's JSON layout.


        In this layout, all methods will return the raw, unmodified JSON as received from the remove service.

        Returns:
        Instance representing the the API's JSON layout

      • extended

        TheTVDBApi.Extended extended()
        Provides access to the API's Extended layout.


        In this layout, all methods will return a single APIResponse object, containing the actual request data, mapped as DTO, as well as all additional information that is available in the corresponding context.

        Returns:
        Instance representing the the API's Extended layout