Начнем с определения того, что означает REST в контексте X-Road. В отличие от протокола SOAP, который является протоколом с подробной спецификацией, REST - это архитектурный стиль, состоящий из лучших практик и рекомендаций. В случае с X-Road поддержка REST означает использование и создание REST API через X-Road поддерживающее любой тип HTTP контента.

Одним из руководящих принципов при разработке протокола сообщений REST для X-Road был принцип простоты использования как для поставщиков сервисов , так и для потребителей. Следовательно, использование и разработка REST сервисов для X-Road стала возможной без необходимости разработки дополнительного компонента адаптера. Информация, специфичная для X-Road, требуемая сервером безопасности (например, идентификатор клиента, идентификатор сервиса, идентификатор поставщика услуг, идентификатор сообщения и т.д), передается и обрабатывается, так что существующие службы и потребители услуг использующие REST могут быть подключены к X-Road с минимальными изменениями или без изменений вообще. Это было достигнуто путем выноса специфической информации X-Road, требуемой сервером безопасности, в заголовки HTTP и параметры URL.

Поддержка REST в X-Road не ограничивается только сообщениями JSON и XML, поскольку сервер безопасности не ставит каких-либо ограничений для типа содержимого полезной нагрузки, передаваемой между потребителем и поставщиком сервисов. Тип содержимого полезной нагрузки определяется с в HTTP заголовках «Content-Type», который передается между потребителем и поставщиком сервиса, так же как и сама полезная нагрузка. Полезная нагрузка передается как есть, сервер безопасности не изменяет, не преобразует и не проверяет обработанную полезную нагрузку. То же самое относится почти ко всем заголовкам и параметрам URL определенным потребителем и поставщиком HTTP сервиса - то есть они передаются как есть Список фильтруемых HTTP заголовков включен в спецификацию протокола REST X-Road Message protocol

Когда дело доходит до подписания и проверки подписи сообщений REST, полезная нагрузка сообщения, параметры URL и заголовки HTTP все включаются в цифровую подпись и журналы, генерируемые и проверяемые сервером безопасности. Следовательно, X-Road гарантирует подлинность REST запросов и ответов так же, как это делается для SOAP-сообщений.

Использовать REST-сервисы через X-Road просто - вызываемый сервис определяется в URL-адресе запроса, а клиентская подсистема X-Road, отправляющая запрос, определяется в HTTP-заголовке. Другая специфичная для X-Road информация (например, идентификатор пользователя, основание , идентификатор клиентской подсистемы, идентификатор сообщения) является необязательной и передается в HTTP заголовках . Другие HTTP заголовки, параметры пути и параметры URL передаются как есть, что означает, что с точки зрения клиента службы единственное отличие по сравнению с прямым вызовом сервиса единственный обязательный HTTP заголовок , определяющий клиентскую подсистему X-Road.

Предоставление сервисов REST через X-Road так же просто (если не проще), как и использование сервисов. Существующие службы REST могут публиковаться в X-Road как есть - достаточно добавить публикуемый базовый URL-адрес REST API и определить права доступа в интерфейсе Security Server. В отличие от сервисов SOAP, Security Server не требует, чтобы в ответах, возвращаемых сервисами REST, была указана специфическая информация X-Road. Определенная информация, относящаяся к X-Road, по-прежнему включена в ответное сообщение, возвращаемое в информационную систему клиента, но сервер безопасности позаботится о добавлении необходимой информации в HTTP заголовки ответного сообщения.

В настоящее время службы должны быть описаны с использованием WSDL. Невозможно опубликовать сервис SOAP в X-Road, не предоставив WSDL описание сервиса. В первой версии X-Road, включающей поддержку REST (v6.21.0), описания REST сервисов не требуются. При добавлении новой службы REST достаточно предоставить базовый URL-адрес REST API для публикации. В более поздних версиях будет добавлена поддержка описания REST сервисов с использованием спецификации OpenAPI 3. Об автоматических преобразованиях SOAP-REST Сервисы должны использовать их собственные реализации - SOAP или REST. Если поставщик сервиса хочет предоставить SOAP и REST версии одного и того же сервиса, он должен реализовать обе версии. Другими словами, сервер безопасности не будет обеспечивать автоматическое преобразование SOAP в REST и обратно. В случае, если требуется автоматическое преобразование SOAP в REST, можно использовать расширение REST Adapter Service. REST Adapter Service - это готовый компонент, который предоставляет X-Road-совместимый конвертер REST-SOAP. Сервис поддерживает ограниченный набор вариантов использования.

Реализация REST поддерживает взаимную аутентификацию TLS между Сервером безопасности и потребителем/поставщиком услуг REST. Поддержка аутентификации на основе JWT (JSON Web Token) между Сервером безопасности и информационной системой может быть предоставлена в более поздних версиях. Однако уже возможно использовать аутентификацию на основе JWT между клиентом сервиса и поставщиком сервиса. Как описано выше, сервер безопасности передает все HTTP-заголовки между потребителем и поставщиком услуг как есть, поэтому нет ограничений для реализации аутентификации на основе JWT на уровне приложения.

Автор С.Бутенко