idspopd - Fotolia

Choose JSON for building APIs

In this Q&A with Apigee's chief architect, learn why it's hard to go wrong with JSON and how to boost API usability.

More and more, developers who are used to working in the Web and mobile worlds naturally turn to APIs as the most effective way to connect clients and servers, according to 

[Ninety-five percent] of APIs should just stick with JSON.
Greg BrailChief Architect, Apigee

Greg Brail. As these developers encounter application-to-application problems like business-to-business connections between enterprises, their first reaction is, "Why can't we just use an API here?"

Brail answers that API-versus-middleware question and compares API-based integration to SOA and enterprise service busses (ESBs) approaches in this SearchSOA interview. He also offers advice on such API matters as change management, XML vs. JSON data formats and uses for hypermedia.

Co-author of the O'Reilly book, APIs: A Strategy Guide, Brail has a long history in middleware development. He built middleware libraries for Citibank and was principal architect for transact plus technical lead for BEA’s WebLogic JMS. At Apigee, an API and middleware backend as a service provider, he is the architecture lead for all products.

When and why should APIs replace integration middleware?

Greg Brail: Just as APIs are fast enough for the most demanding mobile applications, and secure enough for important consumer-focused use cases, there is no reason why they cannot be the default choice for integration tasks as well. There is very little reason to use a more traditional application-to-application protocol or integration technology when an API can be used instead.

Exceptions, I think, are fewer and farther between than people think. A good example would be applications like high-frequency financial trading, where the throughput and latency demands are so extreme that even TCP, let alone HTTP, is just too slow.

Even where more typical enterprise technology like message queuing and publish/subscribe is used, in many cases, wrapping the messaging system with an API makes it easier to consume.

How do APIs as an integration approach compare to SOA and ESBs?
Brail: SOA is about connecting services within the enterprise to achieve reuse and save money. APIs build upon SOA by emphasizing developer usability and self-service, and about creating new services that can be used both inside the enterprise as well as by customers, partners, and developers. SOA didn't do much to enable those kinds of use cases.

ESBs solve part of the API integration and SOA problem, but APIs are a lot more. For instance, ESBs do nothing to make it easier for developers to consume APIs via self-service, and they do nothing to make an existing system of record safe for mobile use on the Internet by managing high-traffic volumes and providing advanced security and threat detection.

Our readers tell us that change managementis a pain point in API management. What process and technical problems does it pose?

Brail: An API is a contract between the API provider and the developer. Any contract has to clearly state what might change and how the developer will know about those changes. In the most common API style -- the URI- and verb-based style that most developers understand -- it's generally understood that once a particular URI/verb combination is out there, it won't go away without a lot of notice, or change in an incompatible way.

The key to making this contract work is good testing. Today we have tools like Swagger that let us formally specify the format of an API, and there are more and more tools appearing on the market that can use that data to test and verify an API. Without continuous testing of the API implementation, it's hard to guarantee that the contract remains valid.

What are best practices, criteria and consequences of errors in choosing data formats (XML, JSON, etc.) when designing and building APIs?
Brail: Today, I think it's hard to go wrong with JSON. It's the easiest format to create and parse in nearly any language because it is so close to what most programming languages expect, parsing is reasonably fast, and it's readable enough. I think that 95% of APIs should just stick with JSON.

The other 5%, in mind, breaks down into use cases where extreme performance is needed, and use cases where there are existing XML schemas that represent a lot of intellectual capital that you want to re-use. For extreme performance, see again high-speed trading. I'm talking about extreme performance, not a mere few thousand of tens of thousands of API calls per second. For existing XML schemas, see standards like FpML [Financial Products Markup Language] and the like where a lot of people spend a lot of time trying to create a common way to describe some very complex things in XML.

What approaches should developers and architects take to design APIs that are more usable today and viable in the future?
Brail: There are some places where Hypermedia [which extends hypertext linking to include links among any set of multimedia objects] is very effective. If the API provider and the developers understand each other well, and agree on a convention and contract, then a hypermedia-driven API can be the basis for a robust and efficient user experience -- one that allows the API provider to adjust on the fly to changing network and market conditions, in the same way that a traditional Web app can be changed based on user analytics. I don't think we'll see hypermedia-based APIs replace the idea of a very well-described URI pattern for everything in the world, but it they become a very effective way to write mobile apps.

Finally, I think that the idea of making a more traditional API "navigable" by adding hypermedia links that let a client “browse” the API just as a Web user browses a webpage, is something that a lot more APIs should be doing today.

Next Steps

Pairing REST with JSON

Parsing big data JSON files

How to prase JSON APIs with iOS

Dig Deeper on Distributed application architecture