Last Updated: September 27, 2021
·
4.634K
· pengwynn

Pretty JSON for humans

If you're building a web API that returns JSON, show your developers you care by prettifying output if you suspect they're a human:

pretty = !(user_agent_string !~ /(^(curl|Wget)|\b(Safari|Firefox))\b/)
extra_newline = pretty ? "\n" : ""

encode_json(obj, :pretty => pretty) + extra_newline
{
  "login": "github",
  "id": 9919,
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://secure.gravatar.com/avatar/61024896f291303615bcd4f7a0dcfb74?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-org-420.png",
  "name": "GitHub",
  "company": null,
  "blog": "https://github.com/about",
  "location": "San Francisco, CA",
  "email": "support@github.com",
  "public_repos": 100,
  "public_gists": 0,
  "followers": 12,
  "following": 0,
  "html_url": "https://github.com/github",
  "created_at": "2008-05-11T04:37:31Z",
  "updated_at": "2013-07-22T21:42:06Z",
  "type": "Organization"
}

It's the little things.

** Update**

I <3 JSONView but not all requests are browser friendly, especially when OAuth and custom media types are involved.

I also abuse jq, grc, python -mjson.tool and the like.

Doing API support daily, however, has made me appreciate that not everyone is a command line pro, is familiar with pipes, or up to speed on the latest tools.

Just a little server-side effort can improve signal to noise for newcomers. And that's a good thing.

15 Responses
Add your response

Good Tip!

Here's what the PHP might look like:


$pretty_print = 0; // E_STRICT prevention
if(isset($_GET['pretty_print']) && $_GET['pretty_print']==1){
    $pretty_print = JSON_PRETTY_PRINT;
}
json_encode($data,$pretty_print);
over 1 year ago ·

It's the little things. I second that.

over 1 year ago ·

Nice! But unuseful if developers use JSONView or other browser extension.

over 1 year ago ·

Most do.

over 1 year ago ·

Because most developers are not as nice to their API users as you are, I like to use curl and pipe the response (if it's json) through the wonderful jq (http://stedolan.github.io/jq/). It pretty prints json and gives it a nice coloured syntax. It can even get you part of the json result if you specify a path. Example | jq '.results[0]' gets you the first result from {"results":[...]}.

over 1 year ago ·

Note that JSON_PRETTY_PRINT was added in PHP 5.4.

over 1 year ago ·

+1 for jq. Love that tool.

over 1 year ago ·

I'm sorry to be the bad guy here but I think user agent based content negotiation (using the user agent as the sole signal to branch the logic of your server-level code) is dubious at best and insecure at worst.

It should be the client's responsibility to format the response when necessary. There are really great browser extensions that do this.

Also, by looking at your code, you'd want to see human readable formatting when using cURL or wget as well. For that you could use the power of Unix and pipe the output of those commands into a post processor and implement the encode_json command locally on your machine.

This way you respect the basic principles of HTTP and keep your code clean and reliable.

Do the right thing.

over 1 year ago ·

I'm sorry to be the bad guy here but I think user agent based content negotiation (using the user agent as the sole signal to branch the logic of your server-level code) is dubious at best and insecure at worst.

It should be the client's responsibility to format the response when necessary. There are really great browser extensions that do this.

Also, by looking at your code, you'd want to see human readable formatting when using cURL or wget as well. For that you could use the power of Unix and pipe the output of those commands into a post processor and implement the encode_json command locally on your machine.

This way you respect the basic principles of HTTP and keep your code clean and reliable.

Do the right thing.

over 1 year ago ·

Yes, is unuseful if the developer use JSONView, but if the person is like me that love Terminal, so, is very cool this tip.

over 1 year ago ·
over 1 year ago ·

Nice, but I prefer to copy json to chrome console

over 1 year ago ·

i use cjson if working on terminal. $ curl https://url.to.json | cjson

over 1 year ago ·

Didn't know about python -mjson.tool. Very cool, already created a function to combo with with curl :)

over 1 year ago ·

In terminal or in your Node code, if you like commas-first: https://github.com/inadarei/cleanjson

over 1 year ago ·