У вас есть собака. Но она не разговаривает на человеческом языке. Однако она способна "понимать" его путём команд, которым её научили в процессе дрессировки. Если сказать пёсику, знающему команду "тапки!" что-то типа "Рексик, принеси мне, пжалста, тапули мои с зайчушками", он разве что на кличку ухом поведёт, но тапки не принесёт. Так вот, API - это набор команд, с помощью которых ваш пёсик вас понимает и делает то, что вам нужно. Это очень сильно упрощённо и для чайника, но суть понятна, думаю.

API это язык, регламентированный способ, общения одной компьютерной программы с другой для совместного исполнения какой-нибудь общей задачи, когда одна программа выполняют запросы другой. Application Programming Interface (API) - Интерфейс программирования приложений.

Вот какая примитивная аналогия для чайников родилась навскидку.

Представьте себе 5 иностранцев, разговаривающих на разных языках, которым нужно работать и жить вместе, скажем в России. Ни один из них не знает языка другого, при этом им нужно единой командой, по ролям, выполнить какую-то задачу, например накормить друг друга и обсудить вкус еды на русском языке. Для этого необходимо купить продукты, приготовить еду, накрыть на стол и за едой обсудить блюда. Чтобы они поняли друг друга и смогли найти продукты во внешнем мире, обучим их базовому набору русских слов. Представим что у нас есть:

1. Француз

2. Испанец

4. Англичанин

5. Итальянец

Распределим между ними роли для выполнения подзадач следующим образом

Покупка Еды: Француз и Испанец

Готовка Блюд: Испанец, Немец и Англичанин

Cервировка Стола: Англичанин и Итальянец

Трапеза и обсуждение вкуса Блюд: ВСЕ

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

Так вот. Группа наших иностранных друзей это группа компьютерных программ , которым нужно общаться между собой и со внешней средой.

Язык и Cлова, обозначающие продукты и элементарные действия , которые нужно произвести это API – стандарты по которым наши иностранные друзья общаются между собой на русском, чтобы выполнить все поставленные подзадачи.

API 1: Слова обозначающие Продукты и Где Купить
API 2: Слова обозначающие Блюда и Способы приготовления
API 3: Слова обозначающие Приборы и Действия с ними
API 4: Слова обозначающие Вкус и Оценку Еду

Может быть и сложнее, например, пусть API 2 это будет турецкий язык, API 3 это китайский язык, API 4 это хинди

Пример для чайников:

1. Есть розетка. За ней огромное количество техники скрывается. Но что бы ей пользоваться - надо иметь вилку с расстоянием между стержнями 3см и розетка отдаст 220в. Это и есть API интерфейс огромной системы электропроизводства.

2. А есть утюг. У него своя сложная система работы. Но что бы работать с розеткой, он соблюдает требования API - нужна вилка с расстоянием 3см и в ответ ждет 220вольт.

И всё. 2 системы независимы, они огромны и сложны. Но API делается, что бы максимально просто соединиться друг с другом.

API - application programming interface. Это некий набор функций, констант, классов и, возможно, других объектов, для взаимодействия с неким куском программы.

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

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

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

Прежде всего, если вы до сих пор не до конца понимаете, что же такое API (Application Programming Interface - интерфейс программирования приложений), прочтите объяснение от Skillcrush , а затем первую часть этой статьи , чтоб наверстать упущенное.

"API" невероятно обширная концепция - каждый раз, когда ваше приложение "общается" с другим приложением, это происходит через некий API. Компоненты внутри вашего собственного приложения, вроде разных частей Rails, также общаются друг с другом через API. Они являются более или менее независимыми субприложениями, которые передают данные, необходимые каждому из них для выполнения собственных специфических задач. В мире приложений все является API!

