For those interested in consuming or publishing APIs, the number of standards and formats available can be bewildering. Though certainly an important decision, there really is no universal right answer as to which type of API or data format you should use. However, having a general knowledge of the options will ensure you can make an informed decision as to which technology best fits the needs of your particular situation.
Introduction to APIs
An API, or Application Programming Interface, is a way of transmitting information between computer programs. Since they were popularized about 10 years ago, web APIs (also known as web services) have been published in a bewildering number of competing standards and formats. Standards are the way in which the information is transmitted: eg, the road along which information travels. Formats are the way that information is structured: eg, the truck that carries the information as it moves between systems.
Standards
The ecosystem of APIs is generally moving away from complicated, transactional standards (like SOAP) towards lightweight standards based on HTTP. Within the HTTP standards, there are two that are most commonly used.
REST
REST stands for Representational State Transfer, and is essentially a way of accessing ‘objects’ via the web. An object can be anything: a news story, a weather report, a sports score. And this really is the breakthrough of REST: it takes data and turns it into an ‘object’ that matches how a computer programs understand information. With REST, you can easily write a program that reads and writes information using an API because the standard reflects the way that computer programs are generally written.
Query-based
An alternative, but also complementary approach to REST is the query-based API. Using this approach, objects are accessed through a set of ‘parameters’ append to a URL. Parameters are really just key/value pairs that can be used to identify the information. Query-based solutions are generally easier to implement, though this comes at the expense of the API consumer: it usually takes more time to build an application on a Query-based API than it does a REST API.
Transactional Standards
It’s worth mentioning, but not focusing on transactional standards. In certain circumstances, especially in the regulatory and financial world, you need to be sure that when you send a message it is successfully received. In these cases, a transactional API is going to be a necessity. The main standard in this space is SOAP, or Simple Object Access Protocol, which is built on top of HTTP but uses XML to create complicated messages. These messages can contain lots of data themselves, which is useful when you need to describe complicated data sets or include things like security, permissions and transactional information. All of this information comes at a cost: implementing SOAP based APIs is difficult, both for the publisher and the consumer.
Formats
The second common question people have about APIs is ‘which format should I use?’ There is no right answer here, but generally two choices.
JSON
JSON is an informal format, and one that has emerged quite by accident. It is actually a feature of the JavaScript programming language that has shown to be a great lightweight way of transmitting information between applications. Because JSON is simple it is quick to process and easy to write applications around. When using JavaScript, you don’t have to do any special processing, which makes JSON an ideal format for APIs that connect a JavaScript based user interface to a backend data source.
XML
XML is to data what HTML is to web pages. XML describes both the structure of data, but also the format of the data. XML can be an appealing option where you need to ensure that the person receiving the data knows exactly what the data values are. In the scientific community this is an important factor, and where XML has received the most use. However, this also comes at a cost: XML based formats are both expensive to process and complicated to use. More and more, API publishers are moving away from XML because the benefit of structured, typed information is outweighed by the cost of using it.
Others
APIs can transmit information in any format, so there are any number of alternatives to JSON and XML. However, you want to make sure that you’re building your API for developers — it should be easy to use and easy to build from. So, if you are considering an alternative format, be sure that it has wide support in the developer community you are targeting, and a good set of tools for parsing and processing the format.
Summary
We usually create APIs based on HTTP and JSON because it lowers the barrier to entry for both API publishers and consumers. However, if you take one thing away from this post, we hope it is an understanding that there is no right answer. Determining the best standard and format for an API depends on understanding the specific needs of the information and audience, and finding the right tool for the job.
