Retrofit android что это такое

Retrofit

Многие сайты имеют собственные API для удобного доступа к своим данным. На данный момент самый распространённый вариант — это JSON. Также могут встречаться данные в виде XML и других форматов.

Библиотека Retrofit упрощает взаимодействие с REST API сайта, беря на себя часть рутинной работы.

Авторами библиотеки Retrofit являются разработчики из компании «Square», которые написали множество полезных библиотек, например, Picasso, Okhttp, Otto.

Библиотекой удобно пользоваться для запроса к различным веб-сервисам с командами GET, POST, PUT, DELETE. Может работать в асинхронном режиме, что избавляет от лишнего кода.

В основном вам придётся работать с методами GET и POST. Если вы будет создавать собственный API, то будете использовать и другие команды.

В Retrofit 2.x автоматически подключается библиотека OkHttp и её не нужно прописывать отдельно.

Библиотека может работать с GSON и XML, используя специальные конвертеры, которые следует указать отдельно.

Затем в коде конвертер добавляется с помощью метода addConverterFactory().

Список готовых конвертеров:

• Gson: com.squareup.retrofit2:converter-gson
• Jackson: com.squareup.retrofit2:converter-jackson
• Moshi: com.squareup.retrofit2:converter-moshi
• Protobuf: com.squareup.retrofit2:converter-protobuf
• Wire: com.squareup.retrofit2:converter-wire
• Simple XML: com.squareup.retrofit2:converter-simplexml
• Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

Также вы можете создать свой собственный конвертер, реализовав интерфейс на основе абстрактного класса Converter.Factory.

Можно подключить несколько конвертеров (порядок важен).

Если вы хотите изменить формат какого-нибудь JSON-объекта, то это можно сделать с помощью GsonConverterFactory.create():

Базовый URL всегда заканчивается слешем /. Задаётся в методе baseUrl().

Можно указать полный URL в запросе, тогда базовый URL будет проигнорирован:

Для работы с Retrofit понадобятся три класса.

1. POJO (Plain Old Java Object) или Model Class — json-ответ от сервера нужно реализовать как модель
2. Retrofit — класс для обработки результатов. Ему нужно указать базовый адрес в методе baseUrl()
3. Interface — интерфейс для управления адресом, используя команды GET, POST и т.д.

Работу с Retrofit можно разбить на отдельные задачи.

Задача первая. POJO

Задача первая — посмотреть на структуру ответа сайта в виде JSON (или других форматов) и создать на его основе Java-класс в виде POJO.

POJO удобнее создавать с помощью готовых веб-сервисов в автоматическом режиме. Либо можете самостоятельно создать класс, если структура не слишком сложная.

В классе часто используются аннотации. Иногда они необходимы, иногда их можно пропустить. В некоторых случаях аннотации помогают избежать ошибок. Список аннотаций зависит от типа используемого конвертера, их список можно посмотреть в соответствующей документации.

Задача вторая. Интерфейс

Задача вторая — создать интерфейс и указать имя метода. Добавить необходимые параметры, если они требуются.

В интерфейсе задаются команды-запросы для сервера. Команда комбинируется с базовым адресом сайта (baseUrl()) и получается полный путь к странице. Код может быть простым и сложным. Можно посмотреть примеры в документации.

Запросы размещаются в обобщённом классе Call с указанием желаемого типа.

В большинстве случаев вы будете возвращать объект Call с нужным типом, например, Call . Если вас не интересует тип ответа, то можете указать Call .

Здесь также используются аннотации, но уже от самой библиотеки.

