API: Pretty print JSON responses

[pdurbin]

Many RESTful APIs such as GitHub's pretty-print the JSON response, indenting it so it's readable.

For efficiency, javax.json (Jersey) does not pretty print JSON. One workaround looks something like this...

@GET
@Path("stuff")
public Response getStuff(@QueryParam("pretty") boolean pretty) {
    JsonArrayBuilder stuff = Json.createArrayBuilder().add("foo").add("bar");
    JsonObject jsonObject = Json.createObjectBuilder()
            .add("status", "OK")
            .add("data", stuff).build();
    if (pretty) {
        Map<String, Boolean> config = new HashMap<>();
        config.put(JsonGenerator.PRETTY_PRINTING, true);
        JsonWriterFactory jwf = Json.createWriterFactory(config);
        StringWriter sw = new StringWriter();
        try (JsonWriter jsonWriter = jwf.createWriter(sw)) {
            jsonWriter.writeObject(jsonObject);
        }
        // return "Content-Type: application/json", not "text/plain"
        MediaType mediaType = MediaType.APPLICATION_JSON_TYPE;
        return Response.ok(sw.toString(), mediaType).build();
    } else {
        return Response.ok(jsonObject).build();
    }

}

... but a better way suggested by @michbarsinai is to add a pretty-printing filter per http://docs.oracle.com/javaee/7/tutorial/doc/servlets006.htm

Perhaps by default the JSON would continue to be non-pretty for performance and efficiency but the the pretty-printing filter could be enabled with a config option.

[mercecrosas]

This sounds like a good idea - there pretty-print could also be used for
examples in the documentation (embedded in the APIs guides).

Mercè Crosas, Ph.D.
Director of Data Science, IQSS
Harvard University
http://iq.harvard.edu/merce-crosas

On Mon, Aug 18, 2014 at 8:56 AM, Philip Durbin [email protected]
wrote:

Many RESTful APIs such as GitHub's pretty-print the JSON response,
indenting it so it's readable.

For efficiency, javax.json (Jersey) does not pretty print JSON. One
work looks something like this...

@get
@path("stuff")
public Response getStuff(@QueryParam("pretty") boolean pretty) {
JsonArrayBuilder stuff = Json.createArrayBuilder().add("foo").add("bar");
JsonObject jsonObject = Json.createObjectBuilder()
.add("status", "OK")
.add("data", stuff).build();
if (pretty) {
Map<String, Boolean> config = new HashMap<>();
config.put(JsonGenerator.PRETTY_PRINTING, true);
JsonWriterFactory jwf = Json.createWriterFactory(config);
StringWriter sw = new StringWriter();
try (JsonWriter jsonWriter = jwf.createWriter(sw)) {
jsonWriter.writeObject(jsonObject);
}
// return "Content-Type: application/json", not "text/plain"
MediaType mediaType = MediaType.APPLICATION_JSON_TYPE;
return Response.ok(sw.toString(), mediaType).build();
} else {
return Response.ok(jsonObject).build();
}

}

... but a better way suggested by @michbarsinai
https://urldefense.proofpoint.com/v1/url?u=https://github.com/michbarsinai&k=AjZjj3dyY74kKL92lieHqQ%3D%3D%0A&r=wSiyrhjKYxxIcPeGBYMQoJmbjnMExhzQEXLURm5Vw4k%3D%0A&m=qHCZGAEFpaFjbz6OC47uPX6H8o4NMkfBtM67dP7un4M%3D%0A&s=0803e03ef777c41be610ddcb5f44545b7208f04fe7481cfe5b7334cea29c9e44
is to add a pretty-printing filter per
http://docs.oracle.com/javaee/7/tutorial/doc/servlets006.htm
https://urldefense.proofpoint.com/v1/url?u=http://docs.oracle.com/javaee/7/tutorial/doc/servlets006.htm&k=AjZjj3dyY74kKL92lieHqQ%3D%3D%0A&r=wSiyrhjKYxxIcPeGBYMQoJmbjnMExhzQEXLURm5Vw4k%3D%0A&m=qHCZGAEFpaFjbz6OC47uPX6H8o4NMkfBtM67dP7un4M%3D%0A&s=64dddb813bcc3660d2ccaaca8642474c9fe5bf5b78e664c650fb001edcdabf3b

