REST API, или как создать удобный веб-сервис

Термин REST появился в 2000 году благодаря Рою Филдингу, одному из создателей протокола HTTP. Сегодня REST API используется повсеместно для обмена данными между клиентом и сервером.

Что такое REST API?

REST API - это сборное из двух сокращений понятие:

Что такое API? Это Application Programming Interface; используется для работы одних программ с другими.

Что такое REST? Это Representational State Transfer (передача состояния представления), или способ построения API архитектуры с помощью HTTP.

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

HTTP является основой REST сервисов, поскольку данный протокол реализован во всевозможных языках программирования, всех ОС и является универсальным. С помощью HTTP появляется возможность предоставить юзеру определенный ресурс по его URI.

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

Представления ресурсов состоят из данных; метаданных, описывающих данные; и гипермедийных ссылок для перехода к следующему желаемому состоянию.

URI - универсальный идентификатор ресурса. Например, http://allcafes.com/cities, где первая часть (http://allcafes.com) является адресом сайта или сервера, а вторая (/cities) - адресом ресурса на удаленном сервере.

Основополагающие принципы Rest API

Не существует определенного стандарта REST API, однако в работе, а именно в написании кода интерфейса, слеудет выделять следующие Restful API принципы:

• Клиент-сервер (Client-Server). Это концепция, согласно которой клиент и сервер должны быть отделены друг от друга. То есть возможно вносить изменения в приложение, не влияя на структуру данных на сервере, или редактировать базу данных на сервере, не затрагивая при этом клиентское приложение.
• Нестационарность (Stateless). Запросы могут выполняться независимо друг от друга, и каждый запрос содержит данные, необходимые для успешного предоставления данных пользователю. Сервер не должен хранить данные о проведенных операциях клиента.
• Кэширование (Cache). Поскольку работа может быть перегружена при обработке большого количества входящих и исходящих запросов, REST API должен иметь возможность кэшировать данные (тогда пользователь сможет обращаться к этому буферу данных при повторных запросах).
• Единый интерфейс (Uniform Interface). Наличие единого интерфейса позволяет установить более стабильную работу (например, благодаря использованию HTTP).
• Многоуровневая система (Layered System). REST API имеют различные уровни своей архитектуры, что позволяет располагать разные серверы на разных уровнях. При таком подходе можно управлять, например, скоростью ответа более важных серверов. Подобная система позволяет существенно увеличить уровень безопасности.
• Код по запросу (Code on Demand). Предоставление кода по требованию клиента позволяет передавать его через API для использования в приложении.

Преимущества

Преимущества REST API и популярность ее использования заложены в принципах и особенностях работы.

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

Гибкость REST API обеспечивается из-за использования HTTP и возможности работы с любыми языками программирования, в любых операционных системах. Созданная архитектура Rest API дает возможность обрабатывать любые типы запросов и форматы данных.

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

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

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

Как работает REST API?

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

Поэтапно работу RESTful API можно описать так:

1. Клиент отправляет запрос на сервер. Согласно документации API, клиент форматирует (изменяет) запрос таким образом, чтобы сервер получил сведения, необходимые для обработки.
2. Сервер аутентифицирует клиента и подтверждает, что клиент имеет право сделать этот запрос. Если аутентификация прошла неуспешно, возвращается ошибка 403.
3. Сервер получает запрос в нужном виде, обрабатывает его.
4. Затем сервер возвращает ответ на запрос клиенту. В ответе содержится информация об успешности выполнения команды и запрашиваемый ресурс.

Для работы с ресурсами через REST API используются команды HTTP:

• GET для получения информации о данных: по запросу GET /cities вы получите список всех городов, для которых собраны адреса кафе.
• DELETE для удаления данных: по запросу DELETE /istanbul будут удалены кафе в Стамбуле, которые уже закрылись.
• POST для добавления новых или замены старых данных: запрос POST /ankara добавит новый адрес кафе в Анкаре.
• PUT для редактирования данных: по запросу PUT /cities можно внести правки в список городов, представленных в приложении.

После выполнения или невыполнения любой команды, пользователь получает ответ, начинающийся с определенной цифры. Например, код, начинающийся с 2, означает успешное выполнение команды, 500 - ошибка сервера, коды с цифрой 4 в начале означают неуспешное выполнение команды и указывают на причину ошибки (401 Unauthorized - неуспешная авторизация, 404 Not found - запрашивается несуществующий ресурс и др.)

Лучшие практики разработки REST API

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

• Используйте kebab-case для URL

Плохо: /cafeKahve или /cafe_Kahve

Хорошо: /cafe-Kahve

• Используйте множественное число для коллекций

Плохо: DELETE /city или DELET /City

Хорошо: DELETE /cities

• URL должен начинаться с коллекции и заканчиваться URI

Плохо: GET /cafe/:cafeId/group/:groupId/price

Хорошо: GET /cafes/:cafeId/ или GET /group/:groupId

• Используйте глаголы в операциях, а не в URL ресурсов

Плохо: POST /updatecafe/{cafeId} или GET /getcafes

Хорошо: PUT /cafes/{cafeId}

• Используйте инструменты для разработки REST API

Например API Blueprint и Swagger.

• Обеспечьте безопасность

Обязательно используйте HTTPS для всех ресурсов и сервисов.

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

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

• Используйте фильтрацию, сортировку

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

Еще больше практик работы с REST API можно найти здесь.