This content is part of the Essential Guide: Enterprise architect's guide to API best practices and trends

JavaOne 2013: Pairing REST and JSON to build APIs

Learn tips on best practices for building REST and JSON APIs from a presenter at JavaOne 2013.

Building a Web-accessible application programming interface is easy, but making one that performs well and doesn't break isn't, according to JavaOne 2013 conference speaker Les Hazlewood, chief technology officer of Stormpath. Back at JavaOne by popular demand, Hazlewood's presentation on Tuesday demonstrated best practices for building Beautiful REST + JSON APIs with JAX-RS and Jersey.

“A good Representational State Transfer [REST] API [application programming interface] is simple on the surface, even if the back end is more complicated," said Hazlewood in an interview just prior to his presentation. An API focuses on collections of things and how to represent individual things. Reduce API to collections and search against all books or published items purchased, and you will have an elegant solution that's intuitive and not overly complex.

In this Q&A, Hazlewood drills down into API best practices, the pros and cons of REST APIs and JavaScript Object Notation (JSON), and more.

Why should Java developers explore using REST APIs?

Les HazlewoodLes Hazlewood

Les Hazlewood: REST as an architectural style builds on a top of much [of] what exists already in HTTP. How you exchange data, the semantics of how you create, read, update and delete data is always built into the HTTP specification. REST codifies how certain scenarios should work when exchanges creating read-delete happen across disparate machines.

That's mostly what REST is about; codifying how these actions are happening across disparate machines. Because it's standing on HTTP, I can have a Linux machine, which can talk to a Windows machine, which can talk to a Macintosh machine. It's not platform- or vendor-specific. [It is] because of the ubiquity of HTTP it follows that you have ubiquity with REST. Everything -- Python, PHP, Java and C# -- can all work with REST.

REST is deceivingly simple on all fronts. Everyone thinks they understand HTTP. It's just this thing your Web browser speaks. They know the HTTP protocol, what a GIT is and what a POST is because they've been filling out Web forms for years. So because REST just uses HTTP, developers think it's simple, but REST services today are more and more not XML, which is traditional with SOAP.

What is difficult about working with REST?

Hazlewood: That is the reason why my presentation exists. REST is an architectural style, but methodologies using it haven't been formalized into a standard or specification. With style comes interpretation. How I think it should function can be slightly different from the way you think it should function. Because it is not a spec that machines can replicate, there's the human element that introduces ambiguity. That loophole [means] getting things [to be] easy to use or right is not always simple. REST and JSON are simple. HTTP is simple. But making sure you pair those two together to solve particular problems in a way that's intuitive is not codified anywhere.

What are other reasons why you recommend pairing JSON with REST in your JavaOne presentation?

Hazlewood: REST and JSON offer a more human-friendly way of representing data; data that doesn't look as congested as XML; that's easier to scan visually with your eyes. That has been the real reason for wider adoption of JSON.

JSON is a grammar specification. Basically strings, numbers, null, not null and that's about it. It allows you -- in a simple format -- to represent complex things with a minimal amount of metadata. It's so simple it can be used in many different contexts. It's easy for machines to parse. It's easy for people to read.

JavaScript (JS) is one of the most dominant programming languages in the world. Even if the main app is built in Java or Python or C#, odds [are] high [that] if you have a webpage, or a visual user interface, there's going to be some JavaScript. JSON is compatible with JS. Anyone who has programming experience with JS will find it easy to understand JSON. If you already use JS, it's easy to integrate with an API. If an API returns JSON and you're already writing JS, then your programming language already knows how to interpret data that comes back from the server. JSON leverages JS, which is hugely popular already, to be used for data exchange, not just [for] writing software.

When is using JSON a good choice and when is it a bad choice?

Hazlewood: Clearly, XML is better at structure data representation. There's more information inside of an XML document, and types can be presented a bit more effectively in an XML document. XML is very well-suited for data exchange, but ease of use is swaying developers. JSON is easier to scan with their eyes. XML is definitely more complex by design. JSON is a very simple grammar. Talking about language design, JSON is built off only a very few core elements, and everything is built up from there. Because of its simplicity, it's very easy to manipulate and to understand. JSON is not as well-suited for machines consuming information compared to XML. XML does a better job for machines.

Dig Deeper on Topics Archive