API. REST API
Что такое API
API (Application Programmig Interface, "программный интерфейс приложения") - интерфейс для взаимодействия между сайтом и сторонними приложениями. Например, авторизация через социальные сети или Госуслуги, или при публикации на сайте видео с Youtube или Яндекс.карты используются API этих систем.
Создатели API предоставляют пользователям некую инструкцию - набор специальных команд (методов), которые можно применять для получения требуемого результата (в рамках разрешенного создателями). Такие команды (методы) содержатся в официальной документации разработчиков API.
Для чего нужно API
Раньше с сервера возвращалась сгенерированная HTML-страница, что было неэффективно. Современный подход предполагает, что с сервера возвращаются только данные, а клиент сам определяет, как их рендерить: браузер использует свои методы отрисовки, а мобильное приложение - свои. Таким образом, одно и то же API может применяться для разных платформ.
SPA (Single Page Application, "одностраничное приложение") - это сайт, который загружает один единственный HTML-файл. При переходе по ссылке SPA запрашивает у сервера нужные данные и точечно перерисовывает часть страницы, чтобы избежать ее полной перерисовки.
Что такое REST API
REST (Representational State Transfer, "передача состояния представления") - набор принципов, рекомендованных к применению при создании API. Если API соответствует таким принципам, его называют REST API.
REST — один из подходов к созданию API. Он сильно повлиял на взаимодействие серверной и клиентской частей приложения: стало проще переносить функциональность на новые платформы и расширять серверные мощности, не затрагивая клиента.
Также благодаря REST веб-приложения лучше кооперируются. За последние 10 лет число открытых API сильно увеличилось. Когда веб-приложению нужна какая-то функциональность, можно найти подходящее API. Например, чтобы отправлять смс пользователям, мы просто подключим проект к сервису Twilio ↗ (opens in a new tab), и нам не нужно разбираться в протоколах, на которых работают смс.
В чем польза от REST API
- унифицированный подход для обмена данными между клиентом и сервером позволяет создавать открытые API, переносить веб-приложение на другие платформы, быстрее разрабатывать и тестировать серверное ПО;
- точечная отрисовка изменений позволяет быстрее загрузить требуемую информацию. Уменьшает время ожидания;
Понимание принципов REST и создания API помогает экономить время — вы точно знаете, какими методами нужно обращаться к эндпоинтам сервера.
Принципы REST
1. Клиент-сервер
Сервер должен возвращать только данные, а не HTML-страницу целиком. Данные возвращаются в формате JSON.
2. Отсутствие состояния (Stateless)
Запрос к серверу должен содержать всю необходимую информацию для его обработки. Сервер не должен хранить информацию о состоянии пользователя.
3. Единый интерфейс (Uniform Interface)
Интерфейс обращения к серверу одинаковый для всех клиентов (сайта, мобильного приложения, умных часов, холодильника и пр.).
4. Многоуровневость
Подразумевает возможность создания многоступенчатой цепочки. Например, клиент (браузер) взаимодействует с API Яндекс.Такси, который в свою очередь является клиентом для API Яндекс.Навигатора и т.д.
5. Кешируемость
Данные, полученные в ответе от сервера, могут быть добавлены в кэш (память клиента). Тогда, если клиенту вновь понадобятся эти данные, он может их не запрашивать их у сервера, а взять из кэша.
6. Код по запросу (Code on demand)
Необязательный принцип. Функциональность клиента может быть расширена кодом, полученным с сервера. Например, можно получить JS-файл и исполнить его в браузере.
Ресурс - единица информации в REST
Атомарной единицей информации, с которой работает API, является "ресурс".
Рой Филдинг, автор концепции REST API:
Ключевая австракция информации в REST - ресурс. Ресурсом может быть документ, изображение, пост в блоге, пользователь социальной сети - все, к чему можно обратиться при HTTP-запросе. Ресурс - концептуальное отображение какого-то объекта или набора объектов, а не сами эти объекты.
Ресурсы нужно правильно именовать:
- существительными во множественном числе, реже в единственном. Например,
users
,cards
; - для иерархии испльзуют слеш:
/users
; - не надо использовать "висячий" слеш:
/users/
. Это плохо; - для многосложных названий лучше использовать дефис:
user-name
; - название пишется строчными символами. Без заглавных букв;
- в названиях не стоит дублировать HTTP-метод:
GET /get-cards
илиPOST /create-card
. Это плохо.
HTTP-методы
К ресурсу всегда можно обратиться по URL.
GET https://yourwebsite.com/cards/3lsko09483kksdo33ksosd
Применяют 5 основных и 2 дополнительных HTTP-методов запросов:
-
GET - получает ресурс;
-
POST - создает ресурс;
-
PUT - целиком заменяет существующий ресурс;
-
PATCH - частично заменяет существующий ресурс;
-
DELETE - удаляет ресурс;
-
HEAD - получает только заголовки ответа;
-
OPTIONS - узнает, какие HTTP-методы поддерживает сервер.
Обработка HTTP-методов на сервере
REST API может быть написан на любом языке программирования, который поддерживает обработку запросов. Может быть написан с использованием различных фреймворков. НО! Алгоритм обработки методов всегда одинаковый:
- выделяется endpoint-ссылка, за которой закреплена функция-обработчик;
- обращение к endpoint-ссылке;
- вызов функции-обработчика;
- функция-обработчик возвращает результат.
Статусы ответов сервера
Ответ от сервера всегда содержит статус. Статус облегчает разработчику жизнь. Всего 5 категорий:
- 1хх: Informational - информационный ответ для технических систем. Например:
100 Continue
. - 2хх: Success - запрос успешно обработан. Например:
200 OK
. - 3xx: Redirection - от клиента требуются дополнительные действия в порядке исполнения запроса.
- 4xx: Client Error - ошибка на стороне клиента: запрос сформирован неверно или нет нужных прав доступа.
- 5xx: Server Error - ошибка на стороне сервера.
Ссылка на документацию: REST API Tutorial: HTTP Status Codes ↗ (opens in a new tab)