- Блог Виктора Деревянко
- пятница, 24 января 2014 г.
- REST под Android. Часть 2: разрабатываем API
- Принципы разработки REST API
- Apigee
- Другие ресурсы
- Тестовый пример: набор книг
- Первая попытка описания API: список URL в текстовом файле
- Инструменты для описания API
- Вторая попытка описания API: Apiary.io
- Выводы
- Android для начинающих: использование REST API
- 1. Включение доступа к Интернету
- 2. Создание фоновых потоков
- 3. Создание HTTP-соединения
- 4. Добавление заголовков запросов
- 5. Чтение ответов
- 6. Разбор JSON ответов
- 7. Использование разных HTTP методов
- 8. Кэширование ответов
- Заключение
- ziginsider
- Что такое REST?
- Что такое REST-API?
- Где используется стиль REST в Android?
- Задачи, которые требуется решить при реализации REST-клиента
- Некоторые важные моменты для реализации REST-клиента под Android, согласно паттернам A/B/C
- Алгоритм фомирования запроса к серверу
Блог Виктора Деревянко
О жизни, о программировании. Все публикуемые исходные коды можно взять здесь
пятница, 24 января 2014 г.
REST под Android. Часть 2: разрабатываем API
Прежде чем переходить к разработке тестового проекта на RoboSpice, необходимо определиться с API для тестового проекта. Разумеется, можно взять одно из готовых API — благо их сейчас сотни. Однако гораздо интереснее написать свое, тем более, что это нетривиальный процесс. Рассмотрим, как пишутся REST API, какие инструменты для этого существуют, и попробуем реализовать простейшее тестовое API.
Принципы разработки REST API
Apigee
Там же на отдельной странице собраны примеры готовых REST API (github, twitter и т.д.). Специальная консоль позволяет поработать с выбранным API прямо из браузера.
Другие ресурсы
- Книга RESTful Web APIs (2013) by Leonard Richardson, Mike Amundsen, Sam Ruby.
- REST+JSON API Design — Best Practices for Developers: slides, video
- Best Practices for Designing a Pragmatic RESTful API by Vinay Sahni
- REST and JSON API guidelines and best practices by Niels Krijger — удобная шпаргалка, краткая компиляция из других источников.
- HTTP: The Definitive Guide by David Gourley, Brian Totty, Marjorie Sayer, Anshu Aggarwal, Sailu Reddy. В книге детально рассмотрен HTTP протокол, на котором в большинстве случаев реализуются REST API. Так же HTTP посвящена отдельная глава «HTTP for APIs» в книге «RESTful Web APIs».
Тестовый пример: набор книг
Первая попытка описания API: список URL в текстовом файле
Договоримся, что для формат представления ресурсов можно задавать следующим образом:
Теперь зафиксируем способ обработки ошибок. Будем считать, что в случае успеха сервер возвращает код 200 — OK , в случае ошибки один из следующих кодов: 400 — Bad Request, 500 — Internal Server Error . Для наших целей вполне достаточно, хотя можно задействовать и другие коды.
В случае ошибки сервер обязан вернуть сообщение с расшифровкой ошибки в формате:
Осталось описать формат представления ресурса и списков ресурсов.
- [1] получить полный список книг
- [2] получить информацию о книге
- [3] добавить книгу в набор
- [4] удалить книгу из набора
- [5] редактировать информацию о книге
- [6] провести поиск книг по автору, по названию — аналогично [1]
Инструменты для описания API
Вторая попытка описания API: Apiary.io
В целом, работа с API Blueprint Language не вызвала каких-то особых проблем. Смутил только один момент, с которым так и не удалось разобраться. Я создал ресурс Book: и действия к нему Параметр fields может использоваться только с GET, а в PATCN и DELETE его быть не может. Набор параметров я задаю отдельно для каждого действия. Тем не менее, в документации для Edit и Delete параметр fields присутствует в URL, что несколько сбивает с толку. Причем ниже, в списке возможных параметров, он отсутствует.
Выводы
- Прежде чем разрабатывать собственное REST API, имеет смысл ознакомиться как минимум с Web API Design. Crafting Interfaces that Developers Love (pdf), чтобы не наделать грубых ошибок.
- Сервис apiary.io — весьма функционален. Разрабатывать REST API на нем гораздо удобнее, чем в просто фиксировать список URL в текстовом файле. Возможность проверки реализации на соответствие спецификации и Mock-сервер стоят того, чтобы потратить время на изучение API Blueprint Language.
Цель достигнута — BooksSet REST API для тестового проекта создано. Переходим к разработке проекта. Об этом — в следующий раз.
Mindmap, созданный в процессе работы над этой статьей, можно скачать здесь, в формате Freemind 1.0 (портативная версия: freemind-bin-1.0.0.zip).
Update Mock-сервер Apiary не поддерживает компрессию gzip. Может когда-нибудь сделают, особенно если за эту функцию проголосует достаточное количество пользователей.
Источник
Android для начинающих: использование REST API
Russian (Pусский) translation by Ilya Nikov (you can also view the original English article)
Большинство из нас стали весьма жадны до новой информации, что в Интернете является такой важной частью нашей жизни. Поэтому создание приложений Android со статичным контентом может быть плохой идеей. Вместо этого вам следует рассмотреть возможность создания приложений, которые могут отображать свежий контент каждый раз, когда пользователь их открывает.
Это может звучать сложно, но с большим количеством сайтов, которые раскрывают свои ресурсы через REST API, на самом деле это довольно просто. (Смотрите руководство для начинающих по HTTP и REST для примера.)
В этом уроке я расскажу вам, как использовать классы и методы, доступные в Android SDK, для подключения к удаленным веб-серверам и взаимодействия с ними с использованием их REST API.
1. Включение доступа к Интернету
Использование REST API, очевидно, связано с использованием Интернета. Тем не менее, приложения Android могут получить доступ к Интернету только в том случае, если у них есть разрешение android.permission.INTERNET . Поэтому перед началом написания любого сетевого кода вы должны убедиться, что в файле манифеста вашего проекта присутствуют следующие uses-permission теги:
Поскольку android.permission.INTERNET не считается опасным разрешением, вам не нужно запрашивать его во время выполнения на устройствах с уровнем API 23 или выше.
2. Создание фоновых потоков
Платформа Android не позволяет выполнять сетевые операции в основном потоке приложения. Поэтому весь ваш сетевой код должен принадлежать фоновому потоку. Самый простой способ создать такой поток — использовать метод execute() класса AsyncTask . В качестве единственного аргумента execute() ожидает объект Runnable .
Если вы хотите узнать больше о выполнении операций в фоновом потоке, я предлагаю вам прочитать этот учебник о фоновых операциях из серии Android для начинающих.
3. Создание HTTP-соединения
Используя метод openConnection() класса URL , вы можете быстро настроить соединение с любой конечной точкой REST. Возвращаемое значение openConnection() должно быть передано в экземпляр HttpURLConnection или HttpsURLConnection , в зависимости от доступа к конечной точке через HTTP или HTTPS. Оба HttpURLConnection и HttpsURLConnection позволяют выполнять такие операции, как добавление заголовков запросов и чтение ответов.
В следующем фрагменте кода показано, как настроить соединение с корневой конечной точкой API GitHub:
Обратите внимание, что HttpsURLConnection является подклассом класса HttpURLConnection .
4. Добавление заголовков запросов
Большинство веб-сайтов, предлагающих REST API, хотят иметь возможность однозначно идентифицировать ваше приложение. Самый простой способ помочь им сделать это — включить уникальный заголовок User-Agent во все ваши запросы.
Чтобы добавить заголовок User-Agent в ваш запрос, вы должны использовать метод setRequestProperty() объекта HttpURLConnection . Например, вот как вы устанавливаете заголовок User-Agent в my-rest-app-v0.1:
Вы можете добавить несколько заголовков к своему запросу, вызвав несколько раз метод setRequestProperty() . Например, следующий фрагмент кода добавляет заголовок Accept и кастомный заголовок Contact-Me :
5. Чтение ответов
После того как вы передали все заголовки запросов, вы можете проверить, есть ли у вас валидный ответ, используя метод getResponseCode() объекта HttpURLConnection .
Если класс HttpURLConnection получает код ответа на перенаправление, например 301, он автоматически обрабатывает его и следует за перенаправлением. Поэтому, как правило, вам не нужно будет писать дополнительный код для проверки перенаправления.
В случае отсутствия ошибок вы можете теперь вызвать метод getInputStream() , чтобы получить ссылку на входящий поток соединения.
Большинство REST API в наши дни возвращают данные, отформатированные как документы JSON. Поэтому, вместо прямого чтения из объекта InputStream , я предлагаю вам создать для него InputStreamReader .
6. Разбор JSON ответов
Android SDK имеет класс JsonReader, который позволяет легко разбирать документы JSON. Вы можете создать новый экземпляр класса JsonReader , передав объект InputStreamReader его конструктору.
То как вы извлекаете определенную часть информации из документа JSON, зависит от его структуры. Например, документ JSON, возвращаемый корневой конечной точкой REST API GitHub, выглядит следующим образом:
Как вы можете видеть, ответ — это только один большой объект JSON, содержащий несколько ключей. Чтобы извлечь из него значение с именем organization_url, вам нужно будет написать следующий код:
Вышеупомянутый код обрабатывает ответ JSON как поток токенов. Поэтому он потребляет очень мало памяти. Однако, поскольку он должен обрабатывать каждый отдельный токен один за другим, он может оказаться медленным при обработке больших ответов.
После того как вы извлечете всю необходимую информацию, вы всегда должны вызвать метод close() для объекта JsonReader , чтобы он освобождал все сохраненные ресурсы.
Вы также должны закрыть соединение, вызвав метод disconnect() объекта HttpURLConnection .
7. Использование разных HTTP методов
HTTP-интерфейсы REST используют методы HTTP для определения типа операции, которая должна выполняться над ресурсом. На предыдущих шагах мы использовали метод HTTP GET для выполнения операции чтения. Поскольку класс HttpURLConnection использует по умолчанию метод GET , нам не нужно было его явно указывать.
Чтобы изменить метод HTTP вашего объекта HttpURLConnection , вы должны использовать его метод setRequestMethod() . Например, следующий фрагмент кода открывает соединение с конечной точкой, принадлежащей httpbin.org, и устанавливает свой HTTP-метод в POST :
Как вы уже знаете, POST -запросы используются для отправки данных на сервер. При записи в выходной поток соединения вы можете легко добавить любые данные в тело запроса POST . Однако, прежде чем вы это сделаете, вы должны убедиться, что вы вызываете метод setDoOutput() объекта HttpURLConnection и передаете ему значение true .
В следующем фрагменте кода показано, как отправить на сервер простую пару «ключ-значение»:
8. Кэширование ответов
Всегда рекомендуется кэшировать ответы HTTP. Таким образом, вы можете не только сократить потребление пропускной способности вашего приложения, но и сделать его более отзывчивым. Начиная с уровня API 13, Android SDK предлагает класс HttpResponseCache , который позволяет легко реализовать кэширование без каких-либо изменений в вашей сетевой логике.
Чтобы установить кэш для вашего приложения, вы должны вызвать метод install() класса HttpResponseCache . Метод ожидает абсолютный путь, указывающий, где должен быть установлен кеш, и число, определяющее размер кеша. Вы можете использовать метод getCacheDir() , если вы не хотите указывать абсолютный путь вручную.
В следующем фрагменте кода устанавливается кеш размером 100 000 байт:
Как только кеш установлен, класс HttpURLConnection начинает использовать его автоматически. Чтобы проверить, работает ли ваш кеш, вы можете использовать его метод getHitCount() , который возвращает количество HTTP-ответов, которые были отправлены из кеша.
Заключение
Существуют тысячи REST API-интерфейсов, которые вы можете свободно использовать в своих приложениях для Android. Используя их, вы можете сделать ваше приложение более информативным, интересным и многофункциональным. В этом уроке вы узнали, как использовать класс HttpURLConnection для использования таких REST API. Вы также узнали, как создать кеш ответов HTTP, который снижает использование потребление сетевого трафика вашим приложением.
Если вы считаете, что использование HttpURLConnection слишком сложное, вам следует обратить внимание на сторонние библиотеки, такие как например, Volley. Библиотеки, подобные этой, используют класс HttpURLConnection внутри, но предоставляют множество удобных методов, которые позволяют сделать ваш код более кратким и читаемым.
Чтобы узнать больше о работе с сетью на платформе Android, вы можете обратиться к руководству по сетевым операциям Android.
Источник
ziginsider
17 августа 2017
Что такое REST?
REST — (сокр. от англ. Representational State Transfer — «передача состояния представления») архитектурный стиль взаимодействия компонентов распределённого приложения в сети по модели клиент-сервер. Был разработан в диссертации Роя Филдинга в 200 году, как альтернатива SOAP, когда запрос клиента несет в себе исчерпывающую информацио о желаемом ответе сервера и сервер не обязан сохранять сессию взаимодействия с клиентом.
Особенности архитектурного стиля:
- Каждая сущность должна иметь уникальный идентификатор – URI.
- Сущности должны быть связаны между собой.
- Для чтения и изменения данных должны использоваться стандартные методы.
- Должна быть поддержка нескольких типов ресурсов.
- Взаимодействие должно осуществляться без состояния.
Стандартные методы таковы:
- GET – получение данных без их изменения. Это наиболее популярный и легкий метод. Он только возвращает данные, а не изменяет их, поэтому на клиенте вам не нужно заботиться о том, что вы можете повредить данные.
- POST – метод, подразумевающий вставку новых записей.
- PUT – метод, подразумевающий изменение существующих записей.
- PATCH – метод, подразумевающий изменение идентификатора существующих записей.
- DELETE – метод, подразумевающий удаление записей.
Что такое REST-API?
REST API – это набор удаленных вызовов стандартных методов, возвращающих данные в определенном формате.
Где используется стиль REST в Android?
1) См. реализации различных библиотек REST-клиентов, например: Retrofit, Volley, RoboSpice… См. статью Volley vs Retrofit
Задачи, которые требуется решить при реализации REST-клиента
Перечислим, какие основные задачи придется решать при реализации REST-клиента на Android согласно паттернам Virgil Dobjanschi (Это так называемые паттерны A/B/C, которые описывают способы реализации REST-клиента под Android. Подробней о паттернах на русском можно глянуть здесь (лекция 2) или здесь):
- Управление сервисом: запуск, остановка.
- Передача результатов из сервиса в активити.
- Кэшировать результатов в sqlite.
- Фиксирование статуса данных sqlite перед и после выполнения REST-запроса.
- Запись информации о проводимых REST-операциях в sqlite.
- Парсинг полученных данных.
- Конструирование REST-запроса на основе URI и набора параметров.
- Выполнение сетевых запросов к REST-серверу.
- Чистка базы данных от устаревших данных.
- В случае неудачи REST-запроса, пытаться повторить запрос (например, экспоненциально увеличивая время между запросами).
- Возможность отложенного запуска REST-запроса через SyncAdapter.
Некоторые важные моменты для реализации REST-клиента под Android, согласно паттернам A/B/C
- Данные, полученные от REST-сервера, всегда сохраняются в sqlite. Напрямую в Activity они никогда не передаются. Вместо этого в Activity передается уведомление о том, что данные загружены в sqlite и их можно оттуда загрузить (вариант — Activity получает уведомление об обновлении данных в Content Provider через Content Observer).
- При выполнении операций insert, delete, update данные в sqlite обновляются дважды: первый раз до отправки REST-запроса, второй раз — после получения результата. Первая операций выставляет информационные флаги, сигнализирующие о типе операции, проводимой над данными, и о статусе операции.
- REST-методы следует всегда выполнять в отдельном потоке.
- Следует использовать Apache HTTP client, а не Java URL connection.
- Форматы данных в порядке предпочтения: какой-либо бинарный формат (например, AMF3), затем JSON, затем XML.
- Желательно включать gzip. GZip на Android реализован “нативно”, библиотека быстрая. В некоторых случаях можно получить коэффициент сжатия 5:1 и даже 10:1, в зависимости от количества получаемых данных. Использование GZip ускоряет загрузку данных и экономит батарею.
- Если используете Sqlite — используйте транзакции.
- Если программе требуется скачать 10-20 картинок, не стоит запускать 10-20 параллельных закачек. Запускайте 1-3, а остальные ставьте в очередь.
- Activity регистрирует binder callback (т.е. ResultReceiver), для получения ответа от сервиса. Этот callback нужно обязательно удалить при вызове onPause у Activity, иначе можно налететь на ANR.
- Длительные операции всегда следует запускать из сервиса. Сервис обязательно следует останавливать после того, как требуемые операции выполнены.
- Необходимо минимизировать сетевой трафик.
- Следует разбивать данные на страницы (конечно, если REST Api предоставляют такую возможность).
- Для некритичной по времени синхронизации данных между клиентом и сервером рекомендуется использовать SyncAdapter.
Алгоритм фомирования запроса к серверу
В общем случае, при выполнении запроса к REST-серверу, требуется выполнить ряд операций:
- сформировать URL
- задать HTTP-заголовки
- выбрать тип HTTP-запроса
- сформировать тело HTTP-запроса, т.е. преобразовать Java объект в JSON
- выполнить запрос, воспользовавшись HTTP-клиентом
- распарсить результаты запроса — преобразовать полученный JSON в Java объект
Источник