0

I am working on a REST service in which I am trying to come up with a JSON response that I am supposed to return back. Below is the design I am able to come up with in which each line is a response for each request so we have total three response for three request wrapped around an array.

In this I will pass HTTP Status code as 200:

[
    { "response": "{\"hello\":1,\"world\":\"4\"}", "aging": "123456", "bandwidth": "100" , "error": "OK", "status": "SUCCESS" }
    { "response": "{\"hello\":2,\"world\":\"5\"}", "aging": "5432", "bandwidth": "134" , "error": "OK", "status": "SUCCESS" }
    { "response": "{\"hello\":3,\"world\":\"6\"}", "aging": "6789", "bandwidth": "234" , "error": "OK", "status": "SUCCESS" }
]

In the same way, I can have below response as well if any request failed and send HTTP Status code as 202 since it's a partial response.

[
    { "response": "{\"hello\":1,\"world\":\"4\"}", "aging": "123456", "bandwidth": "100" , "error": "OK", "status": "SUCCESS" }
    { "response": null, "aging": "0", "bandwidth": "0" , "error": "Some Error", "status": "ERROR" }
    { "response": "{\"hello\":3,\"world\":\"6\"}", "aging": "6789", "bandwidth": "234" , "error": "OK", "status": "SUCCESS" }
]

In the same way, I can have below response if all request failed.

[
    { "response": null, "aging": "0", "bandwidth": "0" , "error": "Some Other Error", "status": "ERROR" }
    { "response": null, "aging": "0", "bandwidth": "0" , "error": "Some Error", "status": "ERROR" }
    { "response": null, "aging": "0", "bandwidth": "0" , "error": "Some New Error", "status": "ERROR" }
]

I am getting above JSON response by serializing below response object:

public class TestResponse {

    private final String response;
    private final ErrorCodeEnum error;
    private final StatusCodeEnum status;
    private final String aging;
    private final String bandwidth;

    // .. constructors and getters here
}

I am trying to understand, is this the best design for returning JSON response for multiple response cases in a REST service? Or is there any better way to return a JSON response with all the proper fields?

The only problem I have is - for successful response, my JSON string is escaped with slashes in response filed in my final JSON. Not sure whether that's a good approach in REST service.

My rest service will call a library which it is using internally and that library will return back a List and then I am serializing this List into JSON Array as shown above.

closed as primarily opinion-based by Scant Roger, user53019, user22815 Dec 8 '15 at 18:27

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • It will help to give an example of the url for the rest request. – joshp Dec 8 '15 at 1:01
3

Well if you embed a unique identifier for each request, then you can respond with a more structured class and still give the client a way to know which query failed.

public class TestResponse {
    private final List<QueryResponse> responses;
    private final List<QueryError> errors;
    // .. constructors and getters here
}

public class QueryResponse {
    private final int queryID;
    private final String response;
    private final String aging;
    private final String bandwidth;
}

public class QueryError {
    private final int queryID;
    private final int errorCode;
    private final ErrorCodeEnum error;
    private final StatusCodeEnum status;
}

The point with this type of smarter organization means you can deal with all the responses and errors as they are generated and not bother transmitting or parsing portion unnecessarily. e.g. just check the length or loop through all the errors and responses.

If you don't like that order of the successful and failed queries are split and want to preserve the original query order, then rearrange it so query responses can contain response data structure and response error structure. For each QueryResponse you'd just check if error or response is null.

public class QueryResponse {
    private final ResponseData response = null;
    private final ResponseError error = null;
}

public class ResponseData {
    private final String response;
    private final String aging;
    private final String bandwidth;
}

public class ResponseError {
    private final int errorCode;
    private final ErrorCodeEnum error;
    private final StatusCodeEnum status;
}

Hope this helps. You asked for an opinion/idea.

Update: With JSON you shouldn't be too hung up on the transmitted format of the data. Serialization and Deserialization should take care of that for you unless you're trying to parse the result, which you should just avoid if possible. There are JSON libraries for every programming language out there. I didn't mind using GSON.

A sample JSON message for maybe the above/last example could look like:

[
    {
        "response": {
            "response": "{\"hello\":1,\"world\":\"4\"}",
            "aging": "123456",
            "bandwidth": "100" 
        }, 
        "error": null
    },
    { 
        "response": null, 
        "error": {
            "errorCode": 100,
            "error": "Some Error Enum Value",
            "status": "It's an error, but this should be a message?"
        }
    }
]

Note that the "response" variable name should probably change so it doesn't appear twice at different nested levels. This is just something I typed up cold, so it's not perfect.

  • Thanks garlicman. In this case, json response is going to be same what I had earlier or it will be slightly different? Can you provide an example for that as well? – david Dec 8 '15 at 17:13
  • See my updated answer. – garlicman Dec 8 '15 at 21:07
  • Thanks. Also, let's say in my JSON array all three request failed and there are different error messages for each request then what's the HTTP Status code my REST Service should return back? I mean all those three errors failed with different messages so what status code my rest service will return? – david Dec 8 '15 at 21:53
  • This is kind of open to interpretation a bit and depends on the complexity of your REST interactions. I mean HTTP status codes won't tell which or why some bulk queries failed. If you want to short cut having to deserialize the JSON to check, then a HTTP status can be way more direct. Look at the 4xx HTTP status codes. The 5xx and 500 should saved for bigger communication issues. You want to minimize overloading the meaning of HTTP status codes. It can lead to confusion later when trying to debug the system. – garlicman Dec 9 '15 at 21:36
  • Yes I do understand but I do need to return some status code back right? – david Dec 9 '15 at 21:51

Not the answer you're looking for? Browse other questions tagged or ask your own question.