Categories: Технологии

Понимание основ работы API и REST API – краткое введение

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

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

REST – это стиль архитектуры API для распределенных систем. REST определяет, как данные представляются клиенту в удобном для него формате. Обмен данными происходит в формате JSON или XML (хотя сегодня более популярен формат JSON).

Понимание того, как данные обмениваются через Интернет

Обмен данными в Интернете происходит с помощью TCP/IP (протокол управления передачей/интернет-протокол). TCP/IP – это набор протоколов связи, который описывает, как взаимодействует огромное количество компьютеров, подключенных к Интернету.

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

TCP/IP использует стандартную модель связи клиент-сервер, когда клиент (компьютерное устройство) запрашивает ресурс у сервера (возможно, гораздо более крупного компьютерного устройства в удаленном месте). Соединения с использованием TCP/IP не сохраняют состояния – каждый запрос от клиента к серверу рассматривается как новый, сервер никогда не запоминает клиента. Это освобождает ресурсы на сервере, чтобы сделать его быстрее, и он быстрее отвечал на несколько запросов.

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

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

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

По сути, REST API-интерфейсы работают примерно так же, как и стандартные запросы TCP/IP, за исключением того, что здесь нет клиентов и серверов, а есть только два приложения, взаимодействующих друг с другом.

Кратко о различных шаблонах API

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

Стиль туннелирования

Туннелирование работает как система удаленных вызовов процедур (RPC), организованных в формате сообщений XML. RPC сам по себе является действительно старой технологией, которая лучше всего подходит для передачи команд и процедур. SOAP в некоторых случаях использует туннелирование.

SOAP – Простой протокол доступа к объектам

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

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

REST

REST – это действительно API-интерфейс «веб-сервисов», помещающий его на противоположную сторону SOAP. REST API основаны на URI (унифицированный идентификатор ресурса) и протоколе HTTP. REST API могут обмениваться данными в формате JSON или XML, хотя многие API REST отправляют данные в виде JSON.

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

Что такое REST API

Допустим, вы пытаетесь найти какое-то видео на YouTube. Вы открываете YouTube, набираете слово в поле поиска, нажимаете Enter, и вы видите список соответствующих видео. REST API работает аналогичным образом. Вы ищете что-то и получаете список результатов от службы, которую вы запрашиваете. Другой пример: вы как разработчик вызываете Instagram API, чтобы получить конкретного пользователя (ресурс), API возвращает вам состояние этого пользователя, включая его имя, количество постов, которые пользователь опубликовал в Instagram, сколько у него подписчиков, и так далее.

Каждый URL называется запросом, а отправленные вам данные называются ответом.

Анатомия запроса к API

Важно знать, что запрос состоит из четырех вещей:

Конечная точка (endpoint)
Метод (GET, POST, PUT, или DELETE)
Заголовки (HTTP заголовки, полный список здесь)
Данные (или тело; ответное сообщение)

Конечная точка (или маршрут) – это URL, который вы запрашиваете. Это отправная точка API, который вы запрашиваете. Например, корневой конечной точкой API Github является https://api.github.com, а корневой конечной точкой Twitter API является https://api.twitter.com.

REST API – определения дизайна. Рекомендации по проектированию

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

Ресурс	GET (чтение)	POST (создать)	PUT (обновить)	DELETE (удалить)
/cars	Возвращает список всех автомобилей	Создать новый автомобиль	Массовое обновление автомобилей (используется редко)	Удалить все автомобили (вероятно, вам не следует это реализовывать)
/cars/1955	Возвращает определенный автомобиль	Метод не разрешен (405)	Обновляет конкретный автомобиль	Удаляет определенный автомобиль

Метод GET и параметры его запроса не должны изменять состояние. Избегайте проектирования конечных точек вида:

GET /cars/1955?avaliable=true
GET /cars/1955/has-finished

Это очень плохо для вашего приложения. Если бот поисковой системы или какой-либо веб-сканер когда-либо завладеют этим URL…

Если вы должны изменить состояние, используйте POST, PUT или DELETE, как в таблице выше.

Используйте подресурсы для отношений

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

GET /users/1955/blogs

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

GET /users/1955/blogs/150

Обрабатывайте ошибки с помощью HTTP-кодов состояния

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

Здесь вы найдете полный список HTTP-кодов состояния сервера.

Обеспечивайте нумерацию страниц, сортировку и фильтрацию

Это, надеемся, понятно. Ваше приложение, скорее всего, будет иметь огромное хранилище информации. Неверным будет вызов эндпоинтов, который вернет все автомобили и отправит вам 100 000 автомобилей одновременно. Перегрузка вашего сервера будет сумасшедшей, и вы быстро сожжете свои ресурсы.

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

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

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

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

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

Авторизация

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

Краткое заключение

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

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