idspopd - Fotolia

Manage Learn to apply best practices and optimize your operations.

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

This was last published in June 2015

Dig Deeper on API management strategy

PRO+

Content

Find more PRO+ content and other member only offers, here.

Join the conversation

9 comments

Send me notifications when other members comment.

By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy

Please create a username to comment.

Have you used JSON with APIs?
Cancel
Yes
Cancel
What was your experience like, Umesh82?
Cancel
Yes, and I regularly inspect the JSON returns in Fiddler, Jmeter, Chrome Dev Tools or Firebug.  Sometimes you find interesting things, sometimes you can use it as part of a fuzzing strategy, but JSON makes it so much easier to test APIs
Cancel
Really good Q&A!

The rise in popularity of hypermedia style APIs is great for API usability especially around self-documenting APIs. It's good to see some standards and concensus emerging in this area with tools such as Swagger, HAL and JSON API.

I've been developing an API for graphic design services (https://99designs.com/tasks/) and one of the challenges we faced was dealing with large binary file inputs and JSON didn't really feel like a good fit in these cases. We ended up using plain HTTP multipart form style uploads, but I'm curious if there are better options.
Cancel
A navigable API is an interesting idea. Perhaps that's a good idea for a Chrome extension. For viewing JSON data that is returned from APIs, I find it is best to just convert it to CSV and then open it in a spreadsheet.
Cancel
Regarding what Greg said about converting to CSV and opening in a spreadsheet, I think that fails to take advantage of the benefits JSON provides. There are so many good developer tools out there now, such as Fiddler and Postman that make it easy to capture a response, examine the JSON, and tweak your initial request to create additional requests that more efficiently test the API. JSON, and the growth and expansion of such tools have almost made good testing of an API ubiquitous with developing the API.
Cancel
Forgot to mention JSON Lint, a web based JSON validator and reformatter. http://jsonlint.com/
Cancel
For those building apps that consume it, JSON is particularly a good choice if ruby is the language.  Ruby very easily can parse them into a Hash, that looks very close to what the JSON is returned at, and its much easier to parse that way then is XML.
Cancel

-ADS BY GOOGLE

SearchSoftwareQuality

SearchCloudApplications

SearchAWS

TheServerSide

SearchWinDevelopment

Close