How can I implement file upload?

[catabozan]

I tried to implement file upload into my API, but it seems like although in the tests the files are being sent, they are discarded from the request.
As I understand, it's because the application/vnd.api+json Content-Type does not support file upload.

This is how I send the request from the test files:

$response = $this
    ->jsonApi()
    ->asMultiPartFormData()
    ->withPayload($payload)
    ->post($uri);

And this is the error I get:

Symfony\Component\HttpKernel\Exception\HttpException 

The request entity has a media type which the server or resource does not support.

I guess this is because the Content-Type is not application/vnd.api+json anymore.

I found this issue on how to handle multipart form data on the old cloudcreativity/laravel-json-api repo, but I can't find that method anywhere in the docs (I assume because the issue is from 2019).

What is the best way to implement file upload?

[zlodes]

You shouldn't use json:api to upload any files.

But you can initiate an upload using json:api and some http-based files API (e.g. S3):

POST https://example.com/api/v1/files
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
	"data": {
		"type": "files",
		"attributes": {
			"name": "avatar.jpg",
			"size": 123456
		}
	}
}

And response:

{
	"data": {
		"id": "ed45a8b0-71a2-485a-8e9d-ce06035a64f6",
		"name": "avatar.jpg",
		"size": 123456,
		"status": "wait-for-uploading",
		"uploadingUrl": "https://example.com/files/a/b/c/ohsofidaodisfhadfa-sdfasdffapdfasfjoasdf",
		"uploadExpiresAt": "2022-02-22T00:00:00+00:00"
	}
}

Then upload your file using uploadingUrl.

[lindyhopchris]

@catabozan in the old package (cloudcreativity/laravel-json-api) I supported an endpoint accepting multiple media types, which effectively allowed an application to support file uploads where needed on specific resource types. I haven't yet implemented this into this new package, as I need to work out how I'm going to do it. The implementation in the previous package was a bit hacky and complicated, and I'd like to do it neater this time.

In the meantime, my recommendation is to implement the file upload as a custom action, e.g. add a custom action for /api/v1/avatars/upload as an example. Custom actions are covered in the docs here:
https://laraveljsonapi.io/docs/2.0/routing/custom-actions.html

The JSON:API spec does not define how to do a file upload. So you should just send it as a normal file upload, but that doesn't stop you sending JSON:API content in the response.

[catabozan]

Thank you for the quick reply :). I'll go with the custom action then.

Edit: By custom action I mean a custom vanilla controller and custom route. Not the laravel-json-api custom actions.