Hi ! We have been working on a Flameshot upload plugin for XBackBone and documented several non-obvious API behaviours that trip up client authors. Posting here in case it's useful for the docs or other integrators.
Full notes with code examples: https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command/src/branch/main/plugins/xbackbone/NOTES.md
Summary of issues:
1. "Token not specified" on large files (PHP silent truncation)
When a POST body exceeds PHP's post_max_size, PHP silently sets POST‘toanemptyarray—returning‘"message":"Tokennotspecified."‘evenwhenthetokeniscorrect.Thisisindistinguishablefromagenuinelymissingtoken.Sendingthe‘token‘field∗before∗the‘upload‘fieldinthemultipartbodyhelpsinpartial−readscenarios.Aclearererrorwhen‘_POST to an empty array — returning {"message":"Token not specified."} even when the token is correct. This is indistinguishable from a genuinely missing token. Sending the token field before the upload field in the multipart body helps in partial-read scenarios. A clearer error when POST‘toanemptyarray—returning‘"message":"Tokennotspecified."‘evenwhenthetokeniscorrect.Thisisindistinguishablefromagenuinelymissingtoken.Sendingthe‘token‘field∗before∗the‘upload‘fieldinthemultipartbodyhelpsinpartial−readscenarios.Aclearererrorwhen‘_SERVER['CONTENT_LENGTH'] > post_max_size would help integrators diagnose this immediately rather than assuming their token is wrong.
- HTTP 413 returns HTML, not JSON
When nginx rejects the upload via client_max_body_size, clients receive an HTML error page rather than JSON. Clients must check the HTTP status code before attempting to parse the body. A note in the docs distinguishing the nginx limit (client_max_body_size) from the PHP limit (post_max_size) — both must be set — would prevent a lot of confusion, as many users set one and not the other.
- Linux script uses xclip (broken on Wayland)
The generated bash script uses echo "${URL}" | xclip -selection c which silently does nothing on Wayland sessions (most modern KDE Plasma and GNOME desktops). Detecting $WAYLAND_DISPLAY and branching to wl-copy would fix this for the majority of current Linux desktop users.
- Token rotation gives no hint
A 400 "Invalid token" response after an admin action gives no indication the token was regenerated. A small addition to the message body — e.g. "message": "Invalid token. If you recently regenerated your token, download a new script from your profile page." — would save users a lot of confusion.
- Field name is upload, not file
Worth a prominent mention in the API docs, most generic uploader configurations default to file and silently fail with no obvious error.
Happy to submit a docs PR for any of these if useful.
Hi ! We have been working on a Flameshot upload plugin for XBackBone and documented several non-obvious API behaviours that trip up client authors. Posting here in case it's useful for the docs or other integrators.
Full notes with code examples: https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command/src/branch/main/plugins/xbackbone/NOTES.md
Summary of issues:
1. "Token not specified" on large files (PHP silent truncation)
When a POST body exceeds PHP's
post_max_size, PHP silently setsPOST‘toanemptyarray—returning‘"message":"Tokennotspecified."‘evenwhenthetokeniscorrect.Thisisindistinguishablefromagenuinelymissingtoken.Sendingthe‘token‘field∗before∗the‘upload‘fieldinthemultipartbodyhelpsinpartial−readscenarios.Aclearererrorwhen‘_POSTto an empty array — returning{"message":"Token not specified."}even when the token is correct. This is indistinguishable from a genuinely missing token. Sending thetokenfield before theuploadfield in the multipart body helps in partial-read scenarios. A clearer error whenPOST‘toanemptyarray—returning‘"message":"Tokennotspecified."‘evenwhenthetokeniscorrect.Thisisindistinguishablefromagenuinelymissingtoken.Sendingthe‘token‘field∗before∗the‘upload‘fieldinthemultipartbodyhelpsinpartial−readscenarios.Aclearererrorwhen‘_SERVER['CONTENT_LENGTH'] > post_max_sizewould help integrators diagnose this immediately rather than assuming their token is wrong.When nginx rejects the upload via client_max_body_size, clients receive an HTML error page rather than JSON. Clients must check the HTTP status code before attempting to parse the body. A note in the docs distinguishing the nginx limit (client_max_body_size) from the PHP limit (post_max_size) — both must be set — would prevent a lot of confusion, as many users set one and not the other.
The generated bash script uses echo "${URL}" | xclip -selection c which silently does nothing on Wayland sessions (most modern KDE Plasma and GNOME desktops). Detecting $WAYLAND_DISPLAY and branching to wl-copy would fix this for the majority of current Linux desktop users.
A 400 "Invalid token" response after an admin action gives no indication the token was regenerated. A small addition to the message body — e.g. "message": "Invalid token. If you recently regenerated your token, download a new script from your profile page." — would save users a lot of confusion.
Worth a prominent mention in the API docs, most generic uploader configurations default to file and silently fail with no obvious error.
Happy to submit a docs PR for any of these if useful.