Проекты: Создание и использование API

Не забывайте использовать Git для фиксации изменений в ваших проектах!

На разогрев: Изучение API Flickr

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

Ваше задание

  1. Зайдите на страницу документации по Flickr API. Бывает проще погуглить что-то вроде XYZ API docs для поиска такой документации, чем искать ее самостоятельно на сайтах.
  2. Посмотрите на имеющиеся форматы. Из них нас интересует RESTful API, так что нажмем ссылку Rest в левой части страницы в разделе "Request Formats".
  3. Вы увидите тот формат, который принимает типичный API - вы просто делаете запрос на определенный ресурс http://api.flickr.com/services/rest/ и добавляете любые необходимые данные в строку запроса GET или в тело запроса POST.
  4. Посмотрите на различные методы. Как загрузить фото? Как получить ваш список контактов? Многие из подобных методов потребуют аутентификации вашей программы или входа под каким-то пользователем.
  5. Почитайте документацию о методе поиска. Его использование не требует аутентификации, необходимо будет просто использовать ключ API (вы его получите при регистрации в качестве разработчика на сайте). Посмотрите список параметров, которые могут использоваться для поиска.
  6. В нижней части экрана вы увидите ссылку на инструмент, позволяющий вам выполнять поисковые запросы, используя ключ API сайта. Функционал реализован в ознакомительных целях, принцип действия прост - вы вводите необходимые параметры запроса и выполняете его. Введите "puppies" как параметр для поля "tags" и опуститесь вниз страницы. Смените вывод результатов на формат JSON, затем нажмите на кнопку "Call Method".
  7. После выполнения запроса, результаты будут внизу страницы. В них вы увидите длинный список фотографий (предваряемый некоторыми метаданными). Вот пример полученного результата:

        { "id": "11357337313", "owner": "84645040@N00", "secret": "6dd795c9c6", "server": "3805", "farm": 4, "title": "Gavin-Feb2013-0127", "ispublic": 1, "isfriend": 0, "isfamily": 0 },
    

    Любопытно, что ниже вы также можете видеть сформированный вашим запросом URL. Здесь он отформатирован, чтобы лучше видеть параметры запроса:

        http://api.flickr.com/services/rest/
          ?method=flickr.photos.search
          &api_key=e0eb58bf4b3e29b253e86d6092e69dee
          &tags=puppies
          &format=json
          &nojsoncallback=1
          &api_sig=200efb63cb01a3d141fff12585e1e20a
    
  8. Этот URL содержит адрес REST API, о котором мы говорили выше, строку поиска, а также некоторую другую информацию, как формат вывода данных и ключ API. Если вы скопируете этот URL в браузер, вы получите тот же самый набор данных.

  9. Вернитесь на основную страницу документации по API и нажмите на ссылку URLs в разделе "Read these first".

  10. API этого сайта требует двух шагов для отображения фотографии - сначала необходимо получить метаданные (это было нами сделано с помощью поиска), а затем на основании них создать такой URL для запроса фотографии, который поймет Flickr. Формат, который они предлагают, таков:

    http://farm{farm-id}.staticflickr.com/{server-id}/{id}_{secret}.jpg
    

    Мы можем подставить значения, полученные нами ранее:

    http://farm4.staticflickr.com/3805/11357337313_6dd795c9c6.jpg
    

    В итоге это будет выглядеть так:

    Также в конце мы можем добавить дополнительные параметры, как например size

  11. Тадам! API разных сайтов различаются, и вам придется изучать их документацию для понимания того, как его использовать. Иногда для этого будет полезно поискать информацию на YouTube или NetTuts.

Проект 1: Создание простого API

Это несложный проект, где вы создадите приложение Rails и сделаете его по сути API, генерирующим данные... другими словами, методы контроллера будут рендерить данные вместо HTML. Рассматривайте это как пример быстрого создания чистого RESTful ресурса. Вплоть до второго проекта мы не столкнемся с работой с внешним API.

Ваше задание

HTML

Начнем создание нашего приложения с того, чтобы оно просто работало в браузере с HTML.

  1. Создайте новое приложение Rails (kittens) и репозиторий Git.
  2. Внесите в файл README информацию о приложении и ссылку на эту страницу.
  3. Создайте модель Kitten с полями :name, :age, :cuteness и :softness.
  4. Создайте контроллер KittensController и маршруты :kittens для всех 7 действий RESTful.
  5. Удалите файл app/public/index.html и сделайте KittensController#index маршрутом по умолчанию.
  6. Настройте все действия контроллера и соответствующие вьюхи для отображения простых HTML страниц - #index должен отображать список всех котят, #show - одного котенка, #new должен рендерить форму создания, #edit должен использовать ту же самую форму (она будет общим парциалом для представлений New и Edit) для редактирования, #create и #update также должны выполнять свою работу.
  7. Сделайте ссылку delete на страницах Show и Edit, также поместите ее рядом с каждой фотографией на странице Index.
  8. Реализуйте отображение информационного хэша flash, поздравляющим с добавлением, редактированием или удалением фотографий, или сообщающим об ошибках.
  9. Протестируйте вашу машину для создания котят, чтобы убедиться, что все действия контроллера работают корректно.

