Enterprise architect's guide to API best practices and trends
A comprehensive collection of articles, videos and more, hand-picked by our editors
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.
Why should Java developers explore using REST APIs?
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.
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.