Работа с API онлайн-сервисов в Delphi. Введение.

Решил я помочь одному из читателей блога и подробнейшим образом расписать работу с API онлайн-сервиса. Что поделать? Такова специфика моей работы в Delphi — разработка отдельных компонентов, классов и, иногда, небольших библиотек для работы с API онлайн-сервисов в Delphi. Что-то пишется для своих нужд, что-то — на заказ. Кое-какой опыт, в общем, имеется. Соответственно, и в поиске блог находят по вопросам работы, то с Google API, то ещё с каким-нибудь API.

Введение

Начал писать что-то типа «инструкции для начинающих»…думал справлюсь быстро. Но когда посмотрел часть статьи в Word и оказалось, что  она занимает без малого 30 страниц текста, решил — перебор :). Дополнил материал парой вводных частей и решил оставить этот материал в блоге. Помня просьбы некоторых читателей не выкладывать большие «портянки» в блог, а хотя бы разбивать статью на несколько частей, решил так и сделать. Поэтому вместо одной статьи в блоге будет три. Каждая часть — это отдельный момент работы. Первая и третья части по размеру вышли по-меньше, вторая — по-больше.

На кого рассчитан материал?  Эта статья будет чем-то похожа, наверное, на развернутую инструкцию про то, с чего начинать и в какой последовательности действовать при работе над любым API онлайн-сервиса в Delphi. Здесь довольно много такой информации, которую большинство «прожженных» профессионалов в Delphi назовут прописными истинами или понятным на интуитивном уровне, но, как говорится из песни слов не выкинешь. Вполне возможно, что именно эти прописные истины пригодятся тем, кто собирается использовать возможности онлайн-сервисов в своих Delphi-приложениях, но не знает с чего начать.

Конечно, любой материал, посвященный программированию, должен сопровождаться примерами. Для примера, я рассматриваю подробным образом работу с API сервиса etxt.ru (его я ещё в блоге не рассматривал). Там где было возможно и целесообразно я давал ссылки на другие материалы блога, посвященные работе с API в Delphi, например, вы найдете практически всю подборку ссылок, касающуюся работе с протоколом OAuth. В заключительной части вы найдете ссылки для загрузки PDF-версии и исходников приложения, рассмотренного в статье.

В этой части я решил сосредоточится на самых общих моментах. Вот какие «философские» вопросы мы сейчас рассмотрим:

1. Что необходимо знать и уметь?
2. Что делать, если время поджимает?
3. Начало работы с API. Какие компоненты выбрать?

К выполнению любой задачи необходимо приступать при наличии достаточной подготовки. Работа с API онлайн-сервисов в Delphi — не исключение. Прежде, чем начать работу непосредственно над кодом, необходимо изучить ряд вопросов, без которых дальнейшая работа может превратиться в сплошные проблемы. Поэтому сейчас я не приведу ни одной строки кода Delphi — только ссылки на материалы, которые стоит изучить перед началом работы.

Что необходимо знать и уметь?

Вначале определимся с тем, что должен знать разработчик, чтобы начать работу над API любого онлайн-сервиса в Delphi. Вот, пожалуй, краткий список того, чем необходимо владеть и, что необходимо понимать помимо основ объектно-ориентированного программирования:

1. Знать принципы работы сетевых протоколов прикладного уровня, хотя бы работу протокола HTTP. Умение загружать странички в TWebBrowser — не показатель знания и умения работы с HTTP. Не поленитесь — почитайте информацию о методах, кодах состояния, заголовках, о том, как составить правильный запрос, как понять, что вам ответил сервер. Статей в Сети на эту тему — масса…тысячи их. Вот в этой нашей статье дается краткая информация по HTTP.
2. Уметь работать с библиотеками и компонентами Delphi, реализующих работу с сетевыми протоколами. От вас не требуется знать все библиотеки досконально (тем более, что их, опять же, очень много), но пользоваться хотя бы одной из них надо уметь ещё ДО того, как вы решили сделать свой клиент для Twitter или ещё для чего-либо. Начните, например, с Indy — она всегда у вас под рукой в Delphi. Потом, если вы хорошо освоите п.1 из этого списка и посчитаете, что Indy вам не подходит, Вы всегда с можете с легкостью понять работу и других библиотек и перейти, например, на Synapse.
3. Необходимо уметь работать с различными кодировками текста. Это, можно сказать, один из ключевых моментов и самых больших препятствий для начинающего разработчика. Всевозможные форумы по программированию в Delphi просто пестрят сообщениями на эту тему: «Кракозябры вместо текста«, «Знаки вопроса вместо текста«, «Indy глючит — текст не читабельный» и т.д. и т.п. Поверьте мне на слово — Indy тут не глючит :) Она выдает вам ровно то, что Вы просите. Не больше и не меньше. Просто вы не умеете работать с кодировками. Что можно почитать на тему кодировок в блоге:
   1.  Здесь я очень кратко рассказывал про некоторые кодировки, в принципе.
   2. В статье «Нахождение кодировки веб-страницы» рассказывается про то как определить кодировку странички, используя навыки работы с библиотекой Synapse и регулярными выражениями.
   3. Серия статей про MLang. В статье «MLang в Delphi. Работа с кодировками Web-страниц» вы узнаете как использовать библиотеку MLang для преобразования кодировок текста.  Статья «MLang. Автоматическое определение кодировки веб-страницы» расскажет про использование интерфейсов MLang для автоматического определения кодировок страниц. В статье «Обновление MLang. Добавлена поддержка Delphi 4-XE» вы найдете обновление модуля Delphi для работы с MLang.
   4. Статья «3 варианта работы с кодировками веб-страниц в Delphi» расскажет как использовать различные возможности Delphi для работы с кодировками текста.
