不！沒有 Postman 我該怎麼測 API，別怕 curl 幫你搞定

前言

有時候我們開發上並不方便使用 Postman 來測試 API，但也不方便安裝其他工具，可能就剛好在伺服器上（伺服器基本上都是沒有 GUI 的），那這時候就可以使用 curl 來測試 API。

什麼是 curl

curl 全名為 Client URL，這是一套網路協定工具，支援非常多種形式，舉凡…FTP、FTPS、HTTP、HTTPS 等等，幾乎所有的網路協定都可以使用 curl 來進行測試。

Note
有的人會說 curl 或者是 cURL，本篇統一稱為 curl。

許多的工具其實都可以看到它的身影，這邊舉例六角學院所提供的 Swagger API 文件

底下可以看到有一段：

curl -X 'POST' \
  'https://ec-course-api.hexschool.io/v2/admin/signin' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "[email protected]",
  "password": "example"
}'

這段可以直接複製貼上到終端機使用

還有哪些地方可以看到它的身影呢？像是 Postman 這個 API 測試工具，當你在 Postman 測試完 API 後，點擊 Code 按鈕，就可以看到 curl 的語法了

所以接下來我們就來認識一下 curl 該如何使用吧！

curl 語法

curl 的語法非常的簡單，如果你只是測試 GET API 的話，基本上只要這一行就可以了：

curl [URL]

但實際上使用我們會需要傳遞一些參數，像是：

• Post、Get、Put、Delete 等等的 HTTP 方法
• Header 參數
• Body 參數
• 其他的參數

所以通常 curl 的語法會是這樣的：

curl [options] [URL]

這邊的 options 就是我們要傳遞的參數，URL 就是我們要測試的網址，參數部分不用擔心，我們後面會用 CRUD 來介紹一輪。

那我這邊將會使用六角學院所提供的課程練習用 TodoList API 作為範例，API Path 是 https://todolist-api.hexschool.io/，這邊的 API 文件可以參考 這裡。

Note
由於這是課程練習用，所以資料會在每日凌晨 1:15 清除。

註冊帳號（POST /users/sign_up）

這邊我們會需要先註冊一個帳號，透過 API 文件我們可以知道註冊帳號需要傳遞那些參數

{
  "email": "[email protected]",
  "password": "example",
  "nickname": "example"
}

接著呢？我們該如何使用 curl 來呼叫這個 API 呢？

我們這邊將會使用一個 -X 參數來指定 HTTP 方法，這邊的 -X 參數後面接著我們要使用的 HTTP 方法，這邊我們要使用 POST 方法，所以我們就這樣寫：

curl -X POST https://todolist-api.hexschool.io/users/sign_up

但這樣寫肯定太長，所以你可以把 -X POST 簡寫成 -XPOST

curl -XPOST https://todolist-api.hexschool.io/users/sign_up

Note
請注意，必須要為大寫的 X，小寫的 x 會變成另一種模式，也就是 Proxy 模式。

接著我們要告訴 Server 我們要傳遞的格式是一個 JSON 格式，這邊就要使用 -H 參數，這邊的 -H 參數後面接著我們要傳遞的 Header 參數，這邊我們要傳遞的 Header 參數是 Content-Type: application/json，所以我們就這樣寫：

curl -XPOST https://todolist-api.hexschool.io/users/sign_up -H "Content-Type: application/json"

接著資料該如何傳遞呢？這邊我們可以使用 -d 參數來傳遞資料，這邊的 -d 參數後面接著我們要傳遞的資料，所以我們就這樣寫：

curl -XPOST https://todolist-api.hexschool.io/users/sign_up -H "Content-Type: application/json" -d '{
  "email": "[email protected]",
  "password": "example",
  "nickname": "example"
}'

接著你貼到終端機就會發現這個帳號註冊成功了

這邊也出個小功課，登入其實也是一樣的做法，但我這邊就不贅述了，登入的 API 是 POST /users/sign_in，傳遞的資料是：

{
  "email": "[email protected]",
  "password": "example"
}

登入成功的話，它會回傳一個 token，這個 token 是用來驗證你是否有權限使用這個 API 的，這邊讓你自己去試試看吧！

點我看解答(請認真思考後再看解答)

curl -XPOST https://todolist-api.hexschool.io/users/sign_in -H "Content-Type: application/json" -d '{
  "email": "[email protected]",
  "password": "example"
}'

驗證 Token（GET /users/checkout）

這隻 API 相對單純，因為只是一個 GET API，通常我們 GET API 並不會帶上資料，以文件來講，你要將登入之後回傳的 Token 放在 Header 裡面，然後名稱是 Authorization，這邊我們就這樣寫：

curl -XGET https://todolist-api.hexschool.io/users/checkout -H "Content-Type: application/json" -H "Authorization: {{ token }}" # ← 請將 {{ token }} 替換為實際取得的 JWT Token

這邊的 [Token] 就是你登入成功後回傳的 Token，這邊你可以直接將它複製貼上到終端機上使用。

這邊的 -X 其實是可以省略的，因為 GET 是預設的 HTTP 方法，所以我們可以這樣寫：

curl https://todolist-api.hexschool.io/users/checkout -H "Content-Type: application/json" -H "Authorization: {{ token }}"

這邊也額外補充一下，其實就連 -XPOST 也可以省略，因為 curl 如果偵測到有 -d 參數的話，會自動將 HTTP 方法改為 POST，所以我們可以這樣寫：

curl https://todolist-api.hexschool.io/todos -H "Content-Type: application/json" -H "Authorization: {{ token }}" -d '{
  "content": "買晚餐"
}'

取得所有待辦事項（GET /todos）

