API PUT methods don't accept mulitpart data, as required for some endpoints

[reitbauer]

Attempted Debugging

• [X] I have read the debugging page

Searched GitHub Issues

• [X] I have searched GitHub for the issue.

Describe the Scenario

I have tried to update the cover of a shelve with the API. I use the Insomnia client for this. If i send an "normal" put request with json data in the body, the update of name, description, books and tags works fine. But if i send a multipart request to update the image, nothing will be updated. Not the name, not the description, no other field. These are the props from the docs: In a Multipart Request it's not possible to send an array.

I hope someone can help me, to solve my problem.

Exact BookStack Version

v22.07.3

Log Content

No response

PHP Version

No response

Hosting Environment

Docker: lscr.io/linuxserver/bookstack

[ssddanbrown]

Hi @reitbauer,

All data can be updated from multipart data. For array items, it requires square bracket syntax to denote the array item index for the relevant keys. Here's a view from a working test I did in postman, showing the data value names used:

Here's the curl version of the request made in that image (With certain bits truncated/altered):

curl --location --request POST '<base_url>/api/shelves' \
--header 'Authorization: Token <token_value>' \
--form 'image=@"<path_to_image>"' \
--form 'name="My new shelf via the API!"' \
--form 'books[0]="1"' \
--form 'books[1]="2"' \
--form 'tags[0][name]="Category"' \
--form 'tags[0][value]="Books"'

[ssddanbrown]

Within 760eff397f51e1bb616202dc6a8561ea52bac3a8 I have expanded the API docs to explain the format for more complex data structures using non-JSON requests formats to help clarify the above for future API users.

[HungryHowies]

@ssddanbrown Thanks for the cURL command I was banging my head trying to figure this out 👍

[reitbauer]

@ssddanbrown: Thanks for the answer. To create a new book it works fine. But the update doesn't work:

Steps I have done:

1. Create a new shelve
2. Get back the id 6
3. Change the request from POST to PUT, add /6 and change the name
4. The response from the update you can see in the screenshot

Thanks and BR

[ssddanbrown]

@reitbauer You are very correct there. Surprised I have not come across this but think I must have only tested mulitpart PUT data from our app API tests, not externally.

This traces back to a PHP & framework limitation. For multipart and urlencoded POST data it's PHP itself that does the decoding of data. Annoyingly it specifically only does this for POST requests, not other HTTP verbs. The frameworks in use (Laravel & Smfony) defer to this PHP handling for multipart and urlencoded requests.

Delving into this, the frameworks don't want to add specific handling themselves, saying this should be handled by PHP, and the PHP core team don't want to add new versions of bad old interfaces. Bit of a deadlock there. Might actually be a pain to properly handle as the options are to implement multipart parsing app-side (or via library) or use an uncommon PHP extension.

There is a somewhat ugly workaround though!, You can instead use a POST request but add a _method parameter to the request data with a value of PUT.

I'll update the title of this issue to target the specific problem.