База знаний
API. REST API

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)