Когда вы создаете приложения с более динамической фронтенд-функциональностью (как одностраничные Javascript-приложения, так и простые приложения с отдельными AJAX-вызовами), они будут общаться с Rails-бэкендом через ваш собственный API, который в действительности просто дополнительная пара-тройка строк кода, говорящая вашим контроллерам, как отдать JSON или XML вместо HTML.

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

Пункты для размышления

Просмотрите вопросы и проверьте, знаете ли на них ответы. Проверьте себя снова после выполнения задания.

• Как Rails понимает, какой тип файла вы ожидаете в ответ, когда посылаете HTTP-запрос.
• В чем заключается цель метода #respond_to ?
• Как вернуть объект пользователя (User), при этом указать атрибуты, которые не хотите включать в этот объект (то есть, вы не можете просто вернуть User.first)?
• Назовите 2 шага, выполняемых "за кулисами" метода #to_json .
• Как указать действию контроллера, что требуется рендерить лишь сообщение об ошибке?
• Как создать свое собственное сообщение об ошибке?
• Почему вы не можете использовать методы аутентификации контроллера, основанные на сессиях, если хотите позволить программно подключаться к вашему API?
• Что такое "Сервис-ориентированная архитектура"?

Основы API

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

Однако, часто вы хотите сделать запрос, который не требует переживать все головные боли от использования браузера. Вас может не заботить структура страницы (HTML), но взамен вы хотите получить чистые данные. Допустим, вы хотите получить список всех пользователей. Вы можете запросить что-то вроде http://yourapplication.com/users , что наверняка запустит действие #index и отрендерит список всех пользователей приложения.

Но зачем заморачиваться со всей этой лишней информацией, если все чего вы хотите - это получить список пользователей? Самым простым вариантом будет отправить запрос на тот же самый URL, указав ожидание JSON или XML ответа взамен. Если вы правильно настроите ваш Rails-контроллер, назад вы получите простой JSON объект-массив, содержащий всех пользователей. Прекрасно!

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

Создание API

Вы можете захотеть сделать ваше Rails-приложение чистым бэкенд API для фронтенд веб-страниц, или просто захотите научиться посылать JSON, когда фронтенд запрашивает его. Этот раздел не осветит как создавать полноценные RESTful API с функциями аутентификации. Это плавное введение в обращение с вашим приложением как с API.

Основы

Если вы хотите, чтобы ваше Rails-приложение возвращало JSON вместо HTML, вам потребуется сказать вашему контроллеру, чтобы он это делал. Самое замечательное то, что одно и то же действие контроллера может возвращать различные типы в зависимости от того, делает ли ваш пользователь обычный запрос из браузера или обращается к API через командную строку. Это определяет какой тип запроса был сделан, основываясь на расширении запрашиваемого файла, например, example.xml или example.json .

Вы можете проверить, что Rails "думает" об ожидаемом вами типе файла, проверив серверный лог:

Started GET "/posts/new" for 127.0.0.1 at 2013-12-02 15:21:08 -0800 Processing by PostsController#new as HTML

Первая строка говорит вам какой URL был запрошен, а вторая сообщает куда он был направлен и как Rails его обрабатывает. Если бы вы использовали расширение.json , то это выглядело бы так:

Started GET "/posts.json" for 127.0.0.1 at 2013-12-04 12:02:01 -0800 Processing by PostsController#index as JSON

Если у вас есть запущенное тестовое приложение, попробуйте запросить различные URL. Если ваш контроллер не умеет их обрабатывать, то вы можете получить ошибку, но все равно должны видеть, что Rails понимает под вашими запросами.

Рендеринг JSON или XML

Когда вы решите, что хотите отвечать на запросы с помощью JSON или XML, вам потребуется сообщить вашему контроллеру, что нужно рендерить JSON или XML вместо HTML. Один из способов сделать это - использовать метод #respond_to:

Class UsersController < ApplicationController def index @users = User.all respond_to do |format| format.html # index.html.erb format.xml { render xml: @users } format.json { render json: @users } end end end

