Гид для начинающих по REST API
Создавая веб-сервис, нужно учитывать многое как со стороны бизнеса, так и стороны разработки. Клиент очерчивает требования — команда разработчиков их выполняет.
В свою очередь, в зависимости от требований и целей, уже на старте необходимо определиться с архитектурой проекта, так как от этого зависит то, как продукт будет функционировать после своего релиза. Сегодня мы поговорим об одной из самых популярных из них — REST.
Понять на самом базовом уровне, что такое REST и зачем он нужен, можно из статьи Райана Томайко “Как я объяснил жене, что такое REST”. Тем не менее, мы скорее подойдем к вопросу с технической стороны. Итак, приступим.
Что такое REST?
Representational state transfer (передача состояния управления) — это архитектурный стиль, применяемый при разработке веб-сервисов, и устанавливающий 6 правил для их построения.
Соблюдающие эти правила веб-сервисы называют RESTful сервисами. Помимо этого, REST также требует использование большинства возможностей протокола http.
Итак, что же это за правила?
- Uniform Interface — единый интерфейс
- Stateless — отсутствие состояний
- Cacheable — кэширование
- Client-Server — разграниченная архитектура клиент-сервер
- Layered System — многоуровневая система
- Code on Demand — код по запросу
Поговорим о каждом из них более подробно.
Единый интерфейс
REST архитектура подразумевает определение единого интерфейса взаимодействия всех клиентов с сервером.
При использовании REST, клиент работает с сервером получая ресурсы и управляя ими. Ресурсами при таком подходе могут выступать, например, таблицы в базе данных, хотя это и не всегда возможно, так как запросы могут иметь достаточно сложную логику взаимодействия с ресурсами.
Сам интерфейс должен разделять работу с разными ресурсами приложения по разным URL-адресам. Благодаря правильно выполненному разделению запросов, появляется возможность для лёгкого разделения одного веб-приложения на несколько, а это, в свою очередь, значительно облегчает портируемость и масштабируемость приложения.
К слову, помимо всего этого, API также становится более понятным для разработчиков даже при отсутствии детальной документации.
Также REST требует, чтобы названия ресурсов представляли собой существительные во множественном числе. Не следует перегружать систему множеством URL. Каждый ресурс в самом простом случае должен иметь только 2 URL адреса. Например:
- Формат для получения коллекции элементов: /buildings
- Формат для получения элемента по id: /buildings/{id}
Информация передаваемая между клиентами и сервером должна быть конвертирована в удобный для передачи формат. Примерами таких форматов может быть JSON или XML, хотя всё же наиболее популярным на текущий момент является как раз JSON.
Тем не менее, некоторые веб-сервисы умеют поддерживать работу с несколькими форматами одновременно.
В таком случае формат возвращаемых данных сервером и формат данных, который сервер должен обработать, управляется с помощью HTTP заголовков Accept и Content-type. В заголовках могут передаваться разные типы. Например: application/json или application/xml.
Отсутствие состояний
Каждый запрос в RESTful-сервисе должен уникально идентифицировать себя ресурсом или ресурсами, и оперировать их полными состояниями. REST веб-сервисы не должны хранить какие-либо данные в сессиях запросов или cookies.
Кэширование
Клиенты должны иметь возможность кешировать запросы. Таким образом, ответы явно или неявно определяют себя как кешируемые или нет, чтобы клиенты не могли использовать устаревшие или некорректные данные в ответ на дальнейшие запросы.
Правильно спроектированное кэширование позволяет уменьшить нагрузку на сервер и увеличить скорость работы клиентских приложений, что способствует большей масштабируемости и производительности.
Клиент-сервер
Интерфейс, который реализует взаимодействие клиентов и серверов, должен явно разделять обязаности клиентов и серверов и при этом должен быть реализован независимо от работы любого из них. Например:
- клиенты не должны иметь представления о хранимой на сервере информации, так как это зона ответственности сервера.
- Сервер не должен быть разработан в привязке к UI какого-либо клиента.
Layered system
Система может иметь промежуточные сервера и клиент не может точно знать с каким именно сервером он взаимодействует. Промежуточные сервера могут выполнять функцию балансировщиков нагрузки, кэша запросов и т.д.
Code on demand
Применение данного правила опционально. Его суть заключается в том, что сервер может передавать выполняемый на стороне клиента код Javascript, который позволяет временно расширить, или модифицировать функционал клиента.
Почему именно REST?
Несмотря на то, REST подходит для всех проектов, работающих по http, иногда его реализация может быть невозможна в силу недостаточных навыков команды. Тем не менее, если освоить REST должным образом, перед разработчиками открывается множество преимуществ:
- Улучшенная производительность. REST возвращает исключительно данные, указанные в запросе. Таким образом быстрее обрабатываются запросы и выдаются ответы.
- Масштабируемость. Приложение может работать на множестве серверов, что позволяет балансировать нагрузку между ними. Также сервис можно разделить на несколько “микросервисов”, которые смогут работать параллельно друг другу.
- Портируемость благодаря единому интерфейсу
- Прозрачность взаимодействия — за счёт своей стандартизации API остаётся понятным для пользователя.
- Легкость изменений. Благодаря меньшей связанности кода, снижается вероятность “поломать” запросы при внесении изменений в другие части приложения.
Методы http
Http содержит 4 метода: GET, POST, PUT, DELETE. Каждый метод должен использоваться для разных целей и идентифицировать функционал, который запрос реализует.
- GET. Используется для получения ресурсов (список ресурсов или один ресурс с указанием его id)
- POST. используется для создания ресурсов
- PUT. Ииспользуется для обновления ресурсов по id, который передается в URL
- DELETE. Используется для удаления ресурсов по id, который передается в URL
Ниже мы привели таблицу, содержащуя возможные запросы для потенциального ресурса people. В ней использованны все возможные http-методы и приведены ответы, которые эти запросы могут возвращать.
Http статус-коды
При использовании REST для веб-сервисов необходимо правильно подобрать http статусы для соответсвуюших ответов сервера. Сам по себе http имеет несколько десятков статус-кодов, но мы приведём 10 наиболее часто используемых:
- 200 OK — хорошо
- 201 Created — создано
- 204 No Content — нет содержимого
- 304 Not modified — не изменялось
- 400 Bad request — неверный запрос
- 401 Unauthorized — не авторизован
- 403 Forbidden — запрещён
- 404 Not found — не найдено
- 409 Conflict — конфликт
- 500 Internal Server error — внутренняя ошибка сервера
Http статус-коды имеют большое количество кодов для обработок ошибок, но этих кодов не достаточно для любого приложения.
В подобных случаях в тело ответа можно включить сообщение, раскрывающее суть ошибки более подробно (используя json, xml и т.д.). Клиенты, которые уже знают про полученный код, смогут корректно его обработать.
Дополнительно
- Запросы, возвращающие коллекции элементов, должны иметь возможность пагинации, сортировки, фильтрации
- Даты и время в запросах следует передавать в формате unix timestamp в миллисекундах.
- Версия приложения должна быть зашита в URL приложения как node. Например: api.app.com/v1/buildings
Если у вас остались какие-либо вопросы, вы можете связаться с нами для получения профессиональной технической консультации. Мы будем рады помочь вам с реализацией любых ваших идей!