С помощью аннотации указываются веб-команды, а затем Java-метод. Для динамических параметров используются фигурные скобки (users//repos), в которые подставляются нужные значения.

В самой аннотации используется метод, используемый на сервере, а ниже вы можете указать свой вариант (полезно для соответствия стилю вашего кода.

Аннотации

Аннотация	Описание
@GET()	GET-запрос для базового адреса. Также можно указать параметры в скобках
@POST()	POST-запрос для базового адреса. Также можно указать параметры в скобках
@Path	Переменная для замещения конечной точки, например, username подставится в в адресе конечной точки
@Query	Задаёт имя ключа запроса со значением параметра
@Body	Используется в POST-вызовах (из Java-объекта в JSON-строку)
@Header	Задаёт заголовок со значением параметра
@Headers	Задаёт все заголовки вместе
@Multipart	Используется при загрузке файлов или изображений
@FormUrlEncoded	Используется при использовании пары «имя/значение» в POST-запросах
@FieldMap	Используется при использовании пары «имя/значение» в POST-запросах
@Url	Для поддержки динамических адресов

@Query

Аннотация @Query полезна при запросах с параметрами. Допустим, у сайте есть дополнительный параметр к запросу, который выводит список элементов в отсортированном виде: http://example.com/api/v1/products/cats?sort=desc. Это несложный пример и мы можем поместить запрос с параметром в интерфейс без изменений.

Если не требуется управлять сортировкой, то её можно оставить в коде и она будет применяться по умолчанию. Но в нашем запросе есть ещё один параметр, который отвечает за категорию котов (домашние, уличные, породистые), которая может меняться в зависимости от логики приложения. Этот параметр можно снабдить аннотацией и программно управлять в коде.

Сортировку мы оставляем как есть, а категорию перенесли в параметры метода под именем categoryId, снабдив аннотацией, с которой параметр будет обращаться на сервер в составе запроса.

Запрос получится в виде http://example.com/api/v1/products/cats?sort=desc&category=5.

В одном методе можно указать несколько Query-параметров.

Запрос может иметь изменяемые части пути. Посмотрите на один из примеров запроса для GitHub: /users/:username. Вместо :username следует подставлять конкретные имена пользователей (https://api.github.com/users/alexanderklimov). В таких случаях используют фигурные скобки в запросе, в самоме методе через аннотацию @Path указывается имя, которое будет подставляться в путь.

@Headers

Пример аннотации @Headers, которая позволяет указать все заголовки вместе.

@Multipart

Пример аннотации @Multipart при загрузке файлов или картинок:

@FormUrlEncoded

Пример использования аннотации @FormUrlEncoded:

Пример аннотации @Url:

Задача третья. Retrofit

Для синхронного запроса используйте метод Call.execute(), для асинхронного — метод Call.enqueue().

Объект для запроса к серверу создаётся в простейшем случае следующим образом

В итоге мы получили объект Retrofit, содержащий базовый URL и способность преобразовывать JSON-данные с помощью указанного конвертера Gson.

Далее в его методе create() указываем наш класс интерфейса с запросами к сайту.

После этого мы получаем объект Call и вызываем метод enqueue() (для асинхронного вызова) и создаём для него Callback. Запрос будет выполнен в отдельном потоке, а результат придет в Callback в main-потоке.

В результате библиотека Retrofit сделает запрос, получит ответ и производёт разбор ответа, раскладывая по полочкам данные. Вам остаётся только вызывать нужные методы класса-модели для извлечения данных.

Основная часть работы происходит в onResponse(), ошибки выводятся в onFailure() (неправильный адрес сервера, некорректные формат данных, неправильный формат класса-модели и т.п). HTTP-коды сервера (например, 404) не относятся к ошибкам.

Метод onResponse() вызывается всегда, даже если запрос был неуспешным. Класс Response имеет удобный метод isSuccessful() для успешной обработки запроса (коды 200хх). В ошибочных ситуациях вы можете обработать ошибку в методе errorBody() класса ResponseBody.

Другие полезные методы Response.

• code() — HTTP-код ответа
• body() — сам ответ в виде строки, без сериализации
• headers() — HTTP-заголовки
• message() — HTTP-статус (или null)
• raw() — сырой HTTP-ответ

Можно написать такую конструкцию.

Для отмены запроса используется метод Call.cancel().

Перехватчики (Interceptors)

В библиотеку можно внедрить перехватчики для изменения заголовков при помощи класса Interceptor из OkHttp. Сначала следует создать объект перехватчика и передать его в OkHttp, который в свою очередь следует явно подключить в Retrofit.Builder через метод client().

Поддержка перехватчиков/interceptors для обработки заголовков запросов, например, для работы с токенами авторизации в заголовке Authorization.

HttpLoggingInterceptor

Библиотека HttpLoggingInterceptor является частью OkHttp, но поставляется отдельно от неё. Перехватчик следует использовать в том случае, когда вам действительно нужно изучать логи ответов сервера. По сути библиотека является сетевым аналогом привычного LogCat.

Подключаем перехватчик к веб-клиенту. Добавляйте его после других перехватчиков, чтобы ловить все сообщения. Существует несколько уровней перехвата данных: NONE, BASIC, HEADERS, BODY. Последний вариант самый информативный, пользуйтесь им осторожно. При больших потоках данных информация забьёт весь экран. Используйте промежуточные варианты.

RxJava

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

Источник

Пример использования Retrofit 2 в приложениях Android

Привет! В этой статье мы будем разбираться как работать с библиотекой Retrofit, которая призвана значительно сократить трудозатраты при работе с API веб-сервисов, а также напишем простой пример использования Retrofit 2 в тестовом приложении.

1.Retrofit. Что это?

Retrofit – это REST клиент для android и Java от компании Square. Он может относительно легко получать и разбирать JSON (или другие структуированные данные) через вебсервисы, использующие REST. В Retrofit для (де)сериализации данных используются конверторы, которые необходимо указывать вручную. Типичным конвертором для JSON формата является библиотека GSon, но вы можете воспользоваться кастомным конвертером для обработки XML или прочих протоколов. Для HTTP запросов Retrofit использует OkHttp библиотеку.

Вы можете создать Java объекты основанные на JSON через сервис по ссылке http://www.jsonschema2pojo.org/

Для работы с Retrofit нам потребуется выполнить три шага:

1)Создать класс модели, который будет перегоняться в JSON

2)Создать интерфейс, определяющий возможные HTTP Операции (API)

3)Настроить Retrofit с помощью Retrofit.Builder класса.