В данном случае, #respond_to передает в блок объект формата, к которому вы можете приложить соответствующий вызов рендеринга. Если вы ничего не сделаете, будет рендериться html с использованием стандартного Rails-шаблона (в этом примере app/views/index.html.erb).

Функция #render достаточно умна, чтобы понять, как рендерить широкий спектр форматов. Когда вы передаете ей ключ:json , она вызовет #to_json на значении, в данном примере на @users . Это преобразует ваш(и) Ruby-объект(ы) в JSON-строки, которые будут переданы запрашивающему приложению.

Таким образом, вы получаете свой API. Конечно, создание API может быть немного более сложным, если вы захотите делать какие-то необычные вещи, но все держится на основах.

Указание возвращаемых атрибутов

Допустим, вы хотите убедиться, что не возвращаете email-адрес пользователя вместе с объектом пользователя (User). В этом случае, вы захотите изменить атрибуты, которые будут возвращаться, модифицируя то, что делает метод #to_json .

Раньше вы бы просто переопределили метод #to_json своей версией, но теперь вам это не понадобится - в действительности, вы взамен переопределите метод #as_json . Метод #as_json используется в методе #to_json , так что его модификация неявно изменён результат #to_json , но довольно специфическим способом.

#to_json делает 2 вещи: запускает #as_json и получает хэш атрибутов, которые будут отрендерены в JSON. Затем он проводит рендеринг в JSON, используя ActiveSupport::json.encode . Так что, модифицируя #as_json , вы более конкретно указываете ту часть метода #to_json , которую в действительности хотите изменить.

В нашем случае, мы делаем это модифицируя #as_json в нашей модели так, чтобы возвращать лишь необходимые нам атрибуты:

# app/models/user.rb class User < ActiveRecord::Base # Вариант 1: Полное переопределение метода #as_json def as_json(options={}) { :name => self.name } # НЕ включаем поле email end # Вариант 2: Используем стандартный метод #as_json def as_json(options={}) super(only: [:name]) end end

Затем, в нашем контроллере лишь потребуется отрендерить JSON как обычно (в примере ниже всегда будет возвращаться JSON, независимо от того, был ли отправлен HTML-запрос или нет):

# app/controllers/users_controller.rb class UsersController < ApplicationController def index render json: User.all end end

Заметьте, что вам не нужно самостоятельно вызывать #to_json , когда вы используете #render - он сделает это за вас.

Иногда Heroku может потребовать дополнительные шаги для корректного отображения ваших страниц с ошибками. Посмотрите . Вам может потребоваться сперва удалить статичные страницы из директории app/public .

Обеспечение безопасности извне

Допустим, вы хотите позволить обращаться к API только если пользователь залогинен. Ваша существующая аутентификация в контроллере уже делает эту работу - просто убедитесь, что у вас установлен правильный #before_action (например, before_action:require_login). Может потребоваться функционал, когда и залогиненный и не залогиненный пользователи могут просматривать страницу, но каждый должен видеть различные данные. Вы не хотите, чтобы незалогиненные пользователи имели возможность делать запросы к API для получения важных данных. Аналогично, вы не хотите давать возможность посещать определенные HTML-страницы неавторизованным пользователям.

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

Следующие шаги

Теперь у вас есть навыки использования вашего Rails-приложения для отдачи не только HTML, но и любого другого формата. Если вы хотите пойти дальше и позволить другим разработчикам создавать что-то с использованием вашей платформы (например, чтобы они могли делать программные запросы вместо аутентификации в качестве пользователя), вам понадобится сделать вашу API-систему намного более надежной. Мы не будем освещать все это здесь, но посмотрите следующие материалы:

• Статья Building Awesome Rails APIs содержит описание множества лучших подходов для движения от игрушечного приложения в сторону стандартов промышленных API.

Сервис-ориентированная архитектура

