# HTTP API Reference

This page lists every node-image-server HTTP endpoint and the behavior shared by all requests.

## Endpoints

| Method | Path | Description | Handler | Details |
|---|---|---|---|---|
| `GET` | `/c/img/{path}` | Fetch an image, converting on the fly and writing the cache | `GetFromPath` (`app/src/router/get`) | [Image Parameters](/api-reference-image) |
| `POST` | `/upload/{path}` | Upload a file to `storage/image/upload/{path}/` | `PostToPath` (`app/src/router/post`) | [Upload API](/api-reference-upload) |
| `DELETE` | `/del/{path}` | Move a file or folder to today's trash | `DeleteFromPath` (`app/src/router/delete`) | [Delete API](/api-reference-delete) |
| `GET` | `/check/state` | Health check, returns `200` `ok` | — | — |
| `GET` | `/storage/image/...` | `express.static` serves files under `storage/image/` directly (including `upload/` and `cache/`) | — | — |
| Any | Other paths | `404` `404 Not Found` | — | — |

`{path}` may contain `/` and maps to a path relative to `storage/image/upload/`.

## Shared Behavior

| Item | Behavior | Implementation |
|---|---|---|
| `User-Agent` | Requests without a `User-Agent` header have their socket destroyed with no response | `middlewares/dataInit.ts` |
| CORS | `Access-Control-Allow-Origin: *`, allowing `GET,PUT,PATCH,POST,DELETE` | `middlewares/cors.ts` |
| Request log | Written to `storage/logs/req.log` (rotated every 3 days) with Taipei time, status, country, IP, method, URL, duration, referrer | `middlewares/logger.ts` |
| Error format | Success responses are JSON; errors are plain-text messages | Each handler |

## Routing Through Nginx

| Path | Upstream | Caching |
|---|---|---|
| `/c/img/` | `nodejs:8080` | `proxy_cache` |
| `/upload/`, `/del/`, everything else | `nodejs:3000` | Not cached |
| Path segments starting with `.` (e.g. `/.trash`) | Denied | — |

Upstream ports must match `NODE_PORT`; see [Configuration](/configuration).