[Z Proposal] JSend style support for idiomatic QBit REST Java support

JSend is a spec that has a lot of client library support. QBit supports this out of the box.

JSend is a application-level specification covering how JSON responses from REST services should be formatted.

There are lots of REST services out there providing JSON data and it is good to follow a standard way that is light weight and has industry support.

A basic JSend-compliant response is as simple as this:

Basic JSend response

{
    status : "success",
    data : {
        "blogPost" : { "id" : 1, "title" : "A blog post", 
                     "body" : "Some useful content" }
     }
}

The body of the call will be in the data.

JSend style support can be turned on by setting the endpointServiceBuilder.setStandardJSONResponse(true).

There are three status types

• success
• fail
• error

Error means there was an error handling a call. Fail means there was some user data validation issue with the input parameters.

QBit's outputs the following fields for each * denotes optional.

• success (status, code, *data)
• fail (status, code, data, *message)
• error (status, code, message, *data)

QBit sends a small superset of attributes and idiomatically maps to the different exception styles.

If you mark an Exception with an @Fail annotation then this exception denotes a Fail. If this exception has a data property then we will output that data property as the data attribute. If you do not specify a data property the message property of the Exception will be used.

@Fail 
class MyException {
...

All other exceptions are considered of type Error, and no annotation is needed. QBit searched for the properties data, message, code, and uses these properties as expected.

Code attribute

If you do not specify a code (which you can only do by throwing an exception), the code is the HTTP code of the response.

The codes are as follows by default:

• 500 (Server Error) for errors
• 412 (precondition failure) for failures.
• 200 (Ok) if REST call returns a value and does not throw an exception.
• 202 (Accepted) if REST call does not return a value.
• 404 if service method is not found.
• 401 Unauthorized access.

If a code from a failure or error is numeric, and is between 400 and 599 then it will be the HTTP status code that is sent as well as the code of the JSend response. If the failure or error (denoted by throwing an exception) does not have a code then 412 and 500 will be used respectively.

Status from an HttpResponse

Note it is also possible for a QBit REST endpoint to return an HttpResponse in which case the body of the response become data, the code becomes code, and if the code is in the

• 0 to 399 range then it is a "success" response status,
• and if the code is between 400 and 499, it is a "failure" response status,
• and if the code is above 499, then it is a status of "error".

##Examples

GET /posts.json: Success with a method with a Callback or non-void return

{
    status : "success",
    code : 200,
    data : {
        "posts" : [
            { "id" : 1, "title" : "A blog post", "body" : "Some useful content" },
            { "id" : 2, "title" : "Another blog post", "body" : "More content" },
        ]
     }
}

GET /posts/2.json: Success with a method with no Callback and a void return type

{
    status : "success",
    code : 202
}

POST /posts.json (with data body: "Trying to creating a blog post"):

{
    "status" : "fail",
    "code" : 500, 
    "data" : { "title" : "A title is required" }
}

GET /posts.json:

{
    "status" : "error",
    "code" : 500,
    "message" : "Unable to communicate with database"
}

GET /posts.json: from Exception that has code property (codes should be numbers or strings)

{
    "status" : "error",
    "code" : "CUSTOM.CODE",
    "message" : "Unable to communicate with database"
}

GET /posts.json: from Exception that has code property numeric

{
    "status" : "error",
    "code" : "401",
    "message" : "Unable to communicate with database"
}