Пришло время представить архитектурный подход под именем "Сервис-ориентированная архитектура" (Service-Oriented Architecture, SOA). Основная идея заключается в том, что ваше приложение будет состоять из множества сервисов, вроде системы оплаты, регистрации пользователей, модуля рекомендаций и т.д. Вместо того, чтобы создавать все это внутри одного главного приложения, вы разбиваете подсистемы на полностью независимые кусочки, которые взаимодействуют друг с другом, используя внутренние API-интерфейсы.

Это хорошо по многим причинам. Благодаря тому, что каждый кусочек вашего приложения не заботится о том, как работают другие части, и знает только как запросить данные через их API, вы можете делать значительные изменения в коде сервиса, и все остальное приложение будет работать, как и прежде. Вы можете полностью заменить один сервис на другой, и, пока он взаимодействует, используя те же API-методы, это пройдет очень гладко. Вы можете использовать внешние API как часть вашего приложения (например, платежные системы) вместо написания собственного. Вы можете создать PHP-приложение, взаимодействующее с Python-приложением, взаимодействующим с Rails-приложением, и все будет работать, ведь они общаются между собой с помощью API.

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

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

Одним из наиболее известных случаев перехода на сервис-ориентированную архитектуру является Amazon.com. Однажды в 2002 году, Джефф Безос прямо заявил, что все рабочие группы должны перейти на СОА, или будут уволены. Печально известный пост из блога сотрудника Google, предназначенный внутрикорпоративных целей, но случайно ставший открытым для публики, рассказывал о мощи Amazon с использованием СОА. Это отличное чтиво, так что обязательно его оцените, но основные тезисы письма Безоса вынесены в следующие цитаты из поста:

1) Все команды отныне предоставляют свои данные и функциональность через интерфейсы сервисов.

2) Команды должны взаимодействовать друг с другом посредством этих интерфейсов.

3) Иные формы межпроцессного взаимодействия запрещены: никаких прямых ссылок, никакого непосредственного чтения данных другой команды, никаких моделей общей памяти, никаких "бэкдоров" и тому подобного. Единственный разрешенный способ взаимодействия - обращение к интерфейсу сервисов через сеть.

4) Неважно какую технологию они используют. HTTP, Corba, Pubsub, собственные протоколы - без разницы. Безоса это не волнует.

5) Все интерфейсы сервисов, без исключения, должны быть изначально спроектированы с возможностью управления извне. То есть, команда должна планировать и проектировать так, чтобы быть в состоянии предоставить интерфейс разработчикам вне компании. Никаких исключений.

6) Любой проигнорировавший эти требования будет уволен.

СОА - это серьезное дело. Несомненно, есть много проблем, которые всплывают при ее использовании - посмотрите этот пост о "извлеченных уроках" Amazon - но она имеет невероятно много преимуществ.

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

Ваша цель

1. Прочитайте раздел 7 руководства Rails по контроллерам , чтобы изучить рендеринг JSON и XML.
2. Они не обязательны к просмотру (потому что они идут немного дальше, чем мы сейчас подготовлены), но, если вам интересно, взгляните на Railscasts в разделе Дополнительных ресурсов внизу урока, чтобы больше узнать о преимуществах API.

Заключение

Мы плотнее поработаем с вашим приложением как с API во время курса по Javascript. В этом курсе вы создадите несколько полноценных (фулл-стэк) приложений, использующих AJAX-вызовы для лучшего пользовательского интерфейса, что по факту включает в себя рендеринг XML или JSON данных взамен полноценной HTML-страницы. Затем вы создадите несколько одностраничных Javascript-приложений, которые полагаются на API, предоставляемом вашим Rails-приложением, для получения всех необходимых данных из БД, а во всем остальном работающих на стороне клиента (в браузере).

Лучший способ разобраться с API - создать и взаимодействовать с ним, на чем мы сфокусируемся в наших проектах.

