Upload API
Last updated
This page documents the request format, filename generation, and responses of
POST /upload/*path.Request
- curl -X POST -F "filepath=@./photo.jpg" http://localhost:8080/upload/blog/2025
| Item | Rule |
|---|---|
*path | Target folder relative to storage/image/upload/; created if missing; empty returns 400 |
| Form field | filepath (multipart/form-data) |
| Type check | Uses the part's Content-Type header; file contents are not inspected |
| Supported types | image/jpeg, image/jpg, image/png, image/webp, image/svg+xml, application/pdf |
| Size limit | None in Go; Nginx client_max_body_size 100M |
Filenames
Uploads are always renamed to
{16 alphanumerics}_{millisecond timestamp}{extension}, with the extension chosen by GetExtension from the MIME type (image/jpeg and image/jpg both become .jpg). The random characters come from math/rand, seeded with the current time at startup.Responses
Success returns
201:- {
- "success": 1,
- "filename": "ERftP1gTS7WCTeJ8_1744080848530.jpg",
- "type": "image/jpeg",
- "size": 2501808,
- "src": "http://localhost:8080/c/img/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg"
- }
configs.GetDomain() sets the domain in src: http://localhost:{PORT} when GO_ENV=development, otherwise https://{DOMAIN}.| Status | Body | Case |
|---|---|---|
400 | please assign a path first | Empty *path |
400 | can not create folder: ... | Folder creation failed |
400 | can not get file form request | Missing filepath field |
400 | can not save file | Write failed |
201 | JSON with empty filename / type / src and the part's size; nothing is saved | Unsupported type |
408 | timed out | Exceeded 30 seconds |
Checking the Result
A
201 alone does not mean the file was saved: an unsupported type also returns 201, with an empty filename. Check both the status and filename:- status=$(curl -s -o response.json -w "%{http_code}" \
- -X POST -F "filepath=@./photo.jpg" \
- http://localhost:8080/upload/blog/2025)
- if [ "$status" != "201" ] || [ -z "$(jq -r '.filename // empty' response.json)" ]; then
- echo "upload failed ($status): $(cat response.json)" >&2
- exit 1
- fi
- jq -r '.src' response.json
Even when the upload is rejected, the target folder under
storage/image/upload/ has already been created, because os.MkdirAll runs before the form field and type checks.