Главная Windows 8

Что такое api? Основы API. Создание собственного API

01.07.2023

В ероятно, вы видели термин «API». Операционная система, веб-браузер и обновления приложений часто объявляют о новых API для разработчиков. Но что такое API?

Интерфейс прикладного программирования

Термин API является аббревиатурой, и он означает «Интерфейс прикладного программирования».

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

Аналогично, API предоставляет множество операций, которые могут использовать разработчики, а также описание того, что они делают. Разработчику необязательно знать, как, например, создается операционная система и отображается диалоговое окно «Сохранить как». Им просто нужно знать, что он доступен для использования в приложении.

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

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

API упрощают жизнь для разработчиков

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

Например, если Вы хотите встроить веб-браузер для отображения одной или нескольких веб-страниц, Вам не нужно программировать собственный веб-браузер с нуля только для Вашего приложения. Вы
можете использовать WKWebView API для встраивания веб-браузера WebKit (Safari) в приложение.

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

Это относится ко всем платформам. Например, Вы хотите создать диалоговое окно в Windows? Для этого есть API . Хотите поддерживать аутентификацию отпечатков пальцев на Android? Для этого есть API , так что Вам не нужно тестировать каждый датчик отпечатков пальцев любого производителя Android. Разработчикам не нужно повторно изобретать колесо снова и снова.

API-интерфейсы управляют доступом к ресурсам

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

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

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

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

Файловые системы, которые используют разрешения, как и в Windows, Mac и Linux, имеют те права, которые применяются API файловой системы. Типичное приложение не имеет прямого доступа к необработанному физическому жесткому диску. Вместо этого приложение должно получить доступ к файлам через API.

API используются для связи между службами

API также используются по другим причинам. Например, если Вы когда-либо видели объект Google Карты, встроенный на веб-сайт, этот веб-сайт использует API Карт Google для встраивания этой карты. Google предоставляет API-интерфейсы, подобные этим, для веб-разработчиков, которые затем могут использовать API-интерфейсы, чтобы собирать сложные объекты прямо на своем веб-сайте. Если таких API не существует, разработчикам, возможно, придется создавать свои собственные карты и предоставлять свои собственные данные карты, чтобы разместить небольшую интерактивную карту на веб-сайте.

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

Это относится ко многим различным онлайн-сервисам. Существуют API для запроса перевода текста из Google Translate или отображения комментариев Facebook или твитов из Twitter на веб-сайте.

Стандарт OAuth также определяет ряд API, которые позволяют Вам входить на сайт через другой сервис, например, использовать Ваши учетные записи Facebook, Google или Twitter для входа на новый веб-сайт без создания новой учетной записи пользователя только для этого сайта. 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).

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

Для того, чтобы облегчить труд своих коллег и обеспечить всем программам для Windows универсальный интерфейс, программисты Microsoft создали такую вещь, как API - "Application Programming Interface".

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

В операционной системе MS-DOS такого понятия, как API, не было, - тот, кто брался писать программу для этой операционной системы, обязан был сам, от начала до конца, продумать и реализовать способы выдачи на экран изображения, получения данных от пользователя, путешествия по файловой системе, рисования графики, если таковая возможность была необходимой 2 . Это делало процесс разработки программ с удобным для пользователя интерфейсом весьма трудоемким процессом, зачастую затраты времени и сил на создание приемлемого графического интерфейса программы превосходили затраты на реализацию собственного алгоритма программы, ради которого она и создавалась. Недаром были очень распространены так называемые "консольные" приложения, то есть программы, работающие только из командной строки, без интерфейса, - ввод данных происходил в той же командной строке или производился из указанного в ней файла, а вывод результатов шел в простом текстовом режиме.

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

В языке Visual Basic for Applications (VBA) многие функции и процедуры API вызываются сами при выполнении программы интерпретатором, так что использовать их для отображения окон ввода и вывода текста, рисования на экране геометрических фигур и других простых действий совершенно нет необходимости, - их VBA вызывает по мере надобности, а программе на нем достаточно использовать соответствующие функции этого языка. Однако иногда возникает необходимость в некоторых действиях, для которых либо нет аналогов во встроенных функциях VBA, либо они работают нерационально или слишком медленно. Например, окно выбора папки с изображением дерева каталогов (рис.5.1) или программа поиска файлов (аналог на функциях VBA - объект "Application.FileSearch" - работает слишком медленно при больших количествах файлов). Для таких случаев в VBA предусмотрена возможность вызова функций API.

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

В подавляющем большинстве случаев при программировании для Office можно обойтись без использования API, но иногда только вызов API-функции может привести к достижению нужного результата. Скажем, вам надо обеспечить вызов разных макросов при простом нажатии мышью кнопки на какой-либо панели инструментов Word и в случае одновременного нажатия этой кнопки и клавиши Shift или Control. Вот фрагмент кода, делающего это:

Declare Function GetAsyncKeyState Lib "user32.dll" (ByVal kState As Long) As Integer

GetAsyncKeyState (vbKeyShift Or vbKeyControl)

If GetAsyncKeyState(vbKeyShift) Then

Call macro1: Exit Sub

ElseIf GetAsyncKeyState(vbKeyControl) Then

Call macro2: Exit Sub

Первая строчка - это как бы "резервирование" функции API для использования в программе на VBA. Видно, что вызывается функция GetAsyncKeyState из библиотеки (файла, содержащего программы, предназначенные только для использования другими программами) user32.dll, причем в эту функцию передается номер клавиши, а возвращает она целое число (а именно - 0, если клавиша с соответствующим номером не нажата, и -32767 или 1, если нажата). Любую функцию или процедуру, вызываемую из библиотек, не относящихся к VBA, необходимо так резервировать с помощью команды Declare.

Фраза vbKeyShift в команде - это заменитель кода клавиши Shift (его значение - 16), а vbKeyControl, как нетрудно понять - заменитель кода клавиши Control. Структура инструкций "If…Then", думается, ясна 3 , а если нет - посмотрите в справке VBA. Команда Call перед именем макроса, как вы помните, означает его запуск.

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

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

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

Можно считать, что API - это некий объект, реализацию которого мы не знаем, однако, можем его использовать. Например, компьютер - объект, реализацию которого знают очень мало людей, однако, использовать его могут почти все, совершая какие-то действия: просмотр видео, сёрфинг по Интернету, печать текста и прочее. Как это всё работает - мало, кто знает, а вот делать это могут чуть ли не все.

Примером API является Windows API , OpenGL API , Direct3D API и так далее.

Например, не так давно я тоже столкнулся напрямую с API . Я зарегистрировался на сервисе почтовых рассылок "SmartResponder.ru " и завёл рассылку, на которую стали подписываться люди. Задача была следующая: в течение суток после подписки человек может приобрести со скидкой мой платный видеокурс. Так как вся информация о подписчиках хранится на сервере "SmartResponder.ru ", то обычный доступ (например, через БД ) к этим данным я не имел, а реализовывать это было нужно. Благо, у "SmartResponder.ru " есть свой собственный API , которым я и воспользовался.

Я нашёл в их API формат запроса, чтобы в результате вытащить дату подписки. Далее через cURL я отправил соответствующий запрос и получил искомую дату подписки для конкретного e-mail адреса . Далее стандартная обработка и вывод результата.

Работая с 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 - создать и взаимодействовать с ним, на чем мы сфокусируемся в наших проектах.