Как запустить api приложения
Перейти к содержимому

Как запустить api приложения

  • автор:

Краткое руководство. Настройка клиентского приложения для доступа к веб-API

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

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

Необходимые компоненты

  • Учетная запись Azure с активной подпиской. Создайте бесплатную учетную запись.
  • Завершение краткого руководства. Регистрация приложения
  • Завершение краткого руководства. Настройка приложения для предоставления веб-API

Добавление разрешений для доступа к веб-API

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

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

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

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

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

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
  2. Если у вас есть доступ к нескольким клиентам, используйте значок Параметры в верхнем меню, чтобы переключиться на клиент, содержащий регистрацию приложения из меню каталогов и подписок.
  3. Перейдите к приложениям>удостоверений>Регистрация приложений и выберите клиентское приложение (а не веб-API).
  4. Выберите Разрешения API>Добавить разрешение>Мои API.
  5. Выберите предварительно зарегистрированный веб-API. Параметр Делегированные разрешения выбран по умолчанию. Делегированные разрешения подходят для клиентских приложений, которые обращаются к веб-API в качестве пользователя, выполнившего вход, и доступ которых должен быть ограничен разрешениями, выбираемыми на следующем шаге. Для этого примера оставьте параметр Делегированные разрешения выбранным. Параметр Разрешения приложения предназначен для приложений типа службы или управляющей программы, которым необходим доступ к веб-API без участия пользователя при входе или предоставлении согласия. Пока вы не определите роли приложений для веб-API, этот параметр будет отключен.
  6. В разделе Выбор разрешений разверните ресурс, области которого определены для веб-API, и выберите разрешения, которым клиентское приложение должно обладать от имени пользователя, выполнившего вход. Если вы использовали примеры имен областей, указанные в предыдущем кратком руководстве, вы увидите имена Employees.Read.All и Employees.Write.All. Выберите Employees.Read.All или другое разрешение, которое могло быть создано заранее.
  7. Чтобы завершить процесс, выберите Добавление разрешений.

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

Configured permissions pane in the Azure portal showing the newly added permission

Вы также можете увидеть разрешение User.Read для API Microsoft Graph. Это разрешение добавляется автоматически при регистрации приложения на портале Azure.

Добавление разрешений для доступа к Microsoft Graph

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

Делегированное разрешение для Microsoft Graph

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

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
  2. Если у вас есть доступ к нескольким клиентам, используйте значок Параметры в верхнем меню, чтобы переключиться на клиент, содержащий регистрацию приложения из меню каталогов и подписок.
  3. Перейдите к приложениям>удостоверений>Регистрация приложений и выберите клиентское приложение.
  4. Выберите Разрешения API>Добавить разрешение>Microsoft Graph
  5. Выберите Делегированные разрешения. Microsoft Graph предоставляет множество разрешений, наиболее часто используемые из которых отображаются в верхней части списка.
  6. В разделе Выбор разрешений выберите следующие разрешения.

Разрешение Description
email Просмотр пользовательских адресов электронной почты.
offline_access Ведение доступа к данным, к которым вам был предоставлен доступ
openid Вход пользователей
profile Просмотр базового профиля пользователей

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

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

Разрешение приложения для Microsoft Graph

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

В последующих шагах в качестве примера вы предоставляете разрешение Files.Read.All Microsoft Graph.

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
  2. Если у вас есть доступ к нескольким клиентам, используйте значок Параметры в верхнем меню, чтобы переключиться на клиент, содержащий регистрацию приложения из меню каталогов и подписок.
  3. Перейдите к приложениям>удостоверений>Регистрация приложений и выберите клиентское приложение.
  4. Выберите Разрешения API>Добавить разрешение>Microsoft Graph>Разрешения приложения.
  5. Все разрешения, предоставляемые Microsoft Graph, отображаются в разделе Выбор разрешений.
  6. Выберите разрешение или разрешения, которые вы хотите предоставить приложению. Например, вы можете использовать управляющее приложение, которое сканирует файлы в вашей организации, уведомляя об определенном типе или имени файла. В разделе Выбор разрешения разверните Файлы, а затем выберите разрешение Files.Read.All.
  7. Выберите Добавить разрешения.

Некоторые разрешения, такие как разрешение Microsoft Graph Files.Read.All, требуют согласия администратора. Чтобы предоставить согласие администратора, выберите Предоставление согласия администратора, как описано далее в разделе Кнопка «Согласие администратора».

Настройка учетных данных клиента

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

Дополнительные сведения о разрешениях API и согласии администратора

Панель Разрешения API для регистрации приложения содержит таблицу Настроенные разрешения, а также может содержать таблицу Другие предоставленные разрешения. Обе таблицы и кнопка согласия администратора описаны в следующих разделах.

Настроенные разрешения

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

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

Разрешения, отображаемые в этой таблице, можно добавить или удалить, выполнив описанные выше действия или указания из раздела Другие предоставленные разрешения (ниже). Администратор может предоставить согласие администратора для всех разрешений API, отображаемых в таблице, и отозвать согласие на индивидуальные разрешения.

Другие предоставленные разрешения

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

Можно добавить полный набор разрешений API или отдельные разрешения, отображаемые в этой таблице, в таблице Настроенные разрешения. Администратор может отозвать согласие для API или отдельных разрешений в этом разделе.

Кнопка согласия администратора

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

Grant admin consent button highlighted in the Configured permissions pane in the Azure portal

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

Configure permissions table in Azure portal showing admin consent granted for the Files.Read.All permission

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

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

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

Руководство по использованию REST API

Платформа@Mail.Ru предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в Mail.Ru. Одним из способов такого взаимодействия вляется использование REST API.

Что такое REST API

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

REST API предназначено, в основном, для запросов с внешних серверов к серверам Mail.Ru. Для запросов с веб-клиентов — клиентской части социального приложения или от сайта — существуют JS API и Flash-библиотека, которые более удобны и просты в использовании.

Как использовать API

Все вызовы методов API — это GET или POST HTTP-запросы к URL http://www.appsmail.ru/platform/api с некоторым набором параметров. Вы выбираете в документации нужный метод, например, users.getInfo rest , формируете запрос согласно документации метода, и осуществляете этот запрос. В ответ на запрос вы получаете его результат, который также описан в документации каждой функции. Кодировка результата — UTF-8.

Например, на PHP для осуществления такого запроса можно использовать cURL, на Perl — LWP::Simple, на Python — urllib, использовать cURL из командной строки и даже просто ваш браузер.

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

Данные запроса могут передаваться в виде query-строки (после знака ?) при использовании метода GET, либо в теле POST-запроса. Помните, что в случае GET-запроса, параметры должны быть закодированы с помощью URL encoding.

На данный момент, API не делает различий между GET- и POST-запросами. Тем не менее, помните, что существует ограничение на длину URL запроса — 2048 символов. Поэтому мы рекомендуем вам выполнять запросы на получение информации с помощью метода GET (они обычно легко умещаются в ограничение), а запросы на изменение данных — загрузку фотографии, новый пост в «Что нового» или гостевую книгу — с помощью метода POST. Так вы не будете ограничены длиной запроса, кроме того, такое использование больше соответствует спецификации протокола HTTP.

Параметры запроса

В каждом запросе должен присутствовать набор обязательных параметров. Также для каждой функции в ее документации определены дополнительные параметры, нужные только для этой функции. Текстовые значения параметров должны быть переданы в кодировке UTF-8. Одинаковые для всех функций параметры перечислены ниже.

Имя Тип Описание
method string название вызываемого метода, например, users.getInfo; обязательный параметр
app_id int идентификатор приложения; обязательный параметр
sig string подпись запроса; обязательный параметр
session_key string сессия текущего пользователя
uid uint64 идентификатор пользователя, для которого вызывается метод; данный аргумент должен быть указан, если не указан session_key
secure bool флаг, обозначающий, что запрос идет по защищенной схеме «сервер-сервер»; возможные значения: 1 или 0; по-умолчанию 0
format string формат выдачи ответа API; возможные значения: xml или json; по-умолчанию json

Порядок следования параметров в запросе значения не имеет, порядок параметров важен только при расчете подписи.

Идентификатор приложения app_id уникален для каждого приложения или сайта и его можно узнать в разделе Мои разработки для приложений и Мои сайты для сайтов.

Флаг secure и подпись sig расчитываются в зависимости от схемы запроса (см. ниже).

Авторизация запроса

Параметры session_key и uid отвечают за авторизацию, то есть от лица какого пользователя происходит запрос. В зависимости от этого одна и та же функция в одном и том же приложении может возвращать немного разные результаты, например, когда один пользователь имеет доступ к каким-то закрытым данным, а другой нет. session_key используется для выполнения запросов по схеме «клиент-сервер» (см. ниже), а uid — по схеме «сервер-сервер».

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

Значение uid вы можете сохранять в вашей базе зарегистрированных пользователей и использовать в тех случаях, когда пользователь не использует выше приложение, и, соответственно, сессия не доступна. Например, когда вы отправляете пользователям уведомления с помощью функции notifications.send rest .

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

Подпись запроса

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

Клиент-сервер

Схема клиент-сервер предназначена для случаев, когда REST API используется из клиента социального приложения, клиентского кода сайта или отдельного мобильного или desktop-приложения.

Если вы хотите использовать схему клиент-сервер, то передайте в параметрах запроса secure=0 и расчитайте sig по следующему алгоритму:

sig = md5(uid + params + private_key)

Значение params — это конкатенация пар «имя=значение» отсортированных в алфавитом порядке по «имя», где «имя» — это название параметра, передаваемого в функцию API, «значение» — значение параметра. Разделитель в конкатенации не используется. Параметр sig при расчете подписи не учитывается, все остальные параметры запроса должны учитываться при расчете.

Значение uid — идентификатор текущего пользователя приложения. Значение private_key вы можете взять из настроек приложения.

Пусть uid=1324730981306483817 и private_key=7815696ecbf1c96e6894b779456d330e Запрос, который вы хотите выполнить: http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa Тогда: params = app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa sig = md5(1324730981306483817app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa7815696ecbf1c96e6894b779456d330e) = 5073f15c6d5b6ab2fde23ac43332b002 Итоговый запрос: http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa&sig=5073f15c6d5b6ab2fde23ac43332b002

Вот пример функции на PHP, которая возвращает значение подписи запроса по схеме клиент-сервер:

function sign_client_server(array $request_params, $uid, $private_key) < ksort($request_params); $params = ''; foreach ($request_params as $key =>$value) < $params .= "$key=$value"; >return md5($uid . $params . $private_key); >

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

Сервер-сервер

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

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

Схема сервер-сервер использует отдельный ключ secret_key, который мы настоятельно рекомендуем вам хранить только на ваших серверах и использовать только при запросах с них к серверам Платформы.

Когда вы хотите использовать схему сервер-сервер, вы должны передать в параметрах запроса параметр secure=1 и расчитать значение параметра sig следующим образом:

sig = md5(params + secret_key)
Пусть uid=1324730981306483817 и secret_key=3dad9cbf9baaa0360c0f2ba372d25716 Запрос, который вы хотите выполнить: http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa&secure=1 Тогда: params = app_id=423004method=friends.getsecure=1session_key=be6ef89965d58e56dec21acb9b62bdaa sig = md5(app_id=423004method=friends.getsecure=1session_key=be6ef89965d58e56dec21acb9b62bdaa3dad9cbf9baaa0360c0f2ba372d25716) = 4a05af66f80da18b308fa7e536912bae Итоговый запрос: http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa&secure=1&sig=4a05af66f80da18b308fa7e536912bae

Вот пример функции на PHP, которая возвращает значение подписи запроса по схеме сервер-сервер:

function sign_server_server(array $request_params, $secret_key) < ksort($request_params); $params = ''; foreach ($request_params as $key =>$value) < $params .= "$key=$value"; >return md5($params . $secret_key); >

Безопасность схемы сервер-сервер основывается на том, что secret_key знаете только вы и Платформа. Поэтому никогда не раскрывайте его третьим лицам. Если у вас возникли сомнения в безопасности secret_key, перегенерите его в настройках приложения.

Привилегии

Установка приложения (первая авторизация) дает приложению возможность получать информацию о пользователе, его друзьях, фотографиях, музыке. То есть пользоваться функциями users.getInfo rest , friends.get rest , photos.get rest , audios.get rest и подобными. Также приложение может отсылать пользователю уведомления с помощью функции notifications.send rest . Установка в большом и мобильном мире производится автоматически Платформой. Для установки standalone-приложений необходимо использовать OAuth-авторизацию для standalone-приложений. Для установки (коннекта) внешнего сайта надо пользоваться либо OAuth-авторизацией для сайтов, либо функцией connect.login js .

Для standalone-приложений и сайтов запросить привилегии можно либо через параметр scope OAuth-авторизации, либо в параметрах функции connect.login js .

Привилегии распространяются только на функции REST API. Функции JS API не зависят от привилегий и при попытке записи в Мой Мир всегда показывают пользователю диалог с запросом подтверждения действия. Вы можете выбирать просить ли у пользователя привилегии и использовать REST API или использовать диалоги из JS API.

Не все привилегии доступны во всех контекстах:

Название привилегии Смысл Функции Мой Мир Мобильный Мир Standalone-приложения Сайты
photos приложение может загружать фотографии photos.upload rest , photos.createAlbum rest нет нет есть есть
guestbook приложение может добавлять записи в гостевые книги пользователей guestbook.post rest нет нет есть есть
stream приложение может добавлять записи в ленту «Что нового» пользователя stream.post rest нет нет есть есть
messages приложение имеет доступ к личным сообщениям пользователя messages.getThread rest , messages.getThreadsList rest , messages.post rest , messages.getUnreadCount rest нет нет есть есть
events приложение имеет доступ к событиям пользователя в Моем Мире events.getUnreadCount rest нет нет есть есть

Функции REST API

  • events.getNewCount
  • friends.get
  • friends.getAppUsers
  • friends.getInvitationsCount
  • friends.getOnline
  • guestbook.post
  • jsapi.popup
  • mail.getUnreadCount
  • messages.getThread
  • messages.getThreadsList
  • messages.getUnreadCount
  • messages.post
  • mobile.getCanvas
  • multipost.send
  • multipost.send-commercial
  • notifications.send
  • notify.bulk
  • payments.openDialog
  • photos.createAlbum
  • photos.get
  • photos.getAlbums
  • photos.upload
  • stream.comment
  • stream.get
  • stream.getByAuthor
  • stream.like
  • stream.post
  • stream.share
  • stream.unlike
  • titles.del
  • titles.list
  • titles.update
  • titles.user_drop
  • users.getBalance
  • users.getInfo
  • users.hasAppPermission
  • users.isAppUser
  • widget.set

Другие технологии

  • JS API
  • Flash-библиотека
  • сторонние библиотеки

Что такое интерфейс прикладного программирования (API)?

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

Что значит API?

API – Application Programming Interface, что значит программный интерфейс приложения. В контексте API слово «приложение» относится к любому ПО с определенной функцией. Интерфейс можно рассматривать как сервисный контракт между двумя приложениями. Этот контракт определяет, как они взаимодействуют друг с другом, используя запросы и ответы. Документация API содержит информацию о том, как разработчики должны структурировать эти запросы и ответы.

Как работают API?

Архитектура API обычно объясняется с точки зрения клиента и сервера. Приложение, отправляющее запрос, называется клиентом, а приложение, отправляющее ответ, называется сервером. Итак, в примере с погодой база данных службы – это сервер, а мобильное приложение – это клиент.

Существует четыре различных способа работы API в зависимости от того, когда и почему они были созданы.

SOAP API

SOAP – Simple Object Access Protocol, т. е. простой протокол доступа к объектам. Клиент и сервер обмениваются сообщениями посредством XML. Это менее гибкий API, который был более популярен в прошлом.

RPC API

Такие API называются системой удаленного вызова процедур. Клиент выполняет функцию (или процедуру) на сервере, и сервер отправляет результат обратно клиенту.

Websocket API

Websocket API – это еще одна современная разработка web API, которая использует объекты JSON для передачи данных. WebSocket API поддерживает двустороннюю связь между клиентскими приложениями и сервером. Сервер может отправлять сообщения обратного вызова подключенным клиентам, что делает его более эффективным, чем REST API.

REST API

На сегодняшний день это самые популярные и гибкие API-интерфейсы в Интернете. Клиент отправляет запросы на сервер в виде данных. Сервер использует этот клиентский ввод для запуска внутренних функций и возвращает выходные данные обратно клиенту. Давайте рассмотрим API REST более подробно ниже.

Что такое REST API?

REST – это Representational State Transfer, т. е. передача репрезентативного состояния. REST определяет набор функций, таких как GET, PUT, DELETE и т. д., которые клиенты могут использовать для доступа к данным сервера. Клиенты и серверы обмениваются данными по протоколу HTTP.

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

Что такое web API?

Web API или Web Service API –это интерфейс обработки приложений между веб-сервером и веб-браузером. Все веб-сервисы являются API, но не все API являются веб-сервисами. REST API – это особый тип Web API, в котором используется стандартный архитектурный стиль, описанный выше.

Различные термины, которые относятся к API, такие как Java API или сервисные API, существуют потому, что исторически API были созданы до всемирной паутины. Современные web API – это REST API, и эти термины могут использоваться взаимозаменяемо.

Что такое интеграции API?

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

Каковы преимущества REST API?

REST API имеет четыре главных преимущества.

1. Интеграция

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

2. Инновации

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

3. Расширение

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

4. Простота обслуживания

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

Какие типы API существую?

API классифицируются как по архитектуре, так и по сфере применения. Мы уже рассмотрели основные типы архитектур API, поэтому мы предлагаем рассмотреть сферы применения.

Частные API

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

Общедоступные API

Это API с общим доступом и могут быть использованы кем угодно. С этими типами API может быть (но не обязательно) сопряжена некоторая авторизация и стоимость.

Партнерские API

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

Составные API

Эти API объединяют два или более разных API для решения сложных системных требований или поведения.

Что такое адрес API и почему он важен?

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

1. Безопасность

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

2. Производительность

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

Как обезопасить REST API?

Все API должны быть защищены посредством надлежащей аутентификации и мониторинга. Описание двух основных способов защиты безопасности REST API см. ниже.

1. Токены аутентификации

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

2. Ключи API

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

Как создать API?

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

1. План API

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

2. Разработка API

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

3. Тестирование API

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

4. Документирование API

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

5. Вывод API на рынок

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

Что такое тестирование API?

Стратегии тестирования API аналогичны другим методологиям тестирования ПО. Основное внимание уделяется проверке ответов сервера. Тестирование API включает описанные ниже аспекты.

  • Выполнение нескольких запросов к адресам API для тестирования производительности.
  • Написание модульных тестов для проверки бизнес-логики и функциональной корректности.
  • Тестирование безопасности путем имитации системных атак.

Как написать документацию по API?

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

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

Как использовать API?

Шаги по внедрению нового API см. ниже.

  1. Получение ключа API Выполняется путем создания проверенной учетной записи у поставщика API.
  2. Установка клиента API HTTP Этот инструмент позволяет легко структурировать запросы API, используя полученные ключи API.
  3. В отсутствие клиента API можно попробовать самостоятельно структурировать запрос в браузере, обратившись к документации по API.
  4. Как только вы освоитесь с новым синтаксисом API, вы сможете начать использовать его в коде.

Где найти новые API?

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

Популярные веб-сайты API см. ниже.

  • Rapid API – крупнейший мировой рынок API с более чем 10 000 общедоступных API и 1 млн активных разработчиков на веб-сайте. RapidAPI позволяет пользователям тестировать API непосредственно на платформе перед совершением покупки.
  • Public API – платформа группирует удаленные API в 40 нишевых категорий, что упрощает просмотр и поиск подходящего для ваших нужд объекта.
  • APIForThat и APIList – на обоих веб-сайтах есть списки из более чем 500 web-API, а также подробная информация о том, как их использовать.

Что такое шлюз API?

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

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

Что такое GraphQL?

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

AWS AppSync – это полностью управляемый сервис, который упрощает разработку API-интерфейсов GraphQL, выполняя тяжелую работу по безопасному подключению к источникам данных, таким как AWS DynamoDB, AWS Lambda и т. д. AWS AppSync может передавать обновления данных в режиме реального времени через Websocket миллионам клиентов. Для мобильных и веб-приложений AppSync также обеспечивает локальный доступ к данным, когда устройства отключаются. После развертывания AWS AppSync автоматически масштабирует подсистему выполнения API GraphQL вверх или вниз в соответствии с текущим объемом запросов к API.

Как получить сервисы Amazon API?

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

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

AWS AppSync предоставляет возможность настраивать, администрировать и обслуживать полностью управляемую систему API GraphQL со встроенной бессерверной инфраструктурой высокого уровня доступности. Вы платите только за то, что реально используете. Минимальная плата или обязательный уровень использования отсутствует. Чтобы начать работу, войдите в консоль AWS AppSync.

RESTful API для сервера – делаем правильно (Часть 1)

В 2007-м Стив Джобс представил iPhone, который произвел революцию в высокотехнологичной индустрии и изменил наш подход к работе и ведению бизнеса. Сейчас 2012-й и все больше и больше сайтов предлагают нативные iOS и Android клиенты для своих сервисов. Между тем не все стартапы обладают финансами для разработки приложений в дополнение к основному продукту. Для увеличения популярности своего продукта эти компании предлагают открытые API, которыми могут воспользоваться сторонние разработчики. Пожалуй Twitter был первым в этой сфере и теперь число компаний, последовавших этой стратегии, растет стремительно. Это действительно отличный способ создать привлекательную экосистему вокруг своего продукта.

Жизнь стартапа полна перемен, поворотных моментов, в которых от принятых решений зависит дальнейшая судьба проекта. Если ваша кодовая база не сможет обеспечить воплощение самых разных ваших решений – вы проиграли. Серверный код, который достаточно гибок для того, чтобы в короткие сроки подстроиться под нужды бизнеса, решает быть проекту или нет. Успешные стартапы не те, которые просто предложили отличную идею, но те, которые смогли ее качественно воплотить. Успех стартапа зависит от успешности его продукта, будь то приложение под iOS, сервис или API. Последние три года я работал над разными приложениями под iOS (в основном для стартапов) использовавшими web сервисы и в этом блоге я попытался собрать накопленные знания воедино и показать вам лучшие методики, которым вам нужно следовать при разработке RESTful API. Хороший RESTful API тот, который можно менять легко и просто.

Целевая аудитория

Этот пост предназначен для тех, кто обладает знаниями в разработке RESTful API уровня от средних до продвинутых. А также некоторыми базовыми знаниями объектно-ориентированного (или функционального) программирования на таких серверных языках как Java/Ruby/Scala. (Я намеренно проигнорировал PHP или Programmable Hyperlinked Pasta).
Прим. Пер. Тут автор привел ссылку на полушутливую статью о истории языков программирования где PHP был расшифрован как Programmable Hyperlinked Pasta (Программируемая Гиперссылочная Лапша). Что как бы характеризует отношение автора к PHP.

Структура и организация статьи

Статья довольно подробна и состоит из двух частей. Первая описывает основы REST тогда как вторая описывает документирование и поддержку разных версий вашего API. Первая часть для новичков, вторая для профи. Я не сомневаюсь, что вы профи, а потому вот вам ссылка чтобы перескочить сразу к главе «Документирование API». Возможно, вам стоит начать оттуда, если вам кажется, что этот пост из разряда «Многа букаф, ниасилил…».

Принципы RESTful

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

Независимость от состояния (Statelessness)

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

Давайте представим, что у вас есть стартап под названием «Новый Фейсбук». Хороший пример, где разработчик мог совершить ошибку это предоставление вызова API, который позволяет мобильному устройству установить последний прочитанный элемент в потоке (назовем его лентой Фейсбука). Вызов API, обычно возвращающий ленту (назовем его /feed), теперь будет возвращать элементы, которые новее установленного. Звучит умно, не правда ли? Вы «оптимизировали» обмен данными между клиентом и сервером? А вот и нет.

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

Независимость от состояния означает, что данные, возвращаемые определенным вызовом API, не должны зависеть от вызовов, сделанных ранее.

Правильный способ оптимизации данного вызова – передача времени создания последней прочитанной записи ленты в качестве параметра вызова API, возвращающего ленту (/feed?lastFeed=20120228). Есть и другой, более «правильный» метод – использование заголовка HTTP If-Modified-Since. Но мы пока не будем углубляться в эту сторону. Мы обсудим это во второй части.

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

Кэшируемая и многоуровневая архитектура

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

Клиент – серверное разделение и единый интерфейс

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

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

REST запросы и четыре HTTP метода

GET
POST
PUT
DELETE

Принцип “кэшируемости” и GET запросы

Главное, что следует помнить — вызов, совершенный через GET не должен менять состояние сервера. Это в свою очередь значит, что ваши запросы могут кэшироваться любым промежуточным прокси (снижение нагрузки). Таким образом Вы, как разработчик сервера, не должны публиковать GET методы, которые меняют данные в вашей базе данных. Это нарушает философию RESTful, особенно второй пункт, описанный выше. Ваши GET вызовы не должны даже оставлять записей в access.log или обновлять данные типа “Last logged in”. Если вы меняете данные в базе, это обязательно должны быть методы POST/PUT.

То самое обсуждение POST vs PUT

Спецификация HTTP 1.1 гласит, что PUT идемпотентен. Это значит, что клиент может выполнить множество PUT запросов по одному URI и это не приведет к созданию записей дубликатов. Операции присвоения — хороший пример идемпотентной операции

String userId = this.request["USER_ID"]; 

Даже если эту операцию выполнить дважды или трижды, никакого вреда не будет (кроме лишних тактов процессора). POST же с другой стороны не идемпотентен. Это что-то вроде инкремента. Вам следует использовать POST или PUT с учетом того является ли выполняемое действие идемпотентным или нет. Говоря языком программистов, если клиент знает URL объекта, который нужно создать, используйте PUT. Если клиент знает URL метода/класса создающего нужный объект, используйте POST.

PUT www.example.com/post/1234 

Используйте PUT если клиент знает URI, который сам бы мог быть результатом запроса. Даже если клиент вызовет это PUT метод много раз, какого либо вреда или дублирующих записей создано не будет.

POST www.example.com/createpost 

Используйте POST если сервер сам создает уникальный идентификатор и возвращает его клиенту. Дублирующие записи будут создаваться если этот запрос будет повторяться позже с такими же параметрами.
Более подробная информация в данном обсуждении.

Метод DELETE

DELETE абсолютно однозначен. Он идемпотентен как и PUT, и должен использоваться для удаления записи если таковая существует.

REST ответы

Ответы от Вашего RESTful сервера могут использовать в качестве формата XML или JSON. Лично я предпочитаю JSON, поскольку он более лаконичен и по сети передается меньший объем данных нежели при передаче такого же ответа в формате XML. Разница может быть порядка нескольки сотен килобайт, но, с учетом скоростей 3G и нестабильности обмена с мобильными устройствами, эти несколько сотен килобайт могут иметь значение.

Аутентификация

Аутентификация должна производиться через https и клиент должен посылать пароль в зашифрованном виде. Процесс получения sha1 хэша NSString в Objective-C достаточно понятен и прост и приведенный код наглядно это показывает.

- (NSString *) sha1

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

RFC 2617 описывает два способа аутентификации на HTTP сервере. Первый — это Basic Access, второй Digest. Для мобильных клиентов подходит любой из этих двух методов и большинство серверных (и клиентских тоже) языков обладают встроенными механизмами для реализации таких схем аутентификации.

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

Facebook Graph API это наиболее развитая и распространенная реализация oAuth на данный момент. Используя oAuth, пользователи Facebook могут давать доступ к своим фотографиям сторонним приложениям без публикации другой приватной и идентификационной информации (логин/пароль). Пользователь также может ограничить доступ нежелательным приложениям без необходимости менять свой пароль.

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

Документирование API

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

Документация

Первым шагом я бы порекомендовал подумать об основных, высокоуровневых структурах данных (моделях), которыми оперирует ваше приложение. Затем подумайте над действиями, которые можно произвести над этими компонентами. Документация по foursquare API хороший пример, который стоит изучить перед тем как начать писать свою. У них есть набор высокоуровневых объектов, таких как места, пользователи и тому подобное. Также у них есть набор действий, которые можно произвести над этими объектами. Поскольку вы знаете высокоуровневые объекты и действия над ними в вашем продукте, создание структуры вызовов API становится проще и понятней. Например, для добавления нового места логично будет вызвать метод наподобие /venues/add

Документируйте все высокоуровневые объекты. Затем документируйте запросы и ответы на них, используя эти высокоуровневые объекты вместо простых типов данных. Вместо того, чтобы писать “Этот вызов возвращает три строковых поля, первое содержит id, второе имя, а третье описание” пишите “Этот вызов возвращает структуру (модель), описывающую место”.

Документирование параметров запроса

Давайте представим, что у Вас есть API, позволяющий пользователю входить, используя Facebok token. Вызовем этот метод как /login.

Request /login Headers Authorization: Token XXXXX User-Agent: MyGreatApp/1.0 Accept: application/json Accept-Encoding: compress, gzip Parameters Encoding type – application/x-www-form-urlencoded token – “Facebook Auth Token” (mandatory) profileInfo = “json string containing public profile information from Facebook” (optional) 

Где profileinfo высокоуровневый объект. Поскольку вы уже задокументировали внутреннюю структуру этого объекта то такого простого упоминания достаточно. Если Ваш сервер использует такие же Accept, Accept-Encoding и параметр Encoding type всегда вы можете задокументировать их отдельно, вместо повторения их во всех разделах.

Документирование параметров ответа

Ответы на вызовы API должны также быть задокументированы, основываясь на высокоуровневой модели объектов. Цитируя тот же пример foursquare, вызов метода /venue/#venueid# вернет структуру данных (модель), описывающую место проведения мероприятия.

Обмен идеями, документирование или информирование других разработчиков о том, что вы вернете в ответ на запрос станет проще если Вы задокументируете ваш API используя структуру объектов (моделей). Наиболее важный итог этой главы — это необходимость воспринимать документацию как контракт, который заключаете Вы, как разработчик серверной части и разработчики клиентских приложений (iOS/Android/Windows Phone/Чтобытонибыло).

Причины создания новых и прекращения поддержки старых версий вашего API

До появления мобильных приложений, в эпоху Web 2.0 создание разных версий API не было проблемой. И клиент (JavaScript/AJAX front-end) и сервер разворачивались одновременно. Потребители (ваши клиенты) всегда использовали самую последнюю версию клиентского ПО для доступа к системе. Поскольку вы — единственная компания, разрабатывающая как клиентскую так и серверную часть, вы полностью контролируете то как используется ваш API и изменения в нем всегда сразу же применялись в клиентской части. К сожалению это невозможно с клиентскими приложениями, написанными под разные платформы. Вы можете развернуть API версии 2, считая что все будет отлично, однако это приведет к неработоспособности приложений под iOS, использующих старую версию. Поскольку еще могут быть пользователи, использующие такие приложения несмотря на то, что вы выложили обновленную версию в App Store. Некоторые компании прибегают к использованию Push уведомлений для напоминаний о необходимости обновления. Единственное к чему это приведет — потеря такого клиента. Я видел множество айфонов, у которых было более 100 приложений, ожидающих обновления. Шансы, что ваше станет одним из них, весьма велики. Вам всегда надо быть готовым к разделению вашего API на версии и к прекращению поддержки некоторых из них как только это потребуется. Однако поддерживайте каждую версию своего API не менее трех месяцев.

Разделение на версии

Развертывание вашего серверного кода в разные папки и использование разных URL для вызовов не означает что вы удачно разделили ваш API на версии.
Так example.com/api/v1 будет использоваться версией 1.0 приложения, а ваша свежайшая и крутейшая версия 2.0 будет использовать example.com/api/v2

Когда вы делаете обновления, вы практически всегда вносите изменения во внутренние структуры данных и в модели. Это включает изменения в базе данных (добавление или удаление столбцов). Для лучшего понимания давайте представим, что ваш “новый Фейсбук” имеет вызов API, называемый /feed который возвращает объект “Лента”. На сегодня, в версии 1, ваш объект “Лента” включает URL аватарки пользователя (avatarURL), имя пользователя (personName), текст записи (feedEntryText) и время создания (timeStamp) записи. Позднее, в версии 2, вы представляете новую возможность, позволяющую рекламодателям размещать описания своих продуктов в ленте. Теперь объект “Лента” содержит, скажем так, новое поле “sourceName”, которое перекрывает собой имя пользователя при отображении ленты. Таким образом приложение должно отображать “sourceName” вместо “personName”. Поскольку приложению больше не нужно отображать “personName” если задана “sourceName”, вы решаете не отправлять “personName” если есть “sourceName”. Это все выглядит неплохо до тех пор, пока старая версия вашего приложения, версия 1 не обратится к обновленному серверу. Она будет отображать ваши рекламные записи из ленты без заголовка поскольку “personName” отсутствует. “Грамотный” способ решения такой проблемы — отправлять как “personName”, так и “sourceName”. Но, друзья, жизнь не всегда так проста. Как разработчик вы не сможете отслеживать все одиночные изменения которые когда либо были произведены с каждой моделью данных в вашем объекте. Это не очень эффективный способ внесения изменений поскольку через пол года вы практически забудете почему и как что-то было добавлено к вашему коду.