這邊我們要取得所有的待辦事項，這邊的 API 是 GET /todos，這邊的做法跟驗證 Token 一樣，我們只要將 Token 放在 Header 裡面就可以了

curl https://todolist-api.hexschool.io/todos -H "Content-Type: application/json" -H "Authorization: {{ token }}"

是不是超簡單的呢？

新增待辦事項（POST /todos）

這邊我們要新增一個待辦事項，這邊的 API 是 POST /todos，這邊的做法跟註冊帳號一樣，我們要將資料放在 -d 參數裡面，這邊的資料是：

{
  "content": "買晚餐"
}

這邊我們就這樣寫：

curl -XPOST https://todolist-api.hexschool.io/todos -H "Content-Type: application/json" -H "Authorization: {{ token }}" -d '{
  "content": "買晚餐"
}'

這時候你應該會發現 curl 的長度變得很長，很難閱讀，這邊我們可以使用 \ 來換行，這樣就會變得比較好閱讀了

curl -XPOST https://todolist-api.hexschool.io/todos \
  -H "Content-Type: application/json" \
  -H "Authorization: {{ token }}" \
  -d '{
  "content": "買晚餐"
}'

\ 這個符號代表著換行的意思，這樣就可以讓我們的程式碼變得比較好閱讀了。

寫到現在你應該會開始疑惑為什麼 -H 參數要寫兩次，因為 HTTP 協定規定每個 Header 是獨立的一行，curl 沒有提供將多個 Header 寫成單行的能力，每個都要各自 -H。

Content-Type: application/json
Authorization: {{ token }}

所以才會需要兩次 -H 參數。

如果把這邊套用到 Fetch 語法上，你或許會比較容易懂，因為也很相似：

fetch("https://todolist-api.hexschool.io/todos", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "xxxxxx"
  },
  body: JSON.stringify({ content: "買晚餐" })
});

本質上就是一個 Key-Value 的概念。

修改待辦事項（PUT /todos/:id）

這個相信對你來講非常簡單了，我就不多做解釋，直接給答案

curl -XPUT https://todolist-api.hexschool.io/todos/-OQEAOBZbuXr4dUYXJc_ \
  -H "Content-Type: application/json" \
  -H "Authorization: {{ token }}" \
  -d '{
  "content": "改買早餐"
}'

這邊的 {{ id }} 就是你要修改的待辦事項的 ID，這邊你可以從 GET /todos 的 API 取得。

刪除待辦事項（DELETE /todos/:id）

邏輯其實與修改待辦事項一樣，只是這邊的 HTTP 方法是 DELETE，所以我們就這樣寫：

curl -XDELETE https://todolist-api.hexschool.io/todos/-OQEAOBZbuXr4dUYXJc_ \
  -H "Content-Type: application/json" \
  -H "Authorization: {{ token }}"

切換代辦狀態（PATCH /todos/:id/toggle）

這邊我們要切換代辦事項的狀態，這邊的 API 是 PATCH /todos/:id/toggle，這邊的做法跟修改待辦事項一樣，我們要將資料放在 -d 參數裡面，這邊的資料是：

{
  "completed": true
}

這邊我們就這樣寫：

curl -XPATCH https://todolist-api.hexschool.io/todos/-OQEAOBZbuXr4dUYXJc_/toggle \
  -H "Content-Type: application/json" \
  -H "Authorization: {{ token }}" \
  -d '{
  "completed": true
}'

到這邊為止很簡單吧？

顯示連線資訊

curl 有一個很強大的功能，你可以針對你所發送的請求，顯示出詳細的連線資訊，這邊我們可以使用 -v 參數來顯示詳細的連線資訊，這邊我們就這樣寫：

curl -v https://google.com

-v 除了顯示 request/response 之外，還會顯示 DNS、TCP 握手、TLS 握手等過程，這些都是有助於 Debug 的（內容太多所以可以自己試試看）。

將回應內容寫入檔案

如果回傳的內容比較多時，你可以使用 -o 將回應的內容寫入檔案，這邊我們就這樣寫：

curl -o google.html https://google.com

-o 參數後面接著你要寫入的檔案名稱，這邊我們就將回應的內容寫入 google.html 檔案裡面，這樣就可以將回應的內容寫入檔案了。

指定 User-Agent

那麼可不可以指定 User-Agent（告訴 Server 我是誰、我使用什麼瀏覽器）呢？當然可以，這邊我們可以使用 -A 參數來指定 User-Agent，這邊我們就這樣寫：

curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3" https://google.com

這邊的 -A 參數後面接著你要指定的 User-Agent，這樣就可以指定 User-Agent 了。

為什麼會特別提到 -A 呢？因為有些網站會針對無法辨識的 User-Agent 做一些限制，所以就會特別補上 User-Agent 的部分。

結論

最後這邊我也整理一下表格，整理一下本篇文章有介紹到的參數哩～

參數	功能說明	實際範例
-X	指定 HTTP 方法（例如：POST、PUT、DELETE）	curl -XPOST https://api.example.com/items
-H	傳送 Header（每個 Header 一個 -H）	curl -H "Authorization: Bearer YOUR_TOKEN"
-d	傳送資料（Request Body，常用於 POST/PUT）	curl -d '{"content":"買晚餐"}' -H "Content-Type: application/json" https://api.example.com/todos
-v	顯示詳細連線資訊（包含 request/response headers）	curl -v https://example.com
-o	將回應輸出到檔案	curl -o result.html https://example.com
-A	指定 User-Agent（模擬瀏覽器或裝置）	curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" https://example.com
\（反斜線）	換行指令，讓多行 curl 比較好閱讀	curl -XPOST https://api.example.com \ -H "Authorization: Bearer ..." \ -d '{"key":"value"}'