###### tags: `FHIR`
# FHIR 實作 — 使用RESTful API (一)
在此章節你會學習到:
1. 知道FHIR常用的API
2. 如何看API怎麼使用
3. 使用Postman及程式呼叫API操作(新增、刪除、修改、查詢)Server的Resources

[TOC]

## 前置作業
1. 大致了解FHIR Resource的結構
2. [Postman](https://www.postman.com)
> 此為操作API的工具，課程會用到，請下載。
3. [VS Code](https://code.visualstudio.com/download)
> 寫程式用的IDE。

## 常用的API
[FHIR RESTful API 說明文件](https://www.hl7.org/fhir/http.html#search)
- read
1. 查看某`Resource`指定`id`的資料。
- vread
1. 查看某`Resource`指定`id`及`version`的歷史資料。
- update
1. 更新某`Resource`指定`id`的資料，如果沒有這筆`id`的資料則創建。
- delete
1. 刪除某`Resource`指定`id`的資料
- history
1. 查看某`Resource`指定`id`的歷史資料。 (比較常用這個)
2. 查看某`Resource`所有的歷史資料。
- create
1. 新增某`Resource`的資料。 (id由server自動產生)
- search
1. 查詢某`Resource`的資料。

## 如何看API怎麼使用
以`read`為例
1. 點擊[FHIR RESTful API 說明文件](https://www.hl7.org/fhir/http.html#search)的`read`
2. 跳轉後看灰色方塊(code block)
3. 開始嘗試使用

- Original

GET [base]/[type]/[id] {?_format=[mime-type]}

- 代入範例

GET [base]/[type]/[id] {?_format=[mime-type]}
GET http://exaple.com/Patient/1
#或
GET http://exaple.com/Patient/1?_format=json

> 其中
> GET 為 http method
> [base] = http://example.com
> [type] = Patient (FHIR Resource Type)
> [id] = Resource id
> {} 大括弧包的是http參數

## 使用Postman
<details>
<summary>使用的Patient範例，點我查看更多</summary>

{
    "id": "1",
    "resourceType": "Patient",
    "name" : [
        {
            "use": "anonymous",
            "text": "楊O凡",
            "family": "楊",
            "given" : [
                "O凡"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1995-08-13",
    "telecom": [
        {
            "system": "phone",
            "value": "0975123456"
        }
    ]
}

</details>

### create
- 官方格式

POST [base]/[type] {?_format=[mime-type]}

- 代入範例

POST https://fhir.dicom.tw/Patient

- Postman
1. method選擇POST
2. 輸入網址 `https://fhir.dicom.tw/Patient`
3. 下方選擇`body`, 並點到`raw`, 最後選擇`JSON`
4. 把上方的Patient範例貼到`body`裡面
5. 點擊右上角的`Send`
6. 下方跑出結果並寫`201 Created`就成功囉
:::danger
請記得自己POST後出現的id代碼，後續都會用到，id長的樣子就是下方紅色框起來的`"id": "66152"`
:::

### read
- 官方格式

GET [base]/[type]/[id] {?_format=[mime-type]}

- 代入範例

GET https://fhir.dicom.tw/Patient/66152

- Postman
>跟上方都差不多就不放圖了
1. method選擇GET
2. 輸入網址 `https://fhir.dicom.tw/Patient/66152`
>記得把`66152`改成自己的ID
3. 點擊`Send`
4. 跑出結果以及`200 OK`

### update
- 官方格式

PUT [base]/[type]/[id] {?_format=[mime-type]}

- 代入範例

PUT https://fhir.dicom.tw/fhir/Patient/66152

- Postman
1. method選擇PUT
2. 輸入網址 `https://fhir.dicom.tw/Patient/66152`
3. 下方選擇`body`, 並點到`raw`, 最後選擇`JSON`
4. 隨意更改原本範例的資料，這裡把名字楊O凡改成楊阿熊
5. 點擊`Send`
6. 跑出結果以及`200 OK`

### vread
剛剛已經update過，vread則是看某資料指定的版本的資料，所以照理來講我們ˊ有version 1跟version 2了。

- 官方格式

GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}

- 代入範例

GET https://fhir.dicom.tw/fhir/Patient/66152/_history/1

- Postman
1. method選擇GET
2. 輸入網址`https://fhir.dicom.tw/Patient/66152/_history/1`
> 查看第一版 楊O凡的資料
3. 點擊`Send`
4. 跑出結果以及`200 OK`
:::success
以下的圖可以看到versionId為1，以及第1版時名字為楊O凡的結果
:::

### history
示範查看某`Resource`指定`id`的歷史資料。
- 官方格式

 GET [base]/[type]/[id]/_history{?[parameters]&_format=[mime-type]}

- 代入範例

GET https://fhir.dicom.tw/fhir/Patient/66152/_history

- Postman
1. method選擇GET
2. 輸入網址`https://fhir.dicom.tw/Patient/66152/_history`
3. 點擊`Send`
4. 跑出結果以及`200 OK`
:::success
以下的圖可以看到FHIR以Bundle回傳2筆的歷史資料
:::

### search
#### search parameter
我知道有Patient，但我有什麼方式查詢Patient?
1. 查看Search parameters [點我跳到Patient Resource](https://www.hl7.org/fhir/patient.html)
2. 拉到最下面
:::warning
這邊不細講每個Type要怎麼搜尋，如果有興趣可以點type進去自己看。
:::
#### 範例
示範找到名字有`阿熊`的資料
- 官方格式

GET [base]/[type]{?[parameters]{&_format=[mime-type]}}

- 代入範例

GET https://fhir.dicom.tw/fhir/Patient/66152?name=阿熊

- Postman
1. method選擇GET
2. 輸入網址`https://fhir.dicom.tw/fhir/Patient?name=阿熊`
3. 點擊`Send`
4. 跑出結果以及`200 OK`
:::success
以下的圖可以看到找到了含有阿熊的資料
:::

### delete
- 官方格式

DELETE [base]/[type]/[id]

- 代入範例

DELETE https://fhir.dicom.tw/fhir/Patient/66152

- Postman
1. method選擇DELETE
2. 輸入網址`https://fhir.dicom.tw/fhir/Patient/66152`
3. 點擊`Send`
4. 跑出結果以及`200 OK`
:::success
可以看到回傳說明已經刪除成功的information
:::