FHIR в стиле REST.

Перевод оригинальной статьи от 15 октября 2013 года с дополнениями.

REST - это концепция

Сегодня мы поговорим о концепции REST и ее реализации в контексте стандарта FHIR. Аббревиатура REST расшифровывается как «передача состояния представления» («REpresentational State Transfer») и подразумевает под собой архитектурный подход (или стиль) в построении распределенного программного обеспечения. Суть REST заключается в манипулировании т.н. ресурсами (resource), т.е. в их создании, изменении и обмене по правилам протокола http. О веб-сервисах, системах и приложениях, реализующих данные принципы, говорят как о RESTful-сервисах, т.е. соответствующих ограничениям спецификации REST. Мы лишь поверхностно коснемся реализации REST-принципов в стандарте FHIR, поэтому, за более полной информацией лучше обратиться к спецификации REST.

Стандарт FHIR хорошо "ложится" на любую из парадигм обмена данными, которые он называет "interoperability paradigms". К возможным "парадигмам" относятся (1) обмен документами, (2) обмен сообщениями, (3) REST-обмен и (4) развертывание веб-сервисов, однако, наиболее просто и удобно стандарт FHIR реализуется именно "поверх" REST. Несмотря на большой энтузиазм вокруг REST и большую популярность данного архитектурного подхода, он лишь является набором простых рекомендаций, изложенных в спецификации. По факту, сегодня почти весь веб работает в соответствии с принципами, изложенными в спецификации REST.

REST и HTTP

REST-взаимодействия основываются на правилах, определенных протоколом HTTP. Любое взаимодействие происходит по схеме "запрос-ответ": в запросе указываются запрашиваемые данные или описывается транзакция, подлежащая выполнению на сервере, в ответе возвращаются данные или статус выполнения транзакции. Существует прямое соответствие между CRUD-операциями, определенными протоколом HTTP, и их реализацией в RESTful-интерфейсах. Также подразумевается, что взаимодействие в RESTful-интерфейсах происходит в строгом соответствии с "семантикой" определенных протоколом методов. Т.е. например, метод get должен использоваться только для получения данных, но никогда для вызова выполнения транзакций (создания новых ресурсов или внесения изменения в существующие), хотя технически это и возможно, ввиду ошибок, часто допускаемых при проектировании и разработке веб-интерфейсов.

Идентификация ресурсов

Согласно одному из базовых требований REST-архитектуры, любой ресурс может быть уникально идентифицирован, т.е. обладает опознавательными характеристиками (identity). "RESTful FHIR" предписывает использование универсальных идентификаторов ресурсов (URI),
которые раскрывают физическое размещение ресурса на сервере, а также уникальный идентификационный номер ресурса в пределах сервера хранения. Уникальность URI обеспечивается сервером.

Структура URI во многом похожа на путь к файлу в файловой системе. Данную схему идентификации также можно уподобить дереву, в котором некоторые ветви могут содержать подветви, причем каждая из подветвей имеет свою "тематическую направленность". Особенностью URI является "самодокументируемость", т.е. пользователь должен самостоятельно и без дополнительных комментариев понять, что идентифицирует данный URI (тип и id ресурса, его размещение). Как и в случае с файловой системой, существует "корневой раздел", т.е. физический адрес сервера, который содержит в себе "подкаталоги", отведенные для размещения тематических ресурсов. Иерархия размещения ресурсов на сервере может быть описана вручную, так и автоматически на базе заданных правил (т.е. машина может самостоятельно генерировать новые подветви URI). Важной особенностью URI является неизменяемость, даже при изменении самого ресурса.

По отношению к URI рекомендуют следующее: (1) не указывайте формат хранения ресурсов (json, xml) в URI, чтобы не "замыкать" ресурсы на один формат, (2) используйте только строчные буквы. (3) Любые пробелы в URI ресурса должны быть заменены на тире или нижние подчеркивания. (4) Насколько возможно, лучше не пользоваться строчными запросами (query strings).

Взаимодействия не зависят от контекста (statelessness)

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

Действенные методы FHIR

Для манипулирования ресурсами доступен ограниченный набор операций (методов), заимствованных из http. Разберем наиболее интересные:

GET. Используется для получения ресурса, идентификация которого происходит по URI. URI ресурса составляется из физического адреса сервера и идентификатора (ID) ресурса. Метод GET может использоваться как для получения одного ресурса, так и для выполнения поисковых запросов, результатом которых могут быть группы ресурсов.

Метод POST позволяет создавать новые ресурсы на указанном сервере. Сервер, на котором будет размещен создаваемый ресурс, самостоятельно присвоит ему уникальный идентификатор. Физический адрес сервера и уникальный (в масштабе данного сервера) идентификатор будут использоваться в качестве URI данного ресурса.

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

Для выполнения метода DELETE клиентская сторона также должна знать URI удаляемого ресурса. Рекомендуется, хотя, это и не является строгим требованием, сохранять ресурс на сервере при выполнении операции DELETE (это вопрос практической реализации стандарта). После удаления ресурс может быть доступен при выполнении операции vread (т.е. при запросе конкретной версии ресурса), однако, метод GET уже не должен возвращать данный ресурс. (Будет возвращен код состояния, сообщающий об удалении ресурса.)

Метод OPTIONS - особый метод в стандарте FHIR, который обращается к корневому каталогу FHIR-сервера и возвращает conformance-ресурс. Данный ресурс содержит информацию о поддерживаемой функциональности сервера.

Ответ на rest-запрос формируется сервером в соответствии с указанным в запросе методом и внутренней логикой сервера. Ответ составляется из нескольких частей. Тело ответа (body) содержит запрашиваемые клиентской стороной данные. Чаще всего данные возвращаются клиенту в ответ на GET-запрос. Сервер всегда возвращает т.н. код состояния (status code), который сообщает клиенту о результате обработки запроса. Код состояния - это число (например, "404"), имеющее определенный смысл в протоколе HTTP. Стандарт FHIR
также предусматривает использование ресурса "operationOutcome", с помощью которого сервер может сообщать клиентской стороне о возможных причинах неудач при их взаимодействии. Как в запрос, так и в ответ могут включаться заголовки (headers), в которых
содержится дополнительная информация для корректной обработки транзакций.

В заголовке может указываться, например, следующая информация:
• В поле Content-type указывается формат cодержимого (XML или JSON).
• В поле Accept клиент сообщает серверу предпочтительный формат (XML или JSON) ответа на GET-запрос. (Сервер, тем не менее, не обязан удовлетворить данное требование клиента.)
• В поле Location сервер сообщит клиенту URI вновь создаваемого ресурса.

Теперь давайте "потренируемся" и попробуем получить содержимое FHIR-ресурса, размещенного на одном из тестовых серверов.
Выполним в веб-браузере следующую команду (на самом деле это и есть URI):

http://fhir.healthintersections.com.au/open/Patient/100

В итоге будет выполнен GET-запрос к вышеуказанному серверу и браузер отобразит содержимое ресурса в XML-формате.

Разберем URI "по кусочкам":
• "http://" - для обмена данными будет использован протокол http
• hl7connect.healthintersections.com.au/svc/fhir/ – конечная точка, куда следует отправлять fhir-запросы.
• "Patient/" - выполняемая операция будет совершаться над ресурсом типа "patient".
• "100" - указан идентификатор пациента.

Однако, отметим следующее: Единственный тип запросов, которые могут выполняться напрямую из браузера вышеописанным методом - это get-запросы.