Что важно знать для реализации REST API в 1С

Архитектура REST и ее значимость

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

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

Архитектура REST не ограничивает выбор используемого протокола, однако она тесно связана с протоколом HTTP. Многие аспекты архитектуры проще всего реализовать именно с этим протоколом. HTTP предназначен для обмена сообщениями, позволяя передавать как двоичные данные (видео, изображения), так и текстовые данные. Наиболее популярными форматами для передачи текстовых данных являются XML и JSON. Их популярность объясняется тем, что их легко контролировать визуально: взглянув на передаваемый текст, сразу можно понять структуру и содержимое данных, что значительно упрощает разработку.

Архитектура REST не предлагает конкретных примеров или паттернов для решения часто возникающих проблем проектирования. Это скорее стратегия развития, которая помогает создать масштабируемую, гибкую и эффективную систему.

Ограничения архитектуры REST

Архитектура описана через шесть основных ограничений.

Ограничение 1: Модель клиент-сервер

Первое ограничение – это модель клиент-сервер. Эта модель хорошо знакома разработчикам 1С: у нас есть сервер, который обрабатывает, собирает и хранит данные, и клиенты, основная задача которых – формирование пользовательского интерфейса.

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

Ограничение 2: Отсутствие состояний

Второе ограничение – отсутствие состояний. В отличие от 1С, где при подключении клиента создается сеанс с параметрами и контекстом выполнения, в архитектуре REST такого контекста нет. Архитектура запрещает собирать историю обращений клиента для формирования контекста.

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

Ограничение 3: Кэширование

Третьим ограничением архитектуры является кэширование. Разработчикам платформы хорошо знаком этот механизм. У нас есть общие модули с повторным использованием, которые позволяют вместо обращения к базе данных использовать кэш.

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

Ограничение 4: Единообразие интерфейса

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

Ресурс – это любая информация, которой можно присвоить имя: документ, изображение, курсы валют. Идентификатор ресурса не должен изменяться в зависимости от его состояния. Например, курсы валют меняются со временем, но их идентификатор должен оставаться прежним. Для этих целей в Интернете используются ссылки.

В данном примере обращение к коллекции Users пользователя и к конкретному элементу с идентификатором 12345.

Ссылку можно разбить на базовую и относительную части. Базовая – это протокол и адрес сервера, в том числе имя базы. Относительная – это часть с именем коллекции ресурсов и идентификатором самого ресурса.

Второе ограничение – управление через представление. Это означает, что имея идентификатор ресурса, нам достаточно его для выполнения действий с данными. То есть, имея идентификатор, можно выполнять такие операции, как создание, чтение, удаление или изменение данных.

Третье ограничение – «самоописываемые» сообщения. Это ограничение логично вытекает из отсутствия состояний, так как в архитектуре REST нет контекста выполнения запроса. Поэтому в самом запросе должно быть достаточно информации, чтобы обработать его. Больше эти данные неоткуда взять.

Последнее ограничение архитектуры – принцип HATEOAS (гипермедиа как средство изменения состояния приложения). Это означает, что помимо данных о состоянии ресурсов, в сообщении может быть информация о связанных ресурсах и доступных действиях с этими ресурсами. Это поведение аналогично управляемому интерфейсу в платформе 1С. Например, при открытии элемента справочника валюты в панели навигации можно увидеть ссылку на регистр сведений. Либо в заказе клиента, в зависимости от его состояния (подтвержден он или нет), может появиться или не появляться команда для создания платежа на основании этого заказа.

Плюсы и минусы ограничений интерфейса

Выполнив эти ограничения, мы получаем:

• Масштабируемость. Легко можно добавить новые ресурсы, изменяя или добавляя сегменты в адрес ресурса.

• Производительность. Имея идентификатор ресурса, можно кэшировать данные, повышая производительность системы.

• Гибкость. Имея адрес и используя стандартные методы протокола HTTP, легко можно выполнять действия с ресурсом.

• Удобство поддержки. Когда все ресурсы имеют одинаковый интерфейс и описание, их проще поддерживать и легче писать документацию.

Одним из минусов подхода REST является сложность реализации специализированных операций. Примером может служить комплексная операция, при которой необходимо подтвердить заказ и одновременно сформировать оплату по нему. Согласно принципам архитектуры, это потребует работы с двумя разными ресурсами: заказом, который нужно изменить, и оплатой, для которой необходимо создать новый ресурс. Эти операции независимы, и, следовательно, выполнить их в рамках одной транзакции невозможно.

Ограничение 5: Слои

Пятым ограничением архитектуры REST являются слои. На изображении представлена архитектура в виде слоев. В этой архитектуре каждый слой отвечает за свой функционал: один слой может заниматься кэшированием, другой – безопасностью, третий – обработкой запросов. Эти слои могут быть расположены не только на разных серверах, но и внутри одного сервера. Например, один сервер может включать слои для обработки запросов, бизнес-логики и работы с базой данных. Этот подход позволяет добавлять новые слои, обеспечивая гибкость: каждый слой может развиваться независимо, что повышает надежность всей системы.

Ограничение 6: Код по требованию

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

Протокол HTTP

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

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

Стандартные HTTP-методы: GET, POST, PUT, DELETE

Как уже упоминалось, стандартные методы HTTP позволяют выполнять простые операции с данными.

Метод GET используется для получения текущего состояния ресурса. Например, применяя его к коллекции users пользователя, можно получить список всех пользователей. Если же применить его к конкретному элементу, то, указывая идентификатор, можно получить данные о конкретном пользователе.

Метод POST используется для добавления новых ресурсов или создания новых элементов.

Методы PUT и DELETE служат для изменения и удаления существующих данных соответственно.

Метод PATCH был добавлен в отдельном стандарте для уменьшения объема передаваемых данных. В отличие от метода PUT, который заменяет весь объект и требует наличия всех реквизитов (отсутствующие реквизиты должны быть заполнены значениями по умолчанию), PATCH изменяет только те реквизиты, которые присутствуют в сообщении, оставляя остальные данные без изменений.

Категории HTTP-заголовков

Заголовки HTTP можно разделить на четыре категории.

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

Также важным элементом кэширования является заголовок Date, однако для работы с платформой его добавление необязательно, так как платформа добавляет его автоматически.

Для каждого протокола очень важно описывать сообщение так, чтобы ни одно приложение не приняло его за что-то другое. Именно для этого во всех сообщениях, которые содержат тело запроса, обязательно должны быть заголовки сущности.

Заголовок Content-Type указывает на тип содержимого и его формат. Например, это может быть изображение (PNG, JPEG), видео или текст (XML, JSON).

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

Также существует заголовок Content-Encoding, который используется для обозначения алгоритма сжатия, примененного к сообщению. Для согласования алгоритмов сжатия между клиентом и сервером используется общий заголовок Accept-Encoding, который позволяет клиенту правильно распаковать сообщение.

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

В заголовках запроса можно выделить Accept-Type и Accept-Language. Подобно заголовкам Content-Type и Content-Language, заголовок Accept-Type указывает формат, в котором клиент хочет получить данные. При этом можно указать несколько форматов с приоритетами: какой формат предпочтительнее. Заголовок Accept-Language указывает, на каком языке клиент предпочитает получить ответ.

В заголовках ответа важны те, которые отвечают за управление кэшированием.

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

Заголовок Etag используется для идентификации текущего состояния ресурса. Это аналог версии данных в платформе.

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

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

Коды HTTP-ответов

Коды HTTP-ответов делятся на пять категорий, состоящих из трех цифр:

• Коды, которые начинаются с 1, являются информационными и используются, когда сервер не может сразу сообщить результат обработки запроса (например, при длительных операциях).

• Успешная обработка запроса возвращает коды, которые начинаются с 2.

• Коды, которые начинаются с 3, используются, когда ресурс изменил свое местоположение, и для получения данных нужно выполнить дополнительные запросы.

• Коды ошибок, которые начинаются с 4 и 5, сообщают о проблемах в запросе или на сервере.

Существует мнение, что если мы достигли обработки бизнес-логики (например, обработчика метода в платформе), то можно возвращать код 200. Однако я с таким подходом не согласен. Правильный выбор кодов, особенно в случае ошибок, позволяет дать более полное представление о том, что именно произошло и как можно повлиять на ситуацию. Использовать только коды ошибок также не всегда корректно. Например, если при закрытии месяца возникает ошибка, возврат кода ошибки с общим сообщением «Произошла ошибка при закрытии месяца» не даст разработчику или пользователю информации о том, что нужно делать дальше. Вместо этого следует использовать тело ответа, чтобы предоставить более подробную информацию об ошибке и возможных путях ее решения.

XML и JSON

В теле запроса и теле ответа мы можем передавать данные. Обычно это делается в текстовом формате, и наиболее популярными форматами являются XML и JSON.

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

В отличие от XML, JSON изначально поддерживает объекты и массивы: объекты выделены фигурной скобкой, а массивы квадратной.

Если мы встречаем значение в кавычках, то получаем строку. Если в значении получаем идентификатор true или false, то мы имеем дело с булевым типом. Идентификатор null обозначает отсутствие значений. Во всех остальных случаях мы встречаем число.

Благодаря этой простоте структура JSON обычно короче: например, если мы уберем все незначащие символы и получим одну длинную строку, то XML может занимать около 500 символов, а эквивалентное сообщение в JSON – около 200 символов. Это сокращение объема данных способствует более быстрой передаче информации и повышению отзывчивости интерфейса.

Заключение

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

*************

Статья написана по итогам доклада (видео), прочитанного на конференции INFOSTART TECH EVENT.