【適用於 FHIR DSTU3 版本】 FHIR 規範之資料格式探討與 REST API 使用教學。 本著作係採用創用 CC 姓名標示-相同方式分享 4.0 國際 授權條款授權， （授權網址：https://creativecommons.org/licenses/by-sa/4.0/deed.zh_TW） 歡迎多加參考與利用。

1. FHIR REST API 導論與使用
FHIR 規範之資料格式探討與 REST API 使用教學
Lorex L. Yang（楊宇凡）<ceo@sita.tech>
Nov 23, 2018 / 臺中榮民總醫院

2. 還是要來做個免責聲明

3. 因為等等會直接針對文件作探討
但是讀文件真．的．很．無．聊

4. 想睡的可以先趴下了 

5. 一樣歡迎發問、回答
ლ(◉◞౪◟◉ )ლ
再說一次，我人真的很好，不會咬人的
你可以放心跟我互動沒關係 ❤

6. 議程中使用到的資源將會公開在這裡
https://hackmd.io/s/H1JVtRQAX
剛剛沒掃到 QR Code 的，可以再掃一次


7. 這節議程要來跟各位聊聊
- FHIR 所規範的資料格式
- REST API 概觀
- 如何使用開發工具測試 REST API
- 如何透過 REST API 存取FHIR Server

8. 在接觸 FHIR 之前，我是 100% 血統純正的工程師
沒讀過合太醬料、也不是醫工系出身
台大醫科

9. 這節議程將不會解釋 FHIR 用途
但是會討論 FHIR 標準如何實作

10. 上一節我們已經完成這個

11. 現在我們要繼續來玩這個

12. 還是要來複習一下，FHIR 是什麼

13. What and Why FHIR
• Fast Health Interoperable Resources
• 把整個醫療流程／體系中會接觸到的資料全部標準化為單一資料結構
• 支援多種不同資料格式
• 採用主流資訊實作標準
 沒醫學基礎的工程師也可以理解
 要跟其他系統對接也很方便
• 可讀性高
• 格式嚴謹，Document 齊全且明確
• Developer Friendly ❤

14. FHIR 結構概觀
FHIR 對開發人員到底是什麼？

15. FHIR
• 對醫療人員來說，FHIR 是一種描述醫療資源／行為／數據／流程…etc 的方法
• 對開發人員來說，我們熟悉的 FHIR 事實上是一堆 Data Structure
• 每一個醫療資源／行為／數據／流程…etc 都是一個 Resource
• 依照不同的分類，幾個 Resource 可以組成一支 Module

16. Data Structure? Data Format?
• 所謂的 Data Structure（資料結構），是對一組資料組成的定義
• 而 Data Format（資料格式），則是表達這組資料的方法
• 一個 Data Structure 可以用許多不同的 Data Format 所表示
• 一個 Resource 只有一種 Structure，但是支援多種 Data Format
• 在開發實務上，並不需要認識所有的 Data Format，僅需挑一種來用即可

17. Data Type
Primitive Type Complex Type

18. Primitive Types 比較單純
大多數都是我們開發時常用的 Data Type
例如 string, integer, boolean…等

19. Complex Types 就比較複雜
大多都是由數個 Primitive Types 構成
例如 string, integer, boolean…等

20. 一個 Complex Type 內
甚至可以由其他 Complex Type 構成

21. 如果有寫過 PostgreSQL 的話
Primitive Types 像 Default Data Types
Complex Types像User Defined Types

22. Primitive
Primitive
Primitive
Complex
Complex

23. 另外還有一個 Reference

25. Reference 是對應到其他 Resource 的參
照
有點像是 Foreign Key 的概念

26. 資料型態（Complex）
參照 資料型態（Primitive）

27. 每個 Resource 都有一個 Structure
有學過 DB 的話，直接看 UML 比較快

29. FHIR 格式概觀
FHIR 應該如何表示？

30. FHIR 支援很多種 Data Format
本次議程先拿最常用的 XML 跟 JSON 來解釋

31. 有關這兩者的詳細規範
都可以在 RFC 文件找到
RFC：Request For Comments，由 IETF 發布的備忘錄
收集了有關網際網路的相關資訊與規範。