JSON API

Сделаем ресурс Kittens доступным через API.

  1. Откройте новое окно терминала и запустите IRB. > require 'rest_client' (возможно потребуется выполнить $ gem install rest_client). Проверьте работу, выполнив запрос > response = RestClient.get("http://localhost:3000/kittens").
  2. В ответ вы должны получить некий HTML. Если проверить его, то возможно, что он обрабатывается как XML, например Processing by KittensController#index as XML.
  3. Запросите ответ в формате JSON, добавив опцию :accept => :json, например RestClient.get("http://localhost:3000/kittens", :accept => :json). Он должен выдать ошибку.
  4. Измените метод #index контроллера KittenController на #respond_to JSON и отрендерите нужные переменные.
  5. Проверьте работу, убедившись, что запросы RestClient возвращают требуемые строки в формате JSON.
  6. Выполните то же самое для метода #show - учтите, что ему будет необходимо предоставить ID. Ваша CSRF защита не позволит вам создавать, изменять или удалять котят через API, поэтому вносить изменения в эти методы нет необходимости.

Этот проект может выглядеть простым, но сейчас у вас есть И обычный сайт, генерирующий HTML в бэкенде, И API, который может получать из него данные. Вы можете использовать вызовы Javascript с фронтенда, чтобы динамически подгружать данные или даже загрузить сначала всю страницу. Или может быть вы подключили приложение к вашему iPhone и вам нужен бэкенд. Все становится неважным, так как у нас есть RESTful API.

Решения студентов

Проект 2: Использование стороннего (Third Party) API

Помните, вы на разогреве игрались с Flickr API? Настало время поработать с ним серьезно. Вы создадите простой фото виджет, для просмотра ваших фотографий с Flickr (или чьих-то других). Во многом придется изучить документацию по Flickr API, но общие принципы самого процесса создания приложения для работы с другими API остаются неизменными.

Ваше задание

  1. Вернитесь на документацию по Flickr API и перейдите на Создание Приложения.
  2. Следуйте пошаговой инструкции для получения вашего ключа API. Необходимо будет залогиниться или зарегистрироваться на Yahoo и предоставить им немного информации о вашем приложении. Выберите "Apply for a non-commercial key". Далее вы получите автоматически сгенерированный ключ, а также секретный ключ. Сохраните их у себя.
  3. С помощью idGettr узнайте свой ID, указав свою ссылку на flickr.com, например http://www.flickr.com/photos/eriktrautman/. ID вам понадобится позже для некоторых методов API.
  4. Загрузите несколько фотографий в ваш альбом!
  5. Следуя инструкции на pixellatedvisions.com, создайте боковую панель (Flickr sidebar). Вы уже выполнили пару шагов, о которых тут идет речь. Инструкция достаточно старая, но должна быть до сих пор работоспособной. Она использует гем flickr_fu, который более не поддерживается Flickr API, но имеются другие варианты (как например Flickraw). Там вы найдете гем, работающий с многими API. Все они требуют прописывать секретные ключи и ключи API - здесь для этого используется файл config/flickr.yml.
  6. Заметим, что практика хранения ключей, жестко прописанных внутри приложения не очень хороша, особенно если приложение выкладывается на Github. Лучше хранить их в виде переменных окружения или же использовать гем, подобный figaro. Переменные окружения позволяют вам подтягивать ключи в приложение напрямую из командной строки при его запуске. Figaro работает по тому же принципу, но позволяет хранить ключи в отдельном файле, который не отправляется на Github. Используйте один из этих методов. Они неплохо описаны в статье Daniel Kehoe.
  7. Создайте контроллер StaticPagesController, который будет отображать домашнюю страницу с простой формой. Форма должна быть в виде текстового поля, в которое можно ввести ID пользователя Flickr. После отправки формы она должна обновиться и отобразить фотографию этого пользователя.
  8. Переместите изображение из боковой панели на основную страницу приложения. Тут мы проверим ваши знания, а не умение копипастить.
  9. Спросите у своих друзей их ID на flickr или поищите случайные. Посмотрите фотографии в своем приложении.

Решения студентов

Дополнительные ресурсы

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

Поделиться уроком: