В изрядной доле проектов нужно интегрировать два или больше приложений. В самом тривиальном случае — фронтенд с бэкендом. В более сложном — мобильное приложение с бэкендом. В случае со звёздочкой — два бэкенда и другие извращения. Стандартом де-факто для таких задач в наше время считается API.
Кроме того, в вашем продукте может потребоваться реализовать дорогостоящую функцию, которая уже сделана в стороннем сервисе на отличненько. Например, если вам нужны карты, целесообразно использовать API Open Street Map или Яндекс.Карт, это сильно дешевле, чем пилить собственные карты.
Также вам пригодится API платёжных шлюзов, если нужно реализовать на сайте оплату чего-нибудь, неважно, физических товаров или виртуальных.
В наше время считается дурным тоном делать регистрацию и авторизацию на сайте логином и паролем, это делают через API социальных сетей, гугловский, фейсбучий, вконтактовский, телеграмовский.
Если у вас сайт с большим количеством контента, например, маркетплейс, имеет смысл реализовать API для использования ваших данных в сторонних сервисах (возможно, платно), это проще, чем постоянно банить десятки ботов, которые будут ваши данные парсить, создавая нагрузку на сервера.
Самая прозрачная аналогия с реальным миром — ресторан. Кухня — бэк, зал ресторана — фронт, официанты — API. Посетитель через зал посетителей стучится в API-официанта, даёт ему заказ. Официант доставляет заказ кухне-бэкенду, там его готовят и отдают официанту, который доставляет результат клиенту в зал ресторана. Если всё сильно упростить, реальное API работает именно так.
Различия REST и SOAP
Чаще всего в современной разработке встречаются REST и SOAP API. Давайте разберём, в чём разница.
REST
REST (от англ. Representational State Transfer — «передача репрезентативного состояния» или «передача „самоописываемого“ состояния») — архитектурный стиль взаимодействия компонентов распределённого приложения в сети.
Предполагает использование протокола HTTP для передачи данных.
Применяется преимущественно в вебе и в мобильных приложениях.
Ещё используется в облачных вычислениях.
Через REST API могут передаваться разные форматы данных, но обычно используется JSON.
Предполагает кэширование передаваемых данных.
Хорошо масштабируется.
SOAP
SOAP (от англ. Simple Object Access Protocol — простой протокол доступа к объектам) — протокол обмена структурированными сообщениями в распределённой вычислительной среде. Первоначально SOAP предназначался в основном для реализации удалённого вызова процедур (RPC).
При помощи SOAP данные могут передаваться не только через HTTP, но и, например, MQ.
Применяется, преимущественно, в Enterprise, для интеграции нескольких отдельно стоящих систем.
Данные передаются только в формате XML.
Данные не кэшируются.
Типы запросов
Метод обозначает тип производимого запроса, де-факто он является спецификацией операции, которую должен произвести сервер. Всего существует пять типов запросов:
- GET
- POST
- PUT
- PATCH
- DELETE
GET – используется для получения со стороны севера определенного ресурса. Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.
POST – нужен для создания определенного ресурса на сервере. Сервер создает в базе данных новую сущность и оповещает вас, был ли процесс создания успешным. По сути, это операция создания.
PUT и PATCH – используются для обновления определенной информации на сервере. В таком случае сервер просто изменяет информацию существующих сущностей в базе данных и оповещает об успехе выполнения операции.
DELETE – как и следует из названия, удаляет указанную сущность из базы или сигнализирует об ошибке, если такой сущности в базе не было.
Postman
Для тестирования API применяется инструмент Postman. Раньше он был плагином для Хрома, но сейчас это автономное приложение для любых платформ. Штуковина достаточно понятная интуитивно, разработчики чаще всего передают данные об API тестировщикам именно в виде коллекций Постман.
Есть публичное API для смешных переводов, например, эндопоинт для перевода на язык Мастера Йоды находится по адресу: https://api.funtranslations.com/translate/yoda.json
Эндпоинт принимает только один строковый параметр text. Отправим Постманом GET запрос на этот эндпоинт:
Как видите, API возвращает такой ответ:
{
"success": {
"total": 1
},
"contents": {
"translated": "Force be with you yoda,Polovec helloy you",
"text": "Hello Yoda, Polovec helloy you",
"translation": "yoda"
}
}Как нетрудно понять, эндоинт возвратил код успеха, а в поле контента передал три значения:
- translated — переведённый текст.
- text — исходный текст.
- translation — тип переводчика.
По такому же принципу работают любые REST API, только в реальных запросах параметров больше и они сложнее.
Применение в реальной разработке
Проектирует API обычно архитектор. Бэкенд-разработчики реализуют эндпоинты и пишут документацию. Фронтендеры или мобильные разработчики интегрируются с этим API, реализуют получение данных из него и отправку данных в него. Тестеры всё это проверяют.
Может сложиться так, что проект будет совсем маленьким и проектирование API поручат вам. Для такого случая предлагаю вам пример API спроектированного мной для мобильного приложения для операций с топливом.
Разное
Очень часто для использования API требуется авторизация. Для этого необходимо реализовать механизм выдачи токенов доступа каждому пользователю API, чтобы клиентское приложение добавляло эти токены к запросам. Посмотрите приложенный пример и поймёте, как это делается.
Если вы интегрируетесь со сторонней системой и успех проекта сильно зависит от её корректной работы, попросите QA реализовать пинговалку стороннего API, они умеют это делать, в том числе с помощью Постмана. Система будет с определённой периодичностью слать запросы на внешнее API и если ответы перестанут поступать, будет записывать такие события в лог, с помощью которого вы потом сможете доказать, что разработка тормозила из-за отваливающегося стороннего API.
Вот ещё хороший документ про API от пользователя Koray OKE:
В целом, это всё, что пиэму нужно знать об API.
1
