# HTTP API 參考

本頁列出 go-image-server 的所有 HTTP 端點、各端點的回應格式與共通行為。

## 端點

| 方法 | 路徑 | 處理器 | 詳細 |
|---|---|---|---|
| `GET` | `/c/img/*path` | `handlers.GetFromPath` | [圖片讀取參數](/zh/api-reference-image) |
| `POST` | `/upload/*path` | `handlers.PostToPath` | [上傳 API](/zh/api-reference-upload) |
| `DELETE` | `/del/*path` | `handlers.DeleteFromPath` | [刪除 API](/zh/api-reference-delete) |
| `GET` | `/check/state` | `handleHealthCheck` | 回 `200 ok` |
| 任意 | 其他路徑 | `routes.Set404` | 回 `404 Not Found` |

`*path` 為 Gin 萬用字元參數，可包含多層 `/`；處理器會去除首尾的 `/`。

## 回應格式

| 端點 | 成功 | 失敗 |
|---|---|---|
| `GET /c/img/*path` | 圖片或 PDF 位元組（chunked） | 404 佔位 SVG（`Cache-Control: no-cache`） |
| `POST /upload/*path` | `201` JSON | 純文字錯誤訊息 |
| `DELETE /del/*path` | `200` JSON | 純文字錯誤訊息 |

上傳與刪除的錯誤一律經 `utils.HandleError` 以純文字回應並寫兩行 `[ERROR]` 日誌；讀圖錯誤經 `utils.HandleGetError` 回傳佔位圖。

## 逾時

三個處理器都在 goroutine 內工作並以 `context.WithTimeout(30s)` 等待結果。超過 30 秒回 `408`，內容為 `timed out`。Nginx 對 `/c/img/` 另設 `proxy_read_timeout`／`proxy_send_timeout` 120 秒。

## 存取控制

Go 服務本身不做任何驗證。Nginx 的 `/upload/` 與 `/del/` 區塊預留了註解掉的 `allow`／`deny`，上線前應啟用 IP 白名單，或只在內網開放這兩個路徑（見 [Nginx 設定](/zh/deployment-nginx)）。