Perhaps by default the JSON would continue to be non-pretty for
performance and efficiency but the the pretty-printing filter could be
enabled with a config option.

Reply to this email directly or view it on GitHub
https://urldefense.proofpoint.com/v1/url?u=https://github.com/IQSS/dataverse/issues/830&k=AjZjj3dyY74kKL92lieHqQ%3D%3D%0A&r=wSiyrhjKYxxIcPeGBYMQoJmbjnMExhzQEXLURm5Vw4k%3D%0A&m=qHCZGAEFpaFjbz6OC47uPX6H8o4NMkfBtM67dP7un4M%3D%0A&s=41212d6582e01f68ee4a50ed4ad04e49e2794856aaefea983c8ca549d2a730fb
.

[michbarsinai]

Updating my last proposal - single filter, tests for pretty=true in requests, prettifies if response type is application/json. off by default, on in "dev mode".

This way, we keep the url the same.

[pdurbin]

pretty-print could also be used for examples in the documentation (embedded in the APIs guides)

I manually pretty-print the example JSON output at http://guides.dataverse.org/en/latest/api/search.html so that it's readable.

[pdurbin]

I have a need to pretty print JSON while working on #2579 for debugging purposes (so I can actually read the JSON) so I created a method for this at 2e75546 because from what I could tell my previous code for pretty printing JSON was deleted as part of fa26ec8 . The methods are different and this time I wrote tests so I'm happier with the new method. If I'm duplicating effort, please let me know.

[michbarsinai]

My objection to doing this on the server side if not because of effort duplication. The problem is the unbounded contiguous memory allocation that this feature requires, and the fact that it's easy to do on the client side with jq or (my new favorite) HTTPie (https://github.com/jkbrzt/httpie https://github.com/jkbrzt/httpie). Client-side solution also gets you syntax coloring.

As long as it's not public API, that's fine.

If we need this on a public API, I'd go with a web filter, and put some effort into implementing this in a stream, not a string.

On 27 Oct 2015, at 16:30, Philip Durbin [email protected] wrote:

I have a need to pretty print JSON while working on #2579 #2579 for debugging purposes (so I can actually read the JSON) so I created a method for this at 2e75546 2e75546 because from what I could tell my previous code for pretty printing JSON was deleted as part of fa26ec8 fa26ec8 . The methods are different and this time I wrote tests so I'm happier with the new method. If I'm duplicating effort, please let me know.

—
Reply to this email directly or view it on GitHub #830 (comment).

[pdurbin]

@michbarsinai my use case is pretty printing the JSON in the Glassfish logs: 9b04e1a#diff-a921aa2648ecc0764975a817168935fbR32 . It's for development, for now. I'm probably commenting on the wrong issue since this one is about what we expose via the API but we have enough issues and I didn't want to create a new one about pretty printing JSON for debugging purposes. Mostly I made the comment so someone like you or @ekraffmiller or whoever else can say, "hey, we already have a method for this and it's over here." :)

[michbarsinai]

You need to try HTTPie, man. Literally go:

http GET localhost:///// <localhost://///>/

and you get the colors for free :-)

On 27 Oct 2015, at 22:05, Philip Durbin [email protected] wrote:

@michbarsinai https://github.com/michbarsinai my use case is pretty printing the JSON in the Glassfish logs: 9b04e1a#diff-a921aa2648ecc0764975a817168935fbR32 9b04e1a#diff-a921aa2648ecc0764975a817168935fbR32 . It's for development, for now. I'm probably commenting on the wrong issue since this one is about what we expose via the API but we have enough issues and I didn't want to create a new one about pretty printing JSON for debugging purposes. Mostly I made the comment so someone like you or @ekraffmiller https://github.com/ekraffmiller or whoever else can say, "hey, we already have a method for this and it's over here." :)

—
Reply to this email directly or view it on GitHub #830 (comment).

[pdurbin]

@michbarsinai ok, I brew installed it. It doesn't help with my use case but it's a nice tool. Thanks. :)

[pdurbin]

I think this would be a very nice and low-hanging-fruit feature but users aren't exactly clamoring for it so I vote we close it until there's actual user demand.

[pdurbin]

No one seems to want this but me so I guess I'll close this issue.