Is it a good RESTFUL API having different response format in same status code?

user_14533058 0
Viewed 977

Is front-end supposed to handle response with different json format under the same status code?

Or it's back-end's job to separate them into different status code?

I'm asking this because I'm now provided with a restful api which have different json response under status code 200.

e.g.

First one:

{
    "status": "error",
    "msg": "have no user data",
    "inputs": {
        "id": "thisisafaketestid"
    }
}

Second one:

{
    "status": "success",
    "user": {
        "id": 1,
        "name": "somename",
        "email": "someEmail@gmail.com"
    }
}

And the status code of both requests are 200.

rest
3 Answers

That first response seems like it should have a different status code. If you are looking up a specific user in this case and it is not found the statuscode should probably be 404.

Regardless, the message structure should not be different.

user_6779830

Status codes, like 200 OK, are metadata in the transfer of documents over a network domain. You asked the server for a current representation of the resource, the server is sending back to you a current representation of the resource. 200 OK is completely appropriate.

Imagine, for example, a plain old boring web server. You ask for a copy of /example.json, the server looks on disk, finds that file, and sends it back to you. What's the right status code to use? 200 OK. Do the semantics of the contents of the document change that answer? No.

It may or may not be good resource design - ie, is this the kind of document schema that makes for a good API experience?

There are cases where it does make a lot of sense: the report that describes the outcome of job-123 might indicate the job failed; the report that describes the status of server-456 might indicate that the server is unhealthy.

A document that tells us our domain process is not on the happy-path might be sharing very different information, with different fields.

The design you demonstrate here might be "fine", or might be the best available compromise.

And yes, when these kinds of designs are appropriate, the client has to parse the document to determine the semantics.

user_547340

The response when calling the API haves http status code: 200, 403, 404, 500... Usually we let the server handle the default, but sometimes we will control them (With .net is StatusCode).

  1. Is front-end supposed to handle response with different json format under the same status code?

  • Yes Please see code with jquery:

         $.ajax({
        type: type,
        url: url,    
        dataType: 'json',
        data: params,
        success: function (data) {
                if(data.status == 200){ //this is http status code
                    // success call
                    if (data.return.status == 'error1'){ //this is your logic error
                      your code here
                    }
                }
        },
        error: function (data) {
                 if (data.status == 401) { // this is http status code
                  // Unaurhorized
        }
        })
  1. Or it's back-end's job to separate them into different status code? Yes (as explained above) However in case you want to return a logical error you should do the same as your code above. That is to use the status field to return the error code. The return can be handled as follows:
        // handle http status code if needed. I usually let the server handle this by default, with return codes of 200, 404, 500..
        your code here
        // handle logic error
        if (error1) { status = "error1"} else if (error2) { status = "error2"} 
        your code here
        // execute your logic
        your code here
user_119052470
Related