API (англ. Application Programming Interface ) - это интерфейс программирования приложений . API конкретного приложения или сервиса предоставляет набор готовых процедур, функций и переменных, с помощью которых сторонние разработчики могут создавать свои приложения и скрипты для работы с этим сервисом.

При работе через API приложение отправляет запрос к сервису и получает ответ, содержащий запрошенные данные, вне зависимости от того, на каком языке программирования они созданы.

Что позволяет делать API платформы beseller?

Цель создания API платформы beseller - предоставление сторонним приложениям возможности взаимодействия с сайтами и базами данных интернет-магазинов.

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

Владельцы интернет-магазинов при помощи сторонних сервисов и собственных приложений имеют возможность обращаться по API к:

Информации об оформленных заказах

Доступные действия (методы) обработки информации о заказах:

1. Выбор информации о заказе по ID
2. Выбор информации о заказах по фильтру
3. Количество заказов по фильтру
4. Создание заказа
5. Удаление заказа
6. Массовое удаление заказов
7. Выбор всех доступных статусов для заказов
8. Обновление статуса заказа
9. Добавление комментария к заказу

Информации о подписчиках

1. Добавление подписчика
2. Удаление подписчика
3. Массовое удаление подписчиков
4. Выбор данных о подписчиках по фильтру
5. Количество подписчиков по фильтру

Информации о зарегистрированных пользователях

Доступные действия (методы) обработки информации о подписчиках:

1. Выбор информации о зарегистрированных пользователях по ID
2. Выбор информации обо всех зарегистрированных пользователях
3. Выбор информации обо всех данных указанных пользователем при регистрации:
   • Фамилия, имя, отчество;
   • Контактный адрес электронной почты;
   • Контактный номер телефона;
   • Указанный адрес доставки: индекс, название населенного пункта, название улицы, номер дома, номер корпуса, номер квартиры, этаж;

Обратите внимание! При регистрации, пользователь может не заполнить все указанные выше поля.

Планы по развитию API

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

1. Разделами каталога.
2. Товарами.
3. Корзиной.
4. Скидками.
5. Способами доставки.
6. Способами оплаты.

Для тестирования взаимодействия с API платформы beseller создан тестовый магазин beseller-api.shop.by .

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

Перед тестированием взаимодействия с API мы рекомендуем вам:

1. оформить самостоятельно несколько заказов;
2. подписаться на рассылку;
3. посмотреть как информация об оформленных заказах и подписчиках отображается в панели администрирования магазина.

Панель управления магазином доступна по адресу: beseller-api.shop.by/manager/ . Логин и пароль при входе в панель управления аналогичны логину и паролю доступа к магазину.

Как подключиться по API к своему магазину?

Для связи приложения с вашим магазином необходимо указать url-адрес доступа к API вида:

http://адрес_вашего_сайта:8082/graphql?token=ваш_персональный_секретный_ключ

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

Функции и переменные GraphQL для работы с API платформы beseller

Как подключиться к API с использованием языка программирования PHP

Для удобства работы с API платформы beseller вы можете воспользоваться:

1. Классами разработанными нами под PHP.
   1. GraphqlClient - осуществляет прием и передачу данных на сервер;
   2. GraphQlHelper - содержит в себе реализованные query и mutation API;
2. Примерами использования классов для осуществления выборок и изменений в базе данных интернет-магазина.

Настройка локального окружения

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

В качестве локального окружения используется GraphiQL Feen , это расширение для браузера Google Chrome которое позволяет формировать запросы к API.

После установки приложения у вас в браузере возле адресной строки появится иконка приложения.

Откройте приложение GraphiQL Feen и перейти на вкладку «SERVERS», выберите метод отправки POST, после чего укажите url-адрес доступа к API.

В качестве тестового url необходимо использовать следующий адрес:

Локальное окружение настроено, можно формировать запросы к API. Для этого необходимо открыть вкладку «QUERIES»

Формирование запроса к API beseller при помощи GraphiQL Feen и полученный ответ

