REST is not JSON


3 min read

REST is not JSON

I do a lot of teaching. However, sometimes when you become so familiar with something, you can develop blind spots. With the explosion of JavaScript, I've been developing front-ends mainly with frameworks like React and Angular. However, these experiences have made me develop a blind spot with respect to REST, as these frameworks often force your responses to be in JSON.

I was teaching an introduction to web development to a group of native desktop developers who have never, ever seen web development. They were familiar with object oriented programming and mainly worked with XML. During a section on REST, I mentioned that REST responses are sent as JSON. This lead to a discussion on what is JSON.

A member then why we don't send responses as XML. My response was inadequate. It was essentially, "We use to do that in 2005, but now we primarily use JSON. JSON is more lightweight over the network, so forget about XML." In the past 10 year's of the JavaScript front-end gold rush, I had completely forgot about original constrain in the REST specification - the Uniform Interface .

REST responses are based on the media-types set in the Accept header . These days we typically default to application/json, but that doesn't mean that application/xml or text/xml isn't valid. It completely is! The recent prevalent use of single-page applications makes it easier to interoperate with application/json, but it isn't the only media type.

The REST specification states that an end-point can support multiple media-types and must communicate which ones it can produce. Ten year's ago, I worked on a project that did this. There was one end-point that could respond with both application/json and image/jpeg. This single end-point returned financial data as a JSON array, but if you set the Accept header to image/jpeg it would return you a line graph.

Under the hood, the implementation would respond with an object, but as the object was leaving the application, it would use an object mapper to map the response to either application/json or image/jpeg based on the Accept header.

The beauty and magic of this is the uniform interface constraint defined in REST. Through a single end-point, the same data can be represented in different media-types. This provides a single source of truth. Remembering this experience, it makes me wonder why we added such complexity to our front-end application?

Do we really need front-end graphing libraries, when this complexity can be moved and cached in the back-end? Even that experience from ten year's ago, did we really need application/json. We could have just used text/html to return the table and have CSS manage the presentation.

json response

In the current landscape, data is converted to JSON which is then programmatically transformed into HTML or an image in the front-end. If a REST API is designed with a uniform interface, then it can respond with JSON, partial HTML fragments or an image. Not only would this simplify the front-end, but the performance would probably be better as no data transformation would be required on the front-end.

In some use cases, your front-end app could completely forego the JavaScript framework and be built with just HTML5 and Web Components! By skipping the framework, you get simplicity and performance. For more information, I highly recommend reading the book Building Hypermedia APIs with HTML5 and Node.js.