Читаем документацию

Чтобы получить список самых популярных фильмов, мы можем воспользоваться методом GET/movie/top_rated

Для получения документации и обзора какие параметры необходимо передать необходимо перейти на страницу документации API https://developers.themoviedb.org/3/movies/get-top-rated-movies

Документация с описанными методами будет выглядеть так. Давайте рассмотрим что обозначает каждый из выделенных блоков.

1. Это список методов для той или иной сущности. В данном разделе все методы для работы с фильмами.
2. Тип и название метода – в данном случае метод Get
3. Обязательный параметр, видим что пользователь должен передать api_key
4. Блок с описанием параметров, их типов и возможными значениями
5. Блок с описанием возможного ответа от сервера и модель ответа с типами.

Описываем интерфейс API

Теперь, когда мы знаем как выглядит спецификация метода, давайте опишем метод для получения списка фильмов с самым высоким рейтингом. Для этого необходимо создать интерфейс MovieApiInterface и описать метод getTopRatedMovies. В итоге у вас должно получиться что-то наподобие:

Код проекта вы можете скачать на GitHub 

interface MovieApiInterface {

    @GET("movie/top_rated")
    fun getTopRatedMovies(
        @Query("api_key") apiKey: String,
        @Query("language") language: String
    ): Call<MoviesResponse>
}

Описание метода

Первая строка @GET(“movie/top_rated”) – показывает, что метод top_rated является методом типа GET. А строка в скобках – адрес по которому наше приложение запросит список фильмов. Полную строку мы не указываем, так как базовый url всего сервиса будет передан в методе инициализации клиента Retrofit.

Помимо аннотации @GET у Retrofit есть еще несколько полезных аннотация для описания других типов запросов (@POST, @PUT, @DELETE). В данном случае, по спецификации метод GET – поэтому и аннотацию мы используем @GET.

Описание параметров и результата

Чтобы передать параметры в Retrofit есть также несколько аннотаций. Например

• @Path – подставляет параметр в часть пути API. Например если есть параметр  id то он будет заменен на значение в части пути {id} в URL
• @Query – параметр, который будет в запросе как ключ=значение.
• @Body – полезные данные для POST запросов.
• @Header – используется для передачи значения в хэдере запроса

Как мы видим из документации, для получения списка фильмов мы можем передать несколько параметров типа Query. Например, это могут быть api_key и language. Поэтому помечаем их аннотацией @Query и помечаем типом String как в документации. Теперь нам нужно описать типа результата. Для этого используется интерфейс Call с типом, который возвращает наш API, в данном случае класс MoviesResponse – будет описывать модель ответа метода top_rated.

Вот и все! Мы описали метод для получения фильмов с самым высоким рейтингом @GET(“movie/top_rated”)  и в следующем уроке опишем модель ответа от сервера для данного метода.