4. Уметь использовать функции хэширования, например MD5, SHA-1 и кодирования, например, в Base64.  На начальном этапе работы вам, в принципе, будет достаточно прочитать небольшую статью под названием «MD5, Base64, HMAC-SHA-1 в Delphi средствами Indy и Synapse«
5. Знать особенности различных способов и протоколов для авторизации пользователей в Сети. Например, сейчас большое количество онлайн-сервисов требуют авторизации пользователя по протоколу OAuth. Знать особенности этого протокола необходимо, чтобы, как минимум, в дальнейшем не «упростить» работу с протоколом так, что ваши пользователи начнут шарахаться от вашего приложения как черт от ладана. Про сам протокол можно прочитать, например, в wiki. Последняя статья в блоге на эту тему касалась как раз того, что НЕ надо делать при работе с протоколом OAuth. Некоторые сервисы предоставляют разработчикам свои собственные способы авторизации, но здесь вам как раз помогут навыки, полученные в п.1-4.
6. Уметь работать с такими форматами данных как XML и JSON. Если у вас нет навыков работы с этими форматами, вы впервые слышите про то, что они вообще существуют, то не начинайте работу над API пока не исключите этот досадный пробел в своих знаниях – потеряете очень много времени, впустую зависая на форумах.

В целом, изучение информации по пяти предоставленным пунктам должно быть достаточно, чтобы начать работу над любым API онлайн-сервисов в Delphi. При изучении каждого из пунктов старайтесь что-то делать в Delphi на эту тему. Изучаете HTTP? Начните параллельно изучать, например, Indy для работы с HTTP в Delphi — пробуйте скачивать странички сайтов из Сети, обрабатывать исключения HTTP, выполнять не только GET-, но POST-запросы и т.д. Изучаете кодировки — напишите простенькую программку для преобразования кодировок. Разбираетесь с форматом XML — найдите на компьютере какой-нибудь файл XML и попробуйте прочитать из него что-нибудь в Delphi. Учитесь постепенно — API от вас не убежит, поверьте. В общем — практика, практика и ещё раз практика.

Частично, разобраться с вопросами, обозначенными выше, Вам поможет представленный далее материал.

Что делать, если время поджимает?

Если время поджимает, а изучать что-то новое некогда/лень (нужное подчеркнуть), но надо, кровь из носу, получить компонент или программу для работы с API, то выход есть…даже несколько выходов.

1. Отложить работу до тех пор, пока не появится время заняться изучением вопросов, представленных выше.
2. Упрашивать кого-нибудь на форумах отдать вам готовые исходники, обосновывая это дело своей жуткой занятостью. Не серьезное и не достойное занятие для уважающего себя разработчика.
3. Вместо изучения пяти пунктов изучить один — научиться правильно составлять техническое задание. Потом смело забросить ТЗ на какой-нибудь freelance.ru и ждать того у кого было время изучить работу с HTTP, кодировками и т.д.

Серьезно. Любой из упущенных моментов обучения ведет к серьезным проблемам в дальнейшей работе:

• не разберетесь в работе HTTP — замучаетесь составлять запросы к API, работать с исключениями API и т.д. Элементарно не сможете разобраться с тем, почему сервер отвечает вам 404 кодом, не смотря на то, что запрос (по вашему мнению) составлен правильно.
• не разберетесь с компонентами (хотя бы поверхностно) — вообще не сможете приступить к работе, т.к. будете смотреть на эти компоненты как…ну, в общем, с удивлением будете смотреть
• не знаете, как работать с JSON — считайте, что 80% различных API вам вообще недоступны.

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

Начало работы с API. Какие компоненты выбрать?

Онлайн-сервис, предоставляющий пользователям свой API, всегда сообщает разработчикам информацию о протоколе по которому необходимо осуществлять взаимодействие с сервером. Например, на самой первой странице документации к любому API можно встретить такие фразы:

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