Сейчас наверняка вам ничего не понятно, но далее на примерах всё встанет на свои места.

Каждый метод из интерфейса (созданного на шаге 2) представляет одну реализацию вызова API вебсервиса. Метод должен иметь HTTP аннотацию(GET, POST, и т.д.) для указания типа запроса и URL адрес. Возвращаемое значение оборачивается в ответе в Call объект, параметризованный типом ожидаемого результата(нашей моделью из 1 шага).

Вы можете менять части и параметры URL для настройки запроса. Замена части URL выполняется с помощью фигурных скобок <> . С помощью аннотации @Path мы связываем значение параметра метода со значtнием из скобок <> в аннотации.

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

Аннотация @Body на параметре метода заставит Retrofit использовать объект как тело запроса.

2.Retrofit конверторы и адаптеры.

2.1 Конверторы.

Retrofit может быть настроен с использованием специфичных конверторов. Задача конверторов – выполнить (де)сериализацию объектов. Некоторые конверторы для различных преобразований данных:

Для преобразования в JSON и обратно:

• Gson: com.squareup.retrofit:converter-gson
• Jackson: com.squareup.retrofit:converter-jackson
• Moshi: com.squareup.retrofit:converter-moshi

Для работы с протоколами сереализации (Protocol Buffers):

• Protobuf: com.squareup.retrofit:converter-protobuf
• Wire: com.squareup.retrofit:converter-wire

Ну и для работы с XML (куда же без него…):

Simple XML: com.squareup.retrofit:converter-simplexml

Ну а если вам захотелось каких то особых извращений или пришлось работать с неким специфичным протоколом – всегда можно создать собственный конвертор, унаследовавшись от класса Converter.Factory

2.2 Retrofit адаптеры

Ретрофит можно расширить адаптерами для связи с такими библиотеками как RxJava 2.x, Java 8 и Guava.

С выбором адаптеров можете ознакомиться на Гитхабе square/retrofit/retrofit-adapters/

Для примера RxJava 2.x адаптер может быть добавлен с помощью Gradle:

Или используя Maven

Добавление адаптера в коде выглядит примерно таким методом

С этим адаптером будут добавлены Retrofit интерфейсы, способные возвращать RxJava 2.x типы, например Observable, Flowable или Single и т.д.

Аутентификация в Retrofit

Аутентификация может производиться как используя логин с паролем(Http Basic authentication), так и с применением токенов.

Существует 2 пути для обработки процедуры аутентификации. Первый – использование заголовков с помощью аннотаций. Второй – использование интерцепторов OkHttp. Посмотрим как с этим работать.

3.1 Аутентификация с помощью аннотаций.

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

С помощью аннотации @Header(«Authorization») мы просим Retrofit добавить поле Authorization в заголовок запроса со значением, предоставленным в параметре credentials.

Для создания данных пользователя(credentials) мы можем использовать класс Credentials из библиотеки OkHttp, а именно его метод basic(String, String). Как видно из сигнатуры, этот метод получает логин с паролем и возвращает данные для проверки подлинности

Если вы хотите использовать токен, просто вызовите метод getUserDetails(String)

3.2 Аутенфитикация с OkHttp интерцепторами.

