Центр электронного взаимодействия "Тундук"

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Реализация поддержки REST ======

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

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

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

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

====== Использование REST сервисов ======
 
Использовать REST-сервисы через X-Road просто - вызываемый сервис определяется в [[https://ru.wikipedia.org/wiki/URL|URL]]-адресе запроса, а клиентская подсистема X-Road, отправляющая запрос, определяется в HTTP-заголовке. Другая специфичная для X-Road информация (например, идентификатор пользователя, основание , идентификатор клиентской подсистемы, идентификатор сообщения) является необязательной и передается в HTTP заголовках . Другие HTTP заголовки, параметры пути и параметры URL передаются как есть, что означает, что с точки зрения клиента службы единственное отличие по сравнению с прямым вызовом сервиса единственный обязательный HTTP заголовок , определяющий клиентскую подсистему X-Road.

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

====== Описание сервисов для REST ======

В настоящее время службы  должны быть описаны с использованием [[https://ru.wikipedia.org/wiki/WSDL|WSDL]]. Невозможно опубликовать сервис SOAP в X-Road, не предоставив WSDL описание сервиса.
В первой версии X-Road, включающей поддержку REST (v6.21.0), описания REST сервисов не требуются. При добавлении новой службы REST достаточно предоставить базовый URL-адрес REST API для публикации. В более поздних версиях будет добавлена поддержка описания REST сервисов с использованием спецификации [[https://ru.wikipedia.org/wiki/OpenAPI_(%D1%81%D0%BF%D0%B5%D1%86%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D1%8F)|OpenAPI 3]].
Об автоматических преобразованиях SOAP-REST
Сервисы должны использовать их собственные реализации - SOAP или REST. Если поставщик сервиса хочет предоставить SOAP и REST версии одного и того же сервиса, он должен реализовать обе версии. Другими словами, сервер безопасности не будет обеспечивать автоматическое преобразование SOAP в REST и обратно. В случае, если требуется автоматическое преобразование SOAP в REST, можно использовать расширение [[https://github.com/nordic-institute/REST-adapter-service|REST Adapter Service]]. REST Adapter Service - это готовый компонент, который предоставляет X-Road-совместимый конвертер REST-SOAP. Сервис поддерживает ограниченный набор вариантов использования.
====== Аутентификация между компьютерами ======

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


----

Автор С.Бутенко
Центр электронного взаимодействия "Тундук"

Инструменты пользователя

Инструменты сайта

Инструменты страницы