32. XML
Extensible Markup Language
RFC 3076

33. XML
• 是一種可擴展的標記語言，被使用來作為攜帶資料／訊息的載具
• 整個 XML 可以視為是一個實體（Entity），也可被視為一樹狀結構的文件
• 有時候被拿來做為軟體的設定檔使用

34. XML 語法結構
<name lang=“en”> Lorex
</name>
用 <> 包起
來
元素 (element) 內容 (content)
用 </> 收起來
屬性 (attribute)

35. XML 語法結構
<name lang=“en”> Lorex
</name>
標籤 (tag)

36. XML 語法結構
<good />
沒 content 的話，直接 /> 收起來

37. XML 柱姐 註解
<!-- 柱姐內容 -->
用 <!-- 跟 --> 包起來

38. XML 文件結構

39. Well-formed XML 規範
• 如果有XML文件宣告(prolog)，必須位於XML文件的第一列
<?xml version="1.0" encoding="big5" ?>
• XML文件只能有一個根標籤 (root)
整個文件在<catalog> 與 </catalog> 之間，被視為一個樹狀結構
• 開始與結束的標籤必須成對出現
例如 <catalog> </catalog>
• 非成對標籤 或 標籤中無內容，則可用「/」 符號
例如<mark> </mark>可以用<mark />表示

40. Well-formed XML 規範
• 標籤必須巢狀排列
必須是 <A><B></B></A>
• 英文大小寫有別
<A> 標籤不可與 </a>標籤配對
• 屬性必須被「'」或「''」 包括起來， 且使用的 quotes 也必須成對
如 <price currency="NT"> ....</price>
• 同一標籤不可有相同的屬性
如 <price currency="NT" currency='FR'> ....</price> 就不行
• 特殊字元的使用必須先 Escape
如 & 要用 &amp;、< 要用 &lt; 等

41. JSON
JavaScript Object Notation
RFC 7159

42. JSON
• 是一種 Lightweight 的資料交換語言
• 由許多 Object 所構成
• 格式靈活、容易閱讀

43. JSON 的 RFC 文件比 XML 好讀多了
那就直接來讀吧XD

44. JSON 基本語法
• JSON 文件必須以 [] 或 {} 把整個文件包起來
• JSON 的表達方式為 key-value 的表達方式（例如 { “name”: “Lorex”}）
• JSON 有六個結構字元：
 [：array 的起始
 ]：array 的結束
 {：物件的起始
 }：物件的結束
 :：Key 的結尾
 ;：Value 的結尾
• Key 就是欄位名稱
• Value 的內容必須是以下之一：false / true / null / object / array / number / string

