Best way to represent multiple JSON response in a REST service? [closed]

Question

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.

Answer 1

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.