Если у вас много вызовов, использующих аутентификацию, то стоит задуматься о использовании интерцепторов. Интерцептор используется для модификации каждого запроса перед его использованием и меняет его заголовок. Преимущество тут заключается в том, что вам не приходится добавлять аннотации @Header(«Authorization») в каждый вызов методов API.

Что бы добавить интерцептор, вы должны выполнить метод okhttp3.OkHttpClient.Builder.addInterceptor(Interceptor):

Созданный okHttpClient должен быть добавлен как ваш Retrofit клиент в методе retrofit2.Retrofit.Builder.client(OkHttpClient)

Как и в примере с аутенфификацией с помощью аннотаций, вы можете пользоваться токеном везде, где используется класс Credentials

А теперь давайте создадим на android приложение, которое будет выгребать с сайта umori.li анекдоты с помощью Retrofit. Пример будет довольно примитивный и несет в себе лишь цель понять, как необходимо взаимодействовать с основными частями библиотеки.

Итак, помните я в начале упоминал про 3 сущности? Давайте поочередно их создавать. Первая — класс-модель. Воспользуемся сервисом http://www.jsonschema2pojo.org/ для получения класса AnekdotModel. Для этого идём по адресу http://www.umori.li/api, знакомимся с API, делаем запрос http://www.umori.li/api/get?site=anekdot.ru&name=new+anekdot&num=1 , и вставляем результат ответа уже в наш чудо-сервис. Выбираем JSON, стиль аннотаций Gson, включение сеттеров и геттеров. В результате получаем класс-модель, отражающий данные, которые будут приходить по сети.

С первым разобрались. Перед созданием второй сущности – интерфейса с описанием будущего API, давайте подключим библиотеку Retrofit в наше приложение. Для этого в Gradle необходимо добавить

Есть так же способы подключения библиотеки с помощью Maven или добавления Jar файла, с ними можете ознакомиться на сайте разработчиков библиотеки.

Приступим к созданию интерфейса с API. Он будет состоять из метода получения портянки с анекдотами.

Взглянув на аннотации, мы видим что будет использоваться метод GET, который к базовому URL добавит /api/get?name=”первый параметр”&num=”второй параметр”.

Третья сущность – класс, в котором будем инициализировать Retrofit. Назовем его Controller. Дёргая его за метод getApi мы получаем готовый экземпляр реализации нашего API, который описывали на втором шаге.

Теперь нам осталось собрать все части в единое целое. Получаемыми данными в активности будем наполнять RecyclerView, часть Gradle с нужыми библиотеками в результате выглядит так

Также не забываем добавить в файл манифеста разрешения на прогулки по интернету.

Создаем файлы разметки для активити и элемента списка RecyclerView:

Для работы с RecyclerView пишем адаптер. Надеюсь написание всех побочных вещей не вызывает у вас вопросов. Но если вы впервые видите RecyclerView, то можете прочитать о принципах работы с ней тут.

Ну и сам класс MainActivity, где вся магия обретает жизнь:

Закомментирован участок где демонстрируется синхронный вариант вызова. Но вы же знаете, что в главном потоке не кошерно вызывать методы, которые могут подвесить UI, так что пользуйтесь им в бэкграунде по необходимости.

Подведя итог можно выделить следующие фазы написания приложения:

А) Подготовительная. Добавление зависимостей в Gradle, разрешений на работу сетью.

Б) Создание модели данных, так называемого POJO объекта(англ. Plain Old Java Object — «старый добрый Java-объект»). Выполняем запрос к ресурсу, ответ вставляем в один из сервисов(например http://www.jsonschema2pojo.org/) и забираем готовую модель. Можете и вручную описать класс, это уже на ваше усмотрение.

В) Реализация инициализации retrofit’а. Тут вы сами вольны принять архитектурныое решение и разместить инициализацию где вашей душе угодно. Можете сделать это в отдельном контроллере, как в коде выше, в централизованном месте(например в классе App, кунаследовавшись от Application), или же выполнить реализацию в активити, непосредственно перед использованием библиотеки.

Г) Вызов методов API из реализации модели, которую построит при инициализации Retrofit.Builder и обработка результатов их работы. Размещение данных для показа пользователю, запись в базу данных, построение графика и т.д.

Согласитесь, Retrofit отлично справляется с задачей сокрытия низкоуровневых вызовов, оставляя нам методы API и обработку их обратных вызовов. Надеюсь, что вы сможете избежать массы костылей при работе с сетью, используя эту чудесную библиотеку!

Источник