45. Object
• “ 老闆不是人，是個東西 ”
• 許多小 Object 可以組成一個大 Object
• 整份文件也可視為是一個 Object
• 一份 JSON 是由許多 Object 所構成
• 一個 Object 可以是一對 key-value，可以是一個 array，也可以什麼都沒有 (null

46. 其他資料型態
• Array：可以由許多 Object 、或是 Value 集合而成
• Number：就是數字，可以為0、負數、也可以用科學符號表示，例如 3e+20 等
• String：就是字串，但遇到特殊字元時要用 作為跳脫字元。但必須用 “ ” 包起來
• Boolean：就是 true／false
• Null：什麼都沒有，就是 null，null 不等於 0、也不等於 false

47. 範例 1

48. 範例 2

49. REST API 概觀與應用
FHIR 要如何使用？

50. REST
Representational State Transfer

51. REST
• REST 是一種網路架構風格，而不是一種標準
• REST 跟 RESTful 是兩種不同的東西
 REST 是一種架構風格
 RESTful 是一種遵循 REST 風格設計而成的系統
• RESTful API 充分使用了 HTTP Protocol（GET／POST／PUT／DELETE）
• RESTful API 擁有直觀簡潔的 URI
• RESTful API 可以滿足對資源的操作
• RESTful API 善用了 HTTP Verb
• RESTful API 接受 JSON、XML、YAML 等，最常見的就是 JSON

52. RESTful API 與一般 API 的比較
一般 API
• 獲取使用者資料 GET /getAllUsers
• 獲取使用者資料 GET /getUser/1
• 新增使用者資料 POST /createUser
• 更新使用者資料 GET /updateUser/1
• 刪除使用者資料 GET /deleteUser/1
RESTful API
• 獲取使用者資料 GET /users
• 獲取使用者資料 GET /user/1
• 新增使用者資料 POST /user
• 更新使用者資料 PUT /user/1
• 刪除使用者資料 DELETE /user/1

53. Before After

54. REST API 的應用情境
單一資源（例如 /user/1）
GET 列出該筆Resource
與其下的 Attributes
POST 在該筆Resource下
新增給定的
Attributes
PUT 使用給定的
Resource與
Attributes 取代原有
Resource（整筆替
換）
PATCH 只更新該筆
Resource下指定的
Attributes（部分更
新）
多重資源（例如 /users）
GET 列出該資源組裡面所
有Resources
POST 在該資源組中新增
Resource
PUT 若該資源組中無指定
Resource，則新增
（跟POST 一樣），
否則就整筆替代該
Resource
DELETE 刪除整個資源組下的
所有 Resources

55. 透過 Postman 與 FHIR Server 互動

56. REST API 使用方法
<Method> <baseURL>/<resource>/[id]{?options}
HTTP 方法 網址 目標 resource identity
選項

57. 看不懂嗎？
GET https://hapi.fhir.tw/baseDstu3/Patient?_pretty=true
HTTP Method BaseURL Resourc
e
Options

58. Postman
測試 API 的好工具
https://www.getpostman.com/

59. Method and URL
回應視窗

60. 開始來玩玩看

61. 取得所有 Patient 資料
GET https://hapi.fhir.tw/baseDstu3/Patient

62. 取得單一 Patient 資料
GET https://hapi.fhir.tw/baseDstu3/Patient/1

63. 新增一筆 Patient 資料
• POST https://hapi.fhir.tw/baseDstu3/Patient
• Payload 如右

64. 編輯剛剛的 Patient 資料
• PUT https://hapi.fhir.tw/baseDstu3/Patient
• Payload 如右

65. 刪除剛剛新增的 Patient 資料
DELETE https://hapi.fhir.tw/baseDstu3/Patient/265

66. 開發者如何將現有資料
組織為符合 FHIR 標準的資料
然後存入 FHIR Server

67. 範例病人資料
• 姓名：王大明
• 性別：男
• 連絡電話：0912-345-678
• 聯絡地址：高雄市小港區大馬路999號
• 資料有效狀態：YES
• 生日：84/01/01

68. 組織資料步驟
• 判定、或取得各欄位所屬的 Resource 與 Field Name，並建一張表對應
原始欄位 原始資料 對應欄位 資料格式
姓名 王大明 Patient.name HumanName
性別 男 Patient.gender code
(male | female | other |
unknown)
連絡電話 0912-345-678 Patient.contact.telecom ContactPoint
聯絡地址 高雄市小港區大馬路999號 Patient.contact.address Address
資料有效狀態 Yes Patient.active boolean
生日 84/01/01 Patient.birthDate date

69. 組織資料步驟
• 以 JSON 為例，去組織資料，暫時先不要理 Complex Type 的欄位
（紅色字體為 Complex Type 欄位，因為還沒完成所以顯示 JSON 格式不正確）

70. 組織資料步驟
• 確認 Complex Type 內的格式內容，然後依次展開後填入
• 最終完成長這樣：

71. 寫入資料
• POST https://hapi.fhir.tw/baseDstu3/Patient
• Payload 如右
• 執行結果如下

72. 驗證：查詢剛剛新增的資料
• GET https://hapi.fhir.tw/baseDstu3/Patient/267

73. 補充：用 node.js 撰寫程式進行介接

74. 既然都支援 REST 了，直接串就好
• 創建空資料夾，然後 npm init
$ npm init
• 安裝 dependencies
$ npm i -S axios
• 新增 payload.json，先把 payload 寫進去，省 code 空間
• 新增 main.js，開始寫

75. node.js 簡易示範程式碼
• payload.json

76. node.js 簡易示範程式碼
• main.js

77. 執行結果

78. Q&A

79. 感謝聆聽