Возвращаясь к web 2.0, это не было проблемой вообще. JavaScript клиент немедленно модифицировался для поддержки изменений в API. Однако установленные iOS приложения от вас больше не зависят. Теперь их обновление — прерогатива пользователя.

У меня есть элегантное решение для хитрых ситуаций подобного толка.

Парадигма разделения на версии через URL

Первое решение — это разделение с использованием URL.
api.example.com/v1/feeds будет использоваться версией 1 iOS приложения тогда как
api.example.com/v2/feeds будет использоваться версией 2.
Несмотря на то, что звучит это все неплохо, вы не сможете продолжать создание копий вашего серверного кода для каждого изменения в формате возвращаемых данных. Я рекомендую использование такого подхода только в случае глобальных изменений в API.

Парадигма разделения на версии через модель

Выше я показал как документировать ваши структуры данных (модели). Рассматривайте эту документацию как контракт между разработчиками серверной и клиентской частей. Вам не следует вносить изменения в модели без изменения версии. Это значит, что в предыдущем случае должно быть две модели, Feed1 и Feed2.

В Feed2 есть поле sourceName и она возвращает sourceName вместо personName если sourceName установлен. Поведение Feed1 остается таким же, как это было оговорено в документации. Алгоритм работы контроллера будет примерно таким:

Вам следует переместить логику создания экземпляра класса в отдельный класс согласно паттерну Factory method. Соответствующий код контроллера должен выглядеть примерно так:

Feed myFeedObject = Feed.createFeedObject("1.0"); myFeedObject.populateWithDBObject(FeedDao* feedDaoObject); 

Где решение о версии используемого API будет принимать контроллер в соответствии с полем UserAgent текста запроса.

Дополнение:
Вместо использования номера версии из строки UserAgent, правильней будет использовать номер версии в заголовке Accept. Таким образом вместо отправки

Accept: application/json 
Accept: application/myservice.1.0+json 

Таким образом у вас появляется возможность указывать версию API для каждого запроса к REST серверу. Спасибо читателям hacker news за этот совет.

Контроллер использует метод Feed factory для создания корректного объекта feed (лента) основываясь на информации из запроса клиента (все запросы имеют в своем составе поле UserAgent которое выглядит наподобие AppName/1.0) касающейся версии. Когда вы разрабатываете сервер таким образом, любое изменение будет простым. Внесение изменений не будет нарушать имеющиеся соглашения. Просто создавайте новые структуры данных (модели), вносите изменения в factory method для создания экземпляра новой модели для новой версии и все!

При использовании такого подхода ваши приложения версий 1 и 2 могут продолжать работать с одним сервером. Ваш контроллер может создавать объекты версии 1 для старых клиентских приложений и объекты версии 2 для новых.

Прекращение поддержки

С предложенной выше парадигмой разделения API на версии через модель прекращение поддержки вашего API становится намного проще. Это очень важно на последних стадиях когда вы публикуете ваш API. Когда вы делаете глобальное обновление API проведите ревизию всех factory method в ваших моделях в соответствии с изменениями вашей бизнес логики.

Если, в ходе релиза версии 3 вашего API, вы решаете прекратить поддержку версии 1 то для этого достаточно удалить соответствующие модели и удалить строки, создающие их экземпляры в ваших factory method-ах. Создание новых версий и прекращение поддержки старых обязательно будут сопровождать ваш проект показывая насколько он гибок для поддержки ключевых решений, диктуемых бизнесом. Бизнес, неспособный к резким переменам и поворотам, обречен. Обычно неспособность к ключевым переменам обусловлена техническим несовершенством проекта. Указанная техника способна решить такую проблему.

Кэширование

Еще один немаловажный момент, касающийся производительности, которому следует уделить внимание — это кэширование. Если вы считаете, что это задача клиентского приложения подумайте хорошенько. В части 2 этой статьи я расскажу как организовать кэширование, используя средства http 1.1.

Обработка ошибок и интернационализация вашего API

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

От переводчика:
Сам я не являюсь разработчиком под iOS и web-сервисов не разрабатывал, мой уровень в этой области можно описать как «Собираюсь стать начинающим». Но тема мне интересна и статья понравилась, причем настолько, что решил перевести.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *