Content Negotiation FHIR
Last updated
Last updated
Content Negotiation là một khía cạnh quan trọng của FHIR (Fast Healthcare Interoperability Resources), cho phép clients và servers thỏa thuận về định dạng nội dung tốt nhất để trao đổi. Trong bài viết này, chúng ta sẽ khám phá chi tiết về content negotiation trong FHIR, bao gồm các định dạng, MIME types, và cách kiểm soát phiên bản thông qua content negotiation.
FHIR hỗ trợ cả hai định dạng XML và JSON làm định dạng chính cho tài nguyên. Mỗi định dạng có những ưu điểm và nhược điểm riêng, và lựa chọn giữa chúng thường phụ thuộc vào đặc điểm kỹ thuật và hệ sinh thái hiện có của ứng dụng.
JSON (JavaScript Object Notation) đã trở thành định dạng phổ biến nhất cho FHIR do tính nhẹ nhàng và phổ biến trong các ứng dụng web hiện đại.
Ví dụ tài nguyên Patient trong JSON:
Ưu điểm của JSON:
Nhỏ gọn hơn XML (ít ký tự truyền tải hơn)
Phân tích cú pháp dễ dàng trong JavaScript
Định dạng phổ biến trong các API web hiện đại
Dễ đọc và viết cho con người
Được hỗ trợ tốt trong nhiều ngôn ngữ lập trình
Nhược điểm của JSON:
Không hỗ trợ comments
Ít hỗ trợ schema validation hơn XML
Không có namespaces tích hợp
XML là định dạng truyền thống được sử dụng trong các hệ thống y tế và tiếp tục được FHIR hỗ trợ đầy đủ.
Ví dụ tài nguyên Patient trong XML:
Ưu điểm của XML:
Hỗ trợ namespaces, giúp phân biệt giữa các phần mở rộng
Hỗ trợ schema validation tốt (XSD)
Hỗ trợ các công cụ xử lý như XSLT và XPath
Có thể chứa comments
Được sử dụng rộng rãi trong các hệ thống y tế truyền thống
Nhược điểm của XML:
Dài dòng hơn JSON (nhiều bytes hơn để truyền tải cùng một thông tin)
Khó đọc hơn đối với người không quen thuộc
Phân tích cú pháp trong JavaScript phức tạp hơn
Yêu cầu nhiều bộ nhớ hơn khi phân tích
Kích thước
Nhỏ gọn
Lớn hơn
Khả năng đọc
Tốt
Trung bình
Khả năng phân tích
Nhanh
Chậm hơn
Hỗ trợ comments
Không
Có
Schema validation
Hạn chế
Mạnh mẽ
Namespaces
Không
Có
Phổ biến trong web APIs
Rất cao
Trung bình
Hỗ trợ cho legacy systems
Hạn chế
Tốt
FHIR được thiết kế để đảm bảo ánh xạ 1:1 giữa cả hai định dạng, có nghĩa là bất kỳ tài nguyên FHIR nào cũng có thể được chuyển đổi từ JSON sang XML hoặc ngược lại mà không mất thông tin. Tuy nhiên, có một số khác biệt tinh tế cần lưu ý:
Trong XML, tất cả các giá trị primitive đều được gói trong thuộc tính value
, trong khi JSON sử dụng trực tiếp giá trị
XML cần các namespace để phân biệt giữa các phần mở rộng, trong khi JSON không có khái niệm này
Content negotiation trong FHIR chủ yếu dựa vào các MIME types và HTTP headers để quyết định định dạng nội dung.
application/fhir+json
FHIR Resource trong JSON
Biểu diễn tiêu chuẩn cho tài nguyên FHIR trong JSON
application/fhir+xml
FHIR Resource trong XML
Biểu diễn tiêu chuẩn cho tài nguyên FHIR trong XML
application/json
JSON không đặc biệt hóa FHIR
Tương thích với các hệ thống JSON cũ hơn
application/xml
XML không đặc biệt hóa FHIR
Tương thích với các hệ thống XML cũ hơn
text/html
Biểu diễn HTML
Giúp hiển thị dữ liệu FHIR trong trình duyệt
application/json-patch+json
JSON Patch
Sử dụng cho các hoạt động PATCH
application/fhir+turtle
RDF Turtle
Biểu diễn ngữ nghĩa (RDF) của tài nguyên FHIR
application/fhir+n-triples
RDF N-Triples
Biểu diễn ngữ nghĩa (RDF) của tài nguyên FHIR
Header Accept
cho phép client chỉ định định dạng mong muốn trong response. Server sẽ cố gắng cung cấp dữ liệu ở định dạng được yêu cầu, hoặc trả về lỗi 406 Not Acceptable
nếu không thể.
Ví dụ các Accept headers:
Yêu cầu FHIR JSON.
Yêu cầu FHIR XML.
Ưu tiên JSON, nhưng XML cũng chấp nhận được với chất lượng thấp hơn.
Yêu cầu FHIR JSON với phiên bản FHIR 4.0.
Khi gửi dữ liệu đến server (POST, PUT), client phải chỉ định loại nội dung đang gửi bằng header Content-Type
:
Nếu không chỉ định Content-Type
, server có thể từ chối request với lỗi 415 Unsupported Media Type
.
Request:
Response:
Ngoài việc sử dụng header Accept
, FHIR cũng hỗ trợ cơ chế thay thế thông qua tham số URL _format
để chỉ định định dạng mong muốn. Điều này hữu ích trong các tình huống khi không thể kiểm soát HTTP headers, như khi sử dụng trình duyệt web đơn giản.
json
application/fhir+json
xml
application/fhir+xml
application/json
application/json
application/xml
application/xml
text/html
text/html
Yêu cầu tài nguyên ở định dạng JSON.
Yêu cầu tài nguyên ở định dạng XML.
Sử dụng MIME type đầy đủ (URL encoded).
Khi cả hai đều được sử dụng, FHIR đặc tả khuyến nghị ưu tiên tham số _format
hơn header Accept
. Tuy nhiên, một số triển khai có thể khác nhau, vì vậy hãy kiểm tra tài liệu của server cụ thể.
FHIR sử dụng content negotiation không chỉ để chọn định dạng dữ liệu mà còn để chọn phiên bản của đặc tả FHIR. Điều này cho phép client yêu cầu một phiên bản cụ thể của tài nguyên FHIR.
FHIR có các phiên bản chính thức, như:
DSTU1 (0.0.82)
DSTU2 (1.0.2)
STU3 (3.0.2)
R4 (4.0.1)
R4B (4.3.0)
R5 (5.0.0)
Mỗi phiên bản có thể có cấu trúc tài nguyên và quy tắc khác nhau.
Client có thể chỉ định phiên bản FHIR mong muốn bằng cách sử dụng tham số fhirVersion
trong header Accept
:
Phiên bản có thể được chỉ định thông qua tham số _format
kết hợp với tham số _fhirVersion
:
Server FHIR phải khai báo các phiên bản được hỗ trợ trong Capabilities Statement (trước đây gọi là Conformance Statement). Client có thể truy vấn điểm cuối /metadata
để xác định các phiên bản được hỗ trợ:
Ví dụ response:
Ngoài phiên bản của đặc tả FHIR, mỗi tài nguyên FHIR cũng có phiên bản riêng, được theo dõi thông qua phần tử meta.versionId
. Để truy cập phiên bản cụ thể của tài nguyên, sử dụng cú pháp:
Điều này khác với versioning thông qua content negotiation vì nó đề cập đến phiên bản cụ thể của tài nguyên, không phải phiên bản của đặc tả FHIR.
Một hệ thống cũ có thể không hỗ trợ MIME types đặc biệt của FHIR:
Request:
Response:
Request:
Response:
Request:
Response:
Request:
Server không hỗ trợ Turtle nhưng cung cấp JSON như là fallback:
Response:
Luôn chỉ định Accept header: Để đảm bảo nhận được định dạng mong muốn
Cung cấp fallback formats: Sử dụng q
parameter để chỉ định ưu tiên
Xử lý 406 Not Acceptable: Chuẩn bị xử lý khi server không thể đáp ứng yêu cầu định dạng
Kiểm tra phiên bản FHIR: Chỉ định fhirVersion
nếu ứng dụng của bạn phụ thuộc vào phiên bản cụ thể
Kiểm tra Content-Type trong response: Đảm bảo xử lý chính xác định dạng nhận được
Hỗ trợ cả JSON và XML: Để tương thích tối đa với nhiều loại clients
Triển khai _format parameter: Hỗ trợ các clients không thể kiểm soát HTTP headers
Xử lý yêu cầu không có Accept header: Thường trả về định dạng mặc định (JSON)
Khai báo định dạng hỗ trợ: Trong Capabilities Statement
Cung cấp triển khai HTML: Cho phép trình duyệt hiển thị dữ liệu FHIR một cách thân thiện
Content negotiation là một khía cạnh quan trọng của FHIR, cho phép clients và servers giao tiếp hiệu quả bằng các định dạng khác nhau. Hiểu và triển khai đúng content negotiation sẽ cải thiện khả năng tương tác giữa các hệ thống y tế khác nhau.
Các điểm chính cần nhớ:
FHIR hỗ trợ đầy đủ cả JSON và XML với ánh xạ 1:1 giữa hai định dạng
Content negotiation được thực hiện chủ yếu thông qua HTTP Accept header và tham số _format
Versioning có thể được quản lý thông qua content negotiation
Tuân thủ thực hành tốt nhất về content negotiation sẽ cải thiện khả năng tương tác và độ tin cậy của ứng dụng FHIR
Trong series tiếp theo, chúng ta sẽ khám phá các khía cạnh khác của FHIR, bao gồm profile, extensions, và triển khai các hoạt động search nâng cao.