или

Для взаимодействия по протоколу SOAP см. документацию здесь, а для взаимодействия по XML-RPC — здесь

Вместе с этим часто в документации можно встретить и такую информацию:

API реализовано на REST-принципах с использованием HTTP и XML для обмена данными.

Что это всё значит для нас, как для разработчиков?

Например, первое сообщение говорит нам о том, что все запросы и ответы на них передаются по протоколу HTTP. Что использовать для работы с HTTP в Delphi? Библиотек и вариантов масса:

1. Indy — «родная» библиотека Delphi
2. Synapse
3. ICS
4. IP*Works
5. ещё с десяток различных платных и бесплатных компонентов и библиотек.

Что говорит нам второе сообщение? Второе сообщение говорит нам о том, что взаимодействовать с сервером мы можем или по протоколу SOAP или по протоколу XML-RPC. Что использовать в Delphi? Если прочитать, как и посредством чего работают эти протоколы, то чисто теоретически, для работы по этим протоколам можно ограничиться двумя компонентами:

1. Первый компонент — для транспорта. Это опять же, что то, что работает с HTTP (см. выше перечень библиотек)
2. Второй компонент — для разбора ответов и составления запросов. Это может быть или стандартный TXMLDocument или какая-нибудь сторонняя библиотека, например, NativeXML.

Для работы по XML-RPC этих двух компонентов будет более, чем достаточно. Но, если вы решили работать по SOAP, то проще, лучше и быстрее использовать уже готовые решения в Delphi — это инструмент для импорта WSDL и компоненты с вкладки WebServices. О том, как ими пользоваться я рассказывал на примере переводчика Bing в статье «API переводчика Bing. Используем SOAP в Delphi«.

Третье сообщение интереснее, т.к. в нем появляется новое непонятное слово — REST. Чтобы понять, что это такое — посмотрим на определение:

HTTP — это протокол. SOAP — тоже протокол. А REST — стиль. Для того, чтобы разобраться, что это за стиль такой и в чем его «соль» я бы порекомендовал вам прочитать старенькую, но достаточно понятную статью на Хабре по названием «Архитектура REST«.

Пусть вас не пугает то, что «API реализовано на REST-принципах«. Для реализации таких API в Delphi опять же все есть. Главное знать в каком формате сервер присылает данные. Если данные приходят в виде XML-документов, то вам достаточно опять же двух компонентов: для работы с HTTP и для работы с XML. Если же данные возвращаются в формате JSON, то тут возможности Delphi сейчас по-богаче:

1. Если Вы обладатель Delphi XE5-XE7, то в Delphi есть целая библиотека — REST Client Library для реализации таких API.
2. Можно использовать любой компонент для работы с HTTP и, опять же, целый ряд компонентов для работы с JSON — это и стандартная (с версии Delphi 2010) библиотека для JSON и SuperObject и ещё несколько библиотек для работы с JSON в Delphi.

Как видите, уже на этапе чтения вводного текста документации API вы сталкиваетесь с тем, что вам необходимо знать. Помимо представленных выше ситуаций, прочие API могут поддерживать и другие протоколы, например, API Яндекс.Диска работает как по HTTP, так и по протоколу WebDav, а Google Contacts API поддерживает как работу по HTTP, так и по CardDav и т.д. И как бы вы не торопились создать свое первое приложение для работы с API, вам придётся, прежде всего, изучить работу протокола и правильно подобрать набор компонентов для работы.

Определившись с набором компонентов для дальнейшей работы, можно приступать к дальнейшему чтению документации и началу работы над своими классами Delphi для работы с API. 

О том, как написать свой первый класс для работы с API мы поговорим во второй части.

Книжная полка

	Автор: Дмитрий Осипов Название: Delphi. Программирование для Windows, OS X, iOS и Android Описание Подробно рассматривается библиотека FM, позволяющая создавать полнофункциональное программное обеспечение для операционных систем Windows и OS X, а также для смартфонов и планшетных компьютеров, работающих под управлением Android и iOS
	Автор: Андрей Шкрыль Название: Разработка клиент-серверных приложений в Delphi Описание: Рассмотрены практические вопросы по разработке клиент-серверных приложений в среде Delphi 7 и Delphi 2005 с использованием СУБД MS SQL Server 2000, InterBase и Firebird. Приведена информация о теории построения реляционных баз данных и языке SQL. Освещены вопросы эксплуатации и администрирования СУБД.
	Автор: Антон Григорьев Название: О чем не пишут в книгах по Delphi Описание: Рассмотрены малоосвещенные вопросы программирования в Delphi. Описаны методы интеграции VCL и API. Показаны внутренние механизмы VCL и приведены примеры вмешательства в эти механизмы. Рассмотрено использование сокетов в Delphi: различные режимы их работы, особенности для протоколов TCP и UDP и др.