Upload API

Last updated


This page documents the request format, filename generation, and responses of POST /upload/*path.

Request


  1. curl -X POST -F "filepath=@./photo.jpg" http://localhost:8080/upload/blog/2025

ItemRule
*pathTarget folder relative to storage/image/upload/; created if missing; empty returns 400
Form fieldfilepath (multipart/form-data)
Type checkUses the part's Content-Type header; file contents are not inspected
Supported typesimage/jpeg, image/jpg, image/png, image/webp, image/svg+xml, application/pdf
Size limitNone 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:
  1. {
  2. "success": 1,
  3. "filename": "ERftP1gTS7WCTeJ8_1744080848530.jpg",
  4. "type": "image/jpeg",
  5. "size": 2501808,
  6. "src": "http://localhost:8080/c/img/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg"
  7. }

configs.GetDomain() sets the domain in src: http://localhost:{PORT} when GO_ENV=development, otherwise https://{DOMAIN}.
StatusBodyCase
400please assign a path firstEmpty *path
400can not create folder: ...Folder creation failed
400can not get file form requestMissing filepath field
400can not save fileWrite failed
201JSON with empty filename / type / src and the part's size; nothing is savedUnsupported type
408timed outExceeded 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:
  1. status=$(curl -s -o response.json -w "%{http_code}" \
  2. -X POST -F "filepath=@./photo.jpg" \
  3. http://localhost:8080/upload/blog/2025)
  4. if [ "$status" != "201" ] || [ -z "$(jq -r '.filename // empty' response.json)" ]; then
  5. echo "upload failed ($status): $(cat response.json)" >&2
  6. exit 1
  7. fi
  8. 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.
中文