APIs You Won't Hate
Why Do People Dislike JSON?

Why Do People Dislike JSON?

Phil Sturgeon

I’ve seen a few people promoting GraphQL and gRPC over REST, almost purely on the merits of being “not JSON”. They moan about JSON and instil the virtues of these architectures for their use of stricter type systems.

As well as blaming JSON for various imagined faults, they continue on to blame REST for an entirely non existent reliance on JSON.

REST is a architectural concept, and doesn’t care what data format you use. A REST API can receive and transmit data in any combination of JSON, XML, CSV, images, videos, binary or lolcat. It really doesn’t matter.

As explained in You Might Not Need GraphQL, if you’re mainly interested in this specific feature, your REST API can absolutely implement Protobuf, Cap’n Proto, or any other similar stricter type system.

I posted a tweet along these lines, and got a great question back.

Dislike of JSON

When you hear somebody stating their dislike for JSON, it usually stems from the same thing: weak types. A field in JSON could be an integer in one instance, string in another, object on another response.

It could change at any moment, even accidentally, and it could go unnoticed by either client or server for a while. Some weakly typed languages like PHP don’t really worry about it, as a 123 and a "123" are the same thing, but other languages certainly do fall over.

To imagine the difference, think about data structures in programming languages. When you type hint on “object” or “array” you have no idea what shape that data will be, but if you hint against a specific class or interface name then you’ve got some assurances. JSON is like an unnamed object/array, and a lot of people don’t like things being that vague.

There’s also a lack of explanation about what a field could contain. If you’re looking at a status field, you do not know what other values it could contain.

None of this has anything to do with JSON. This would be the same if you built an API in XML or CSV, yet still people blame JSON.

Data by itself is vague. Data needs metadata. This concept isn’t new, it’s just been ignored for a while, and it’s time to remember how things used to work.

Everything Has Happened Before

In the late 90's, people were building XML-RPC APIs with arbitrary fields being sent up and down. There was not much explanation about what anything was, and a string could change to an integer rather easily.

This was much worse in XML as everything is a string anyway, so XML Schema (XSD) was developed to describe the contracts. Humans and computers then knew which types which fields were expected to be, and loads of expectations could be built around that.

XML Schema was one of the core concepts of SOAP, which people then started to hate due to being overly complicated. They rushed to REST, with some people trying to “fit the entire request in the URL” as a testiment to how simple REST was.

If your idea of a good API interaction is json_decode(file_get_contents("http://api.example.org/v2/something.csv")) then you might need to read this book.

Confusing REST for this oversimplified style of interaction, then blaming it for tripping you up, is exceedingly daft.

devs be like

Everything Will Happen Again

JSON Schema is a similar tool to XML Schema. You can design JSON Schema with UML-style tools, use that JSON Schema for documentation, mocking, response validation, and all sorts of other things.

In REST this stuff is optional. You can use it if you want, or you can ignore it. Even if you implement JSON Schema, nobody has to interact with it.

"schema": "http://api.turtles.com/schemas/turtle.json",
"id": "213-1398-fdsf",
"foo": "bar",

That’s about it.

Or you can use Protobuf.

Or, you can still use JSON Schema and add a step in your build chain to generate Protobuf contracts from JSON Schema; Offering both depending on the Content-Type header.

The world is your oyster once you write specifications.

The ecosystem for JSON Schema, specifications, documentation, etc., is still ongoing and improving, but a lot of people are throwing the baby out with the bath water and jumping into whole API rewrites for a benefit they could easily have in their existing APIs.

Most importantly, let’s not confuse people by blaming JSON or REST for problems that are nothing to do with either of them.

Further Reading

If you want an easy start with JSON Schema, there are online editors you can play with.

Alternatively there’s OData, JSON-LD and a few others kicking around.

Get the newsletter

Pragmatic API, HTTP And REST info monthly

Want to get updates on what we're building at APIs You Won't Hate?

Subscribe to our newsletter

APIs You Won't Hate

APIs You Wont Hate is the recommended manual for building well designed and well crafted APIs. Join us, read our blog posts, search our community of knowledge and put it to good use building robust APIs




Powered by Vercel

© 2023 APIs You Won't Hate. All rights reserved.