Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Proper Http status codes for uploading files on rest end point

We are developing an application that allows a user to upload file on rest end point.
Could someone please guide if it is correct to send 400 error code for the failure of following validation scenario:

1) The Length of file name exceeds permissible limit.
2) File name contains special characters
3) Uploaded file was empty
4) The System failed to read the uploaded file from disk.

Regards, Tarun

like image 950
Tarun Avatar asked Jan 06 '17 11:01

Tarun


People also ask

What is upload in REST API?

In the context of web applications, we call “upload” the process in which a user sends data/files from a local computer to a remote computer. Sometimes we need to expose, in our REST API, an upload operation that allows the transmission of: Binary files (of any kind)

What is the HTTP status code for REST API?

HTTP Status Codes REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result. RFC 2616 defines the Status-Line syntax as shown below: Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF

What is 303 status code in REST API?

Generally speaking, the 303 status code allows a REST API to send a reference to a resource without forcing the client to download its state. Instead, the client may send a GET request to the value of the Location header.

What is status-line in an HTTP response message?

REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result. RFC 2616 defines the Status-Line syntax as shown below: HTTP defines forty standard status codes that can be used to convey the results of a client’s request.


2 Answers

  1. The Length of file name exceeds permissible limit.

I think the 400 is not an appropriate because syntax of the request is correct in this case. The 422 Unprocessable Entity is better in this case.

  1. File name contains special characters

Illegal characters mean the syntax is broken. So 400 Bad Request is a proper response in this case. Someone may claim that a definition of illegal characters is needed so the server may authoritatively send 400.

  1. Uploaded file was empty

I think it is not an error because an empty file is a legal file.

  1. The System failed to read the uploaded file from disk.

Does the system mean the server? Then the server should return a 5xx response because it is not a client failure. In case of general read error the server should return 500.

EDIT:

Uploaded file was empty.

When application semantic forbids an empty file the 400 or 422 appropriate. More details about them is at 400 vs 422 response to POST of data

like image 110
Zaboj Campula Avatar answered Oct 07 '22 21:10

Zaboj Campula


4xx statuses are for client-side errors, 5xx are for server-side errors. So, generally you need 4xx codes for your cases 1) to 3), while 4) should be a 5xx error.

Let’s first say that for your case 4), a simple HTTP 500 seems appropriate. If you want to indicate that the client could try again later, HTTP 503 would be more suitable.

Now for 1) to 3): According to RFC 2616, HTTP 400 indicates syntax errors; this would usually be protocoll errors, e.g. invalid headers. Semantical or payload errors aren’t really defined in this generic RFC, however, (as Zaboj mentions) WebDAV offers HTTP 422, which seems suitable, though it’s not really meant for generic HTTP.

In the end, it doesn’t really matter which particular codes you send. If your upload fails with HTTP 400 or 422, in either case the client will perform some error routine (e.g. show or log the error message).

The important thing to know is that some codes can trigger client behaviour (e.g. HTTP 401 combined with certain headers can trigger an authentication dialog in a browser), and you should be aware of these side effects.

In my opinion, it is much more important to send a useful error description in the response body to help the client fix their problem, than finding the “perfect” HTTP status code. I know that REST zealots will disagree, but none of them will be able to give you the right HTTP status code for every situation.

That said, if you want to issue fine-grained error codes/messages for automated processing, you can introduce custom HTTP header fields, e.g.

X-MyApp-Error-Code: 2.1.6
X-MyApp-Error-Message: The uploaded file is empty

Then you would provide a documentation and/or SDK which reveals all possible error code values for X-MyApp-Error-Code to your API consumers.

like image 45
lxg Avatar answered Oct 07 '22 21:10

lxg