I'm building a REST API, but I've encountered a problem.
It seems that accepted practice in designing a REST API is that if the resource requested doesn't exist, a 404 is returned.
However, to me, this adds unnecessary ambiguity. HTTP 404 is more traditionally associated with a bad URI. So in effect we're saying "Either you got to the right place, but that specific record does not exist, or there's no such location on the Internets! I'm really not sure which one..."
Consider the following URI:
http://mywebsite/api/user/13
If I get a 404 back, is that because User 13 does not exist? Or is it because my URL should have been:
http://mywebsite/restapi/user/13
In the past, I've just returned a NULL result with an HTTP 200 OK response code if the record doesn't exist. It's simple, and in my opinion very clean, even if it's not necessarily accepted practice. But is there a better way to do this?
404 is just the HTTP response code. On top of that, you can provide a response body and/or other headers with a more meaningful error message that developers will see.
Use 404 if the resource does not exist. Don't return 200 with an empty body.
This is akin to undefined vs empty string (e.g. "") in programming. While very similar, there is definitely a difference.
404 means that nothing exists at that URI (like an undefined variable in programming). Returning 200 with an empty body means that something does exist there and that something is just empty right now (like an empty string in programming).
404 doesn't mean it was a "bad URI". There are special HTTP codes that are intended for URI errors (e.g. 414 Request-URI Too Long).
As with most things, "it depends". But to me, your practice is not bad and is not going against the HTTP spec per se. However, let's clear some things up.
First, URI's should be opaque. Even if they're not opaque to people, they are opaque to machines. In other words, the difference between http://mywebsite/api/user/13, http://mywebsite/restapi/user/13 is the same as the difference between http://mywebsite/api/user/13 and http://mywebsite/api/user/14 i.e. not the same is not the same period. So a 404 would be completely appropriate for http://mywebsite/api/user/14 (if there is no such user) but not necessarily the only appropriate response.
You could also return an empty 200 response or more explicitly a 204 (No Content) response. This would convey something else to the client. It would imply that the resource identified by http://mywebsite/api/user/14 has no content or is essentially nothing. It does mean that there is such a resource. However, it does not necessarily mean that you are claiming there is some user persisted in a data store with id 14. That's your private concern, not the concern of the client making the request. So, if it makes sense to model your resources that way, go ahead.
There are some security implications to giving your clients information that would make it easier for them to guess legitimate URI's. Returning a 200 on misses instead of a 404 may give the client a clue that at least the http://mywebsite/api/user part is correct. A malicious client could just keep trying different integers. But to me, a malicious client would be able to guess the http://mywebsite/api/user part anyway. A better remedy would be to use UUID's. i.e. http://mywebsite/api/user/3dd5b770-79ea-11e1-b0c4-0800200c9a66 is better than http://mywebsite/api/user/14. Doing that, you could use your technique of returning 200's without giving much away.
That is an very old post but I faced to a similar problem and I would like to share my experience with you guys.
I am building microservice architecture with rest APIs. I have some rest GET services, they collect data from back-end system based on the request parameters.
I followed the rest API design documents and I sent back HTTP 404 with a perfect JSON error message to client when there was no data which align to the query conditions (for example zero record was selected).
When there was no data to sent back to the client I prepared an perfect JSON message with internal error code, etc. to inform the client about the reason of the "Not Found" and it was sent back to the client with HTTP 404. That works fine.
Later I have created a rest API client class which is an easy helper to hide the HTTP communication related code and I used this helper all the time when I called my rest APIs from my code.
BUT I needed to write confusing extra code just because HTTP 404 had two different functions:
the real HTTP 404 when the rest API is not available in the given url, it is thrown by the application server or web-server where the rest API application runs
client get back HTTP 404 as well when there is no data in database based on the where condition of the query.
Important: My rest API error handler catches all the exceptions appears in the back-end service which means in case of any error my rest API always returns with a perfect JSON message with the message details.
This is the 1st version of my client helper method which handles the two different HTTP 404 response:
public static String getSomething(final String uuid) {
String serviceUrl = getServiceUrl();
String path = "user/" + , uuid);
String requestUrl = serviceUrl + path;
String httpMethod = "GET";
Response response = client
.target(serviceUrl)
.path(path)
.request(ExtendedMediaType.APPLICATION_UTF8)
.get();
if (response.getStatus() == Response.Status.OK.getStatusCode()) {
// HTTP 200
return response.readEntity(String.class);
} else {
// confusing code comes here just because
// I need to decide the type of HTTP 404...
// trying to parse response body
try {
String responseBody = response.readEntity(String.class);
ObjectMapper mapper = new ObjectMapper();
ErrorInfo errorInfo = mapper.readValue(responseBody, ErrorInfo.class);
// re-throw the original exception
throw new MyException(errorInfo);
} catch (IOException e) {
// this is a real HTTP 404
throw new ServiceUnavailableError(response, requestUrl, httpMethod);
}
// this exception will never be thrown
throw new Exception("UNEXPECTED ERRORS, BETTER IF YOU DO NOT SEE IT IN THE LOG");
}
BUT, because my Java or JavaScript client can receive two kind of HTTP 404 somehow I need to check the body of the response in case of HTTP 404. If I can parse the response body then I am sure I got back a response where there was no data to send back to the client.
If I am not able to parse the response that means I got back a real HTTP 404 from the web server (not from the rest API application).
It is so confusing and the client application always needs to do extra parsing to check the real reason of HTTP 404.
Honestly I do not like this solution. It is confusing, needs to add extra bullshit code to clients all the time.
So instead of using HTTP 404 in this two different scenarios I decided that I will do the following:
I am not using HTTP 404 as a response HTTP code in my rest application anymore.
I am going to use HTTP 204 (No Content) instead of HTTP 404.
In that case client code can be more elegant:
public static String getString(final String processId, final String key) {
String serviceUrl = getServiceUrl();
String path = String.format("key/%s", key);
String requestUrl = serviceUrl + path;
String httpMethod = "GET";
log(requestUrl);
Response response = client
.target(serviceUrl)
.path(path)
.request(ExtendedMediaType.APPLICATION_JSON_UTF8)
.header(CustomHttpHeader.PROCESS_ID, processId)
.get();
if (response.getStatus() == Response.Status.OK.getStatusCode()) {
return response.readEntity(String.class);
} else {
String body = response.readEntity(String.class);
ObjectMapper mapper = new ObjectMapper();
ErrorInfo errorInfo = mapper.readValue(body, ErrorInfo.class);
throw new MyException(errorInfo);
}
throw new AnyServerError(response, requestUrl, httpMethod);
}
I think this handles that issue better.
If you have any better solution please share it with us.
404 Not Found technically means that uri does not currently map to a resource. In your example, I interpret a request to http://mywebsite/api/user/13 that returns a 404 to imply that this url was never mapped to a resource. To the client, that should be the end of conversation.
To address concerns with ambiguity, you can enhance your API by providing other response codes. For example, suppose you want to allow clients to issue GET requests the url http://mywebsite/api/user/13, you want to communicate that clients should use the canonical url http://mywebsite/restapi/user/13. In that case, you may want to consider issuing a permanent redirect by returning a 301 Moved Permanently and supply the canonical url in the Location header of the response. This tells the client that for future requests they should use the canonical url.
So in essence, it sounds like the answer could depend on how the request is formed.
If the requested resource forms part of the URI as per a request to http://mywebsite/restapi/user/13 and user 13 does not exist, then a 404 is probably appropriate and intuitive because the URI is representative of a non-existent user/entity/document/etc. The same would hold for the more secure technique using a GUID http://mywebsite/api/user/3dd5b770-79ea-11e1-b0c4-0800200c9a66 and the api/restapi argument above.
However, if the requested resource ID was included in the request header [include your own example], or indeed, in the URI as a parameter, eg http://mywebsite/restapi/user/?UID=13 then the URI would still be correct (because the concept of a USER does exits at http://mywebsite/restapi/user/); and therefore the response could reasonable be expected to be a 200 (with an appropriately verbose message) because the specific user known as 13 does not exist but the URI does. This way we are saying the URI is good, but the request for data has no content.
Personally a 200 still doesn't feel right (though I have previously argued it does). A 200 response code (without a verbose response) could cause an issue not to be investigated when an incorrect ID is sent for example.
A better approach would be to send a 204 - No Contentresponse. This is compliant with w3c's description *The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.*1 The confusion, in my opinion is caused by the Wikipedia entry stating 204 No Content - The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request. The last sentence is highly debateable. Consider the situation without that sentence and the solution is easy - just send a 204 if the entity does not exist. There is even an argument for returning a 204 instead of a 404, the request has been processed and no content has been returned! Please be aware though, 204's do not allow content in the response body
Sources
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
1. http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
This old but excellent article... http://www.infoq.com/articles/webber-rest-workflow says this about it...
404 Not Found - The service is far too lazy (or secure) to give us a real reason why our request failed, but whatever the reason, we need to deal with it.
This recently came up with our team.
We use both 404 Not found with a message body and 204 No Content based on the following rational.
If the request URI indicates the location of a single resource, we use 404 Not found. When the request queries a URI, we use 204 No Content
http://mywebsite/api/user/13 would return 404 when user 13 does not exist
http://mywebsite/api/users?id=13 would return 204 no content
http://mywebsite/api/users?firstname=test would return 204 no content
The idea here being, 'query routes' are expected to be able to return 1, many or no content.
Whatever pattern you choose, the most important things is to be consistent - so get buy in from your team.
The Uniform Resource Identifier is a unique pointer to the resource. A poorly form URI doesn't point to the resource and therefore performing a GET on it will not return a resource. 404 means The server has not found anything matching the Request-URI. If you put in the wrong URI or bad URI that is your problem and the reason you didn't get to a resource whether a HTML page or IMG.
Since this discussion seems to be able to survive the end of time I'll throw in the JSON:API Specifications
404 Not Found
A server MUST respond with 404 Not Found when processing a request to fetch a single resource that does not exist, except when the request warrants a 200 OK response with null as the primary data (as described above).
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "http://example.com/articles/1/author"
},
"data": null
}
Also please see this Stackoverflow question
For this scenario HTTP 404 is response code for the response from the REST API
Like 400, 401, 404 , 422 unprocessable entity
use the Exception handling to check the full exception message.
try{
// call the rest api
} catch(RestClientException e) {
//process exception
if(e instanceof HttpStatusCodeException){
String responseText=((HttpStatusCodeException)e).getResponseBodyAsString();
//now you have the response, construct json from it, and extract the errors
System.out.println("Exception :" +responseText);
}
}
This exception block give you the proper message thrown by the REST API
Related
I want to change data on a server via a put request, but I always get a 401 [no body] error. The response looks like the following:
I do not really understand why I get this error, because my body is not empty. My code looks like this and the values seem to be okay too. Does anyone have any idea what I'm doing wrong?
Postman Update:
The values are different right now (consent and authorisation) since its basically a new request but the values were correct before too so this change should not make a difference.
Looks like you are simply passing invalid authorization header, or maybe not passing it at all.
What happens is that you make a RestTemplate exchange call, then you get 401 from that request, and Spring propagates it and returns 500 - Internal Server Error, because there is no error handling in place.
EDIT: According to your screenshots, you are not replacing your path variables. Update the way you build your URL as listed below.
Map<String, String> pathVars = new HashMap<>(2);
pathVars.put("consent-id", consentId);
pathVars.put("authorisation-id", authorisationId);
UriComponents uri = UriComponentsBuilder.fromUri(mainLink)
.path("consents/{consent-id}/authorizations/{authorisation-id}")
.buildAndExpand(pathVars);
Verify if your authorization-id is correct
if the token has a type for example Bearer you must write so:
"Authorization": "Bearer rrdedzfdgf........."
and make sure that there is only one space between Bearer and the token
Often the problem comes from the browser locally;
if your site is online, save the part and deploy the last modifications of the site and make the test
otherwise if it is a mobile application test it on a smartphone and not a browser;
in case none of this works, do it with your backend, it works with this
I had a problem where the I would add an extra character to a password. And Insomnia(Or Postman) would return a JSON response from the server along with a 401 HTTP status code. But when I did the same thing inside a springboot app, when using catch(HttpServerErrorException e){System.out.prinln(e.getMessage());} the e.getMessage would have [no body]. I think that is a feature built in the HttpServerErrorException class where it doesn't provide the body for security purposes. Since whoever is requesting is not authorized they should not have access to it.
My team had a discussion early this week about if HTTP Codes should represent Business Failures.
Imagine a scenario where we have a Customer REST API. Within that API, we have lots of operations, like:
POST - mydomain.com/customers (receive a JSON body and create a new Customer)
GET - mydomain.com/customers/{id} (search for a specific Customer)
PATCH - mydomain.com/customers/{id} (receive a JSON body and patch a specific Customer)
DELETE - mydomain.com;customers/{id} (deletes a specific Customer)
Now, imagine a situation where I'm looking for a Customer which has the id = 5.
There's no Customer with the id = 5. What should I do in terms of HTTP status code?
Customer not found is a Business Failure. Should I return a 404 - NOT FOUND? Should I return a 200 - OK (with a JSON body describing that the Customer with ID 5 do not exist)?
We had a discussion exactly on that behavior.
Controller.java (example)
#GetMapping("/customers/{id}")
public ResponseEntity<?> handleRequestOfRetrieveCustomerById(#PathVariable("id") Integer id) throws CustomerNotFoundException {
try {
ResponseEntity.ok(customerService.findCustomerById(id));
} catch(CustomerNotFoundException e) {
// log at Controller level and rethrow
throw e;
}
}
Handler.java (example)
#ExceptionHandler(BusinessResourceNotFoundException.class)
#ResponseBody
protected ResponseEntity<Fault> handleExceptionOfBusinessResourceNotFound(BusinessResourceNotFoundException exception) {
return new ResponseEntity<Fault>(exception.getFault(), HttpStatus.NOT_FOUND);
}
In this example, a 404 - NOT FOUND is returned with a body giving more details to the client.
From reading the HTTP/1.1 Specification:
404 Not Found
The server has not found anything matching the Request-URI. No
indication is given of whether the condition is temporary or
permanent. The 410 (Gone) status code SHOULD be used if the server
knows, through some internally configurable mechanism, that an old
resource is permanently unavailable and has no forwarding address.
This status code is commonly used when the server does not wish to
reveal exactly why the request has been refused, or when no other
response is applicable.
If "The server has not found anything matching the Request-URI...", I understand that returning a 404 - NOT FOUND would be the correct approach., since the /id composes my URI (mydomain.com/customers/id)
Am I right?
Which one is the better / right (if there's a wrong way) approach?
Status codes are meant to describe the result of the server's attempt to understand and satisfy the client's corresponding request.
Ultimately, if a client requests a representation of a resource that doesn't exist, the server should return 404 to indicate that. It's essentially a client error and should be reported as such.
Returning 200 would be misleading and would cause confusion to API clients.
Sometimes the HTTP status codes are not sufficient to convey enough information about an error to be helpful.
The RFC 7807 was created to define simple JSON and XML document formats to inform the client about a problem in a HTTP API. It's a great start point for reporting errors in your API. It also defines the application/problem+json and application/problem+xml media types.
Technically and from the http point of view, 404 should also be returned for any misspelling of the entity name (cutsomer instead of customer).
So even if you decide that "customer not found" will result in http 404, you cannot conclude that http 404 will imply "entity occurrence not found".
HTTP codes exist for a reason. Whoever consumes your API should be able to handle the response straight away, without having to result on the body contents.
In your case, 404(Not Found) looks quite suitable.
Alternatively, if you always return a 200, doesn't that beat the purpose of a response code altogether? If you are getting a response, you already know that your request got through to some extent.
TLDR;
Use 404 :)
I have recently worked on a Rest API with Spring Boot and the best practices found on the internet said this :
Parameters null or value not set : 400 / Bad request
Returned value not found (record or list empty) : 404 / Not found
Exception from server (database error, network error etc.) : 500 / Internal server error
Those links will help you : best practice error handling, ControllerAdvice, error message
A REST API is part of the integration domain, not the business domain. It's a skin that your domain model wears to disguise itself as a web site aka an HTTP compliant key value store.
Here, 404 is an appropriate choice because it mimics the response that would be returned by a key value store if you tried to get a key that wasn't currently stored.
I would follow the meaning of HTTP status codes.
Wiki says (https://en.wikipedia.org/wiki/List_of_HTTP_status_codes):
This class of status code is intended for situations in which the error seems to have been caused by the client
So to be clear: mydomain.com/customers/{id} is a valid URL an the server understands the request. The fact that customer with id=5 doesn't exists has nothing to do with a "false URL" or "not understandable request".
In my opinion this should return some 2xx status code with further information inside json (definitions made by your REST API)
I need to force the client to retry its request (meaning to send the same request one more time). What I'm thinking of is a response with status-code 307 and header Location: <original-url> (that's good enough for now, unless there's a better way).
My question is, from HTTP specification point of view, what is the correct value for Location in this specific context. Or more specifically in Java having request of type HttpServletRequest, which one should I use: getRequestURI (Returns the part of this request's URL from the protocol name up to the query string in the first line of the HTTP request) or getRequestURL (Reconstructs the URL the client used to make the request containing protocol, server name, port number, and server path, but it does not include query string parameters).
Any other suggestion/comment is appreciated.
getRequestURL() returns complete URL used by the client where as getRequestURI() returns just the basic path resides in server.
i am using this technique to redirect with a response status this is my code this is useful:-
httpServletResponse.reset();
httpServletResponse.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
httpServletResponse.setHeader("SERVER-RESPONSE", "bad request");
return;
and also you can set headers in response.
I believe a redirect is the wrong status code in the first place.
Isn't this what 503 is for? (https://www.greenbytes.de/tech/webdav/rfc7231.html#status.503)
I am using Jersey (1.18) to build a REST API for my WebApplication. In a part of my code I have the following snippet.
return Response.status(Status.NO_CONTENT).entity(err_message).build();
where Status is an instance of com.sun.jersey.api.client.ClientResponse.Status;
According to Jersey Documentation NO_CONTENT should return a 204 code, instead of this, the http response has a header with 200 code.
NO_CONTENT
public static final ClientResponse.Status NO_CONTENT
204 No Content, see HTTP/1.1 documentation.
I tried to change the aforementioned code to
return Response.noContent().entity(err_message).build();
But the issue still exists.
As a side note, using NOT_FOUND instead of NO_CONTENT, return a 404 header as expected.
Any suggestion on 'How can I return 204 code?', is this a bug or I am doing something wrong.
Note: Not a duplicate of Returning 200 response code instead of 204
See this SO answer which says,
...204 means "No Content", meaning that the response contains no
entity, but you put one in it. It's likely that Jersey is switching it
to a 200 for you, which is basically identical to a 204 except that it
contains a response entity.
Finally, you can get 204 responses very simply by a couple of built-in
behaviors: void methods and null return values both map to a 204
response. Otherwise, simply return Response.status(204).build().
In other words, if you want "NO_CONTENT" then don't include content in your response.
After a little more digging I have found the problem. The W3c Documentation gives a hint.
I am quoting
10.2.5 204 No Content
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.
If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent's active document view, although any new or updated metainformation SHOULD be applied to the document currently in the user agent's active view.
The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.
In my code I have entity(err_message) which causes the problem. By removing it the 204 is returned correctly. I think somehow the Jersey or 'someone' casts the response to 200 since it has content.
Update (02/05/2015)
This blog post link (posted earlier today as an answer and then deleted), gives some additional insights about situation. Based on the content of the blog post, whenever there is any content in the HTTP response the following method is invoked. This method sets the status code back to 200.
private void commitWrite() throws IOException {
if (!isCommitted) {
if (getStatus() == 204)
setStatus(200);
isCommitted = true;
o = responseWriter.writeStatusAndHeaders(size, ContainerResponse.this);
}
}
We can say that Jersey detects that since there is some content in the response, the status code was wrongly set to 204 and it changes it to the appropriate 200.
As described here https://cloud.google.com/appengine/docs/java/endpoints/exceptions Google Cloud Endpoints only returns a very limited range of http status codes, namely:
HTTP 400 BadRequestException
HTTP 401 UnauthorizedException
HTTP 403 ForbiddenException
HTTP 404 NotFoundException (also: Timeout)
HTTP 405
HTTP 408
HTTP 409 ConflictException
HTTP 410
HTTP 412
HTTP 413
Google suggests to use the existing status codes to return custom errors:
"In many situations, you may want to use common HTTP status codes to indicate the success or failure of a user's API request. For example, if a user is attempting to retrieve an entity which does not exist, you may want to send an HTTP 404 status code saying No entity exists with ID: entityId.
You can send such common HTTP status codes by throwing an exception provided by the endpoints library as follows:
String message = "No entity exists with ID: " + entityId;
throw new NotFoundException(message);
"
Further down in the same document, Google states:
"Any other HTTP 4xx codes will be returned as error 404"
What's the problem with that? I throw 404 if my entity cannot be found, but Google also throws 404 for almost anything else that goes wrong.
With the exception of 401, 403, and 409, which I can use to tell my client what the exact error was (authorization, forbidden or conflict), I need to fall back to 400 and 404 for all my other status codes, with the result that my client never knows exactly what the problem was.
Sure I can include a human readable error message, but that is meant for RuntimeException(s) that occured in the server code, not to tell my client there was a problem with the data it sent.
Sure, I can also use the first few digits of the error description to send an application specific error code and send the generic 400 Bad Request, but I guess that's not how this should be done.
Any input appreciated. How do you return application specific error codes which your client can use to resolve an application-specific problem?
Having read the following and other posts
http://archive.oreilly.com/pub/post/restful_error_handling.html
Standard JSON API response format?
I would almost say what Google suggests is wrong, because there is no clear differentiation between http status codes and application codes. Both happen on different layers, and the client has no way to tell if it made a bad request, such as violating a contract (e.g. calling a non-existing endpoint, essentially a runtime error), or passing a wrong id (an application layer error).
Articles suggest the following solutions:
use http error codes: not always possible as discussed above
add the application error as custom response header: I would not choose this because it won't appear in the log, which will make debugging tough.
always return 200 and wrap the result in a JSON (as sockets.io does): not viable with endpoints
I came up with another solution which I admit is a compromise (a violation of the error message, in fact), but which I believe is the best suitable integration of individual application error codes into Cloud Endpoints:
I extended 400 BadRequestException, so that any error message is returned as JSON. The client still receives receives http status code 400, but instead of a String error message, it receives a JSON string like this:
{
"code": 400,
"message": "This is a human readable error message."
}
And here I have two options: Either I return code 400, which means this is a BadRequestException where the client actually violated a contract, or I return any other application specific code, which the client can easily parse and process.
My ApplicationException looks like this (it uses a custom JSONizer so it won't work for you like this but you could use JSONObject, GSON, Jackson, whatever):
import com.google.api.server.spi.response.BadRequestException;
public class ApplicationException extends BadRequestException {
private static final int DEFAULT_APPLICATION_CODE = 400; // use this code for all requests without explicit code
public ApplicationException(int code, String message) {
super(JsonResponse.build()
.add("code", code)
.add("message", message)
.toString());
}
public ApplicationException(String message) {
super(JsonResponse.build()
.add("code", DEFAULT_APPLICATION_CODE)
.add("message", message)
.toString());
}
public ApplicationException(String message, Throwable cause) {
super(JsonResponse.build()
.add("code", DEFAULT_APPLICATION_CODE)
.add("message", message)
.toString());
}
}
I haven't marked my answer as correct as I want you to keep posting further suggestions and comments if you believe there are better ways to do this.