Пояснения к скриншоту:

1. Сохраненные запросы
2. Поле для ввода запросов
3. Поле ввода переменных
4. Полученный ответ
5. Кнопка запуска

Пример запроса на получение списка оформленных заказов за указанный промежуток времени

query ($first:Int, $offset:Int, $filter: OrdersFilterType){
orders(first:$first, offset:$offset, filter:$filter){
comment
status{
id
description
name
}
create_date
update_date
total {
suffix
value
}
payment {
name
description
cost {
suffix
value
}
}
delivery {
name
description
cost {
suffix
value
}
}
currencies {
bank_code
course
suffix
}
user_data {
name
description
value
}
}
}

Указание промежутка времени для выборки данных об оформленных заказах

{
"filter": {
"date_after": "2017-11-16T00:00:01Z",
"date_before": "2017-11-23T00:00:01Z"
}
}

Пример ответа от API

{{
"data": {
"orders": [
{
"comment": "Culpa officiis vel ut.",
"create_date": "2017-11-22 16:23:28",
"currencies": [
{
"bank_code": "BYN",
"course": 10000,
"suffix": "руб."
}
],
"delivery": {
"cost": [
{
"suffix": "руб.",
"value": 0
}
],
"description": "Курьер",
"name": "custom"
},
"payment": {
"cost": [
{
"suffix": "руб.",
"value": 0
}
],
"description": "Пластиковые карты",
"name": "custom"
},
"status": {
"description": "Новый",
"id": 1,
"name": "new"
},
"total": [
{
"suffix": "руб.",
"value": 4450
}
],
"update_date": "2017-11-22 16:23:28",
"user_data": [
{
"description": "Адрес e-mail",
"name": "email",
"value": "[email protected]"
},
{
"description": "Телефон",
"name": "phone",
"value": "784.392.3949 x69329"
},
{
"description": "Адрес",
"name": "registration",
"value": "607 Erik Station Suite 057\nReynaberg, WY 83542-0037"
},
{
"description": "Комментарий",
"name": "comment",
"value": "Id nam illo optio."
},
{
"description": "ФИО",
"name": "fio",
"value": "Jordi Mann MD"
}
]
}

Этот краткий термин на слуху у всех, кто хоть как-то сталкивался с разработкой. Но далеко не все понимают, что именно он обозначает и зачем нужен. Разработчик Пётр Газаров рассказал об API простыми словами в своём блоге.

Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). Большинство крупных компаний на определённом этапе разрабатывают API для клиентов или для внутреннего использования. Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина».

Всемирная паутина и удалённые серверы

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

При введении в адресную строку браузера www.facebook.com на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу.

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

API как способ обслуживания клиентов

Многие компании предлагают API как готовый продукт. Например, Weather Underground продаёт доступ к своему API для получения метеорологических данных .

Сценарий использования: на сайте небольшой компании есть форма для записи клиентов на приём. Компания хочет встроить в него Google Календарь, чтобы дать клиентам возможность автоматически создавать событие и вносить детали о предстоящей встрече.

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

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

Чем API Google Календаря отличается от API любого другого удалённого сервера в сети?

Технически, разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON.

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

Пользовательблагодаря API получает возможность совершить действие, не покидая сайт компании.

Большинство современных сайтов используют по крайней мере несколько сторонних API. Многие задачи уже имеют готовые решения, предлагаемые сторонними разработчиками, будь то библиотека или услуга. Зачастую проще и надёжнее прибегнуть именно к уже готовому решению.

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

Таким образом, когда компания предлагает своим пользователям API, это просто означает, что она создала ряд специальных URL, которые в качестве ответа возвращают только данные.

Такие запросы часто можно отправлять через браузер. Так как передача данных по протоколу HTTP происходит в текстовом виде, браузер всегда сможет отобразить ответ. Например, через браузер можно напрямую обратиться к API GitHub (https://api.github.com/users/petrgazarov), причём без маркера доступа, и получить вот такой ответ в формате JSON:

Браузер отлично отображает JSON-ответ, который вполне можно вставлять в код. Из такого текста достаточно просто извлечь данные, чтобы использовать их по своему усмотрению.

Ещё несколько примеров API

Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:

• фрагмент программного обеспечения с определённой функцией,
• сервер целиком, приложение целиком или же просто отдельную часть приложения.

Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.

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

Пришло время поговорить о таком понятии как API функции в языке Visual Basic . Чем же важны эти функции в Visual Basic? Давайте разберемся, во-первых, когда Вы начнете программировать на Visual Basic, Вы сразу же поймете, что с использованием этих функций можно написать очень серьезные программы, во-вторых, просто многое нельзя сделать без использования API функций, например, практически все что связанно с использованием операционной системы Windows (например: узнать имя пользователя, место на жестком диске и так далее ).

Но для того чтобы начать применять на практике эти функции, Вам нужно знать, что они из себя представляют, давайте поговорим сначала об этом.

Теория по API функциям Visual Basic

API – это аббревиатура Application Programming Interface (интерфейс прикладного программирования ). Другими словами, API – это набор функций, которые сама операционная система дает программисту для использования их в своих программах. С помощью API программисты легко реализуют свои задумки на практике.

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

Практически все функции, которые располагаются в Windows - находятся внутри DLL (Dynamic Link Library ). Все dll-файлы расположены в системной папке Windows. Существует свыше 1000 функций API, которые условно делятся на четыре основные категории.

• Работа с приложениями - запуск и закрытие приложений, обработка команд меню, перемещения и изменения размера окон;
• Графика - создание изображений;
• Системная информация - определение текущего диска, объем памяти, имя текущего пользователя и т.д.;
• Работа с реестром - манипуляции с реестром Windows.

Применение API функций на практике

Теперь перейдем непосредственно к использованию этих функций на практике. Функции API, вызываемые в Visual Basic, должны быть сначала объявлены. При объявлении указывается имя DLL и функции, а также информация о количестве и типе аргументов.

Процедуры DLL объявляются командой Declare в секции General Declarations модуля формы или стандартного модуля:

Declare Function имя Lib "библиотека" [([ _ переменная [,ByVal,] переменная ]...])] As тип

Процедуры DLL, находящиеся в стандартных модулях, по умолчанию являются открытыми и могут вызываться из любой точки приложения. Процедуры, объявленные в модуле формы, являются закрытыми и перед их объявлением должно стоять ключевое слово Private.

Секция Lib сообщает, где следует искать файл DLL, содержащий функцию. При ссылке на основные библиотеки Windows (user32.dll, kernel32.dll, gdi.dll) расширение включать не обязательно.

Если путь к файлу не указан, то начинается просмотр каталогов в следующей последовательности

1. Каталог, содержащий EXE-файл программы;
2. Текущий каталог;
3. Системный каталог Windows;
4. Каталог Windows;
5. Переменная окружения Path.

Вот небольшой перечень стандартных библиотек DLL Windows:

• advapi.dll - защита NT,реестр и другие продвинутые сервисы;
• comdlg.dll - стандартные диалоговые окна;
• gdi.dll - интерфейс графических устройств;
• kernel32.dll - память, диски, процессы, ресурсы;
• mpr.dll - сети;
• netapi32.dll - библиотека сетевого API;
• shell32.dll - оболочка Windows, drag-and-drop ,выборка значков;
• user32.dll - пользовательский интерфейс-окна, меню, строки, сообщения;
• version.dll - контроль версий;
• winmm.dll - мультимедиа, звук, джойстики, таймеры;
• winspoll.dll - диспетчер печати.

Большинство процедур DLL за документировано с использованием нотации языка программирования C и C++. Для успешного преобразования функции API в команду Declare необходимо разбираться в механизме передачи аргументов. Обычно аргументы передаются по значению. В этом случае перед именем аргумента ставится ключевое слово ByVal. Если аргумент передается по ссылке, то ставится ByRef.

Вот самый малый список функций, которые используются в Visual Basic:

• BitBlt - копирует изображение из одного hDC в другой;
• FindWindow - находит Handle окна с указанным Caption;
• GetCursorPos - возвращает текущую позицию курсора мыши (глобально);
• GetDriveType - возвращает тип накопителя;
• GetForegroundWindow - возвращает Handle активного окна;
• SetCursorPos - устанавливает новую позицию курсора мыши;
• SetVolumeLabel - изменяет метку диска;
• SetWindowPos - устанавливает позицию окна с определённым Handle (также с помощью этой функции можно сделать так, чтобы окно было ПОВЕРХ всех;
• ShellExecute - запускает приложение, ассоциированное с расширением, которое имеет указанный файл (также может просто запустить указанное приложение);
• ShowCursor - скрывает или показывает курсор мыши на экране.

Примеры работы с реестром

Также при программировании на Visual Basic, да и на других языках возникает проблема, когда нужно использовать реестр Windows, но с помощью api функций это сделать легко, например:

Для чтения строкового параметра используйте функцию GetRegString

Пример:

Dim test As String test = GetRegString(HKEY_LOCAL_MACHINE, _ "Software\Microsoft\DirectX", "Version") Form1.Caption = test

Для чтения параметра DWORD GetRegDWord

Пример:

Dim test As Long test = GetRegDWord(HKEY_LOCAL_MACHINE, _ "Software\Microsoft\Internet Explorer\AboutURLs", "Home") Form1.Caption = test

Для записи строкового параметра используется SetRegString

Пример:

SetRegString HKEY_LOCAL_MACHINE, _ "Software\test", "MyProgram", "Options"

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

Для записи параметра типа DWORD используется SetRegDWord

Пример:

SetRegDWord HKEY_LOCAL_MACHINE, _ "Software\test", "MyProgram", "555"

Для удаления ключа из реестра используется функция DeleteRegKey

Пример:

DeleteRegKey HKEY_LOCAL_MACHINE, "Software", "test", True

Второй параметр - Ключ-родитель
Третий параметр - True - если требуется подтверждение на удаление или False - если подтверждение не требуется.

Для удаления параметра из реестра используется функция DeleteRegValue

Пример:

DeleteRegValue HKEY_LOCAL_MACHINE,_ "Software\Microsoft\Internet Explorer\AboutURLs", "mozilla", False

На самом деле возможности API функций в операционной системе Windows практически безграничны. Давайте закончим на этом рассмотрение этой возможности Visual Basic и напоследок напишем небольшую программку с использованием API функций.

Данная программа просто выводит сообщение на экран, вставьте следующий код:

Private Declare Function BeginPath Lib "gdi32" (ByVal hdc As Long) As Long Private Declare Function EndPath Lib "gdi32" (ByVal hdc As Long) As Long Private Declare Function PathToRegion Lib "gdi32" (ByVal hdc As Long) As Long Private Declare Function SetWindowRgn Lib "user32" (ByVal hWnd As Long, ByVal hRgn As Long, ByVal bRedraw As Boolean) As Long Private Sub Form_Load() Const TEXT = "Ты использовал API" Dim hRgn As Long Font.Name = "Times New Roman" Font.Bold = True Font.Size = 60 Width = TextWidth(TEXT) Height = TextHeight(TEXT) BeginPath hdc Print TEXT EndPath hdc hRgn = PathToRegion(hdc) SetWindowRgn hWnd, hRgn, False Move (Screen.Width - Width) / 2, (Screen.Height - Height) / 2 End Sub

Мы здесь использовали 4 функции (BeginPath, EndPath, PathToRegion, SetWindowRgn), которые располагаются в двух dll библиотеках (gdi32, user32).

На этом все, пока!