Is REST losing its flair - REST API Alternatives

This article was prepared by a guest contributor to ProgrammableWeb. The opinions expressed in this article are the author's own and do not necessarily reflect the view of ProgrammableWeb or its editorial staff.

This guest post comes from Ole Lensmar, the creator of SoapUI and Chief Architect at SmartBear Software. Follow him at @olensmar

The adoption of REST as the predominant method to build public APIs has over-shadowed any other API technology or approach in recent years. Although several alternatives (mainly SOAP) are still (very) prevalent in the enterprise, the early adopters of the API movement have taken a definitive stance against them and opted for REST as their approach and JSON as their preferred message format. All this for good reasons:

SOAP/WSDL is overly complex in most cases and difficult to consume from thin clients.

The REST architectural style fits well with HTTP and the scalability, caching and distribution best practices prevalent in large-scale web and mobile applications.

The common use of JSON within REST APIs makes them extremely easy to consume from scripting-based platforms (web/Ajax, node.js, grails, etc.)

Undoubtedly REST is still the poster child of the API movement, but there are a number of initiatives, technologies and discussions that are starting to nibble at the crust of the de-facto standard that REST has become. To name a few:

1) Asynchronous APIs

The need for pushing out data asynchronously instead of the traditional request/response doesn’t always fit well with a RESTful design. Furthermore, the underlying technologies (WebSockets, MQTT, AMQP, Stomp, pubsubhubbub/WebHooks – to name a few) are often very different from HTTP and therefore often don’t align well with REST principles either.

The need for asynchronicity is especially prevalent within the Internet of Things; connected devices need to publish status-updates, sensory data, etc. to other applications that are listening – instead of those applications having to poll them continuously, which would impose unnecessary bandwidth and processing requirements on the devices themselves (which are often extremely restricted).

2) Orchestration / Experience APIs

The resource granularity given by traditional REST APIs isn’t always an advantage; pulling required resources into a mobile dashboard or complex single-page web application can require many API requests – which adds overhead to both the client logic, bandwidth and server processing. Orchestrating internal APIs at the server and publishing very usage-specific “experience APIs” can therefore make a huge difference in performance and simplicity for client developers. These APIs don’t have any desire to follow RESTful principles – they are all about optimizing both the end user and developer experience - Netflix was one of the first to publicly tout this approach – and others have followed (see this post from TheNextWeb.com).

3) SDKs vs APIs

Most API consumers are ultimately consuming these from some high-level language; javascript, python, ruby, java, etc. which has lead to many API providers including prebuilt client libraries for these languages (Google, Facebook, etc.). Since the languages themselves are often more RPC oriented, so is the code-level API exposed by the SDK – paving way for the backend API to work in a similar fashion, perhaps by using more optimized binary protocols (see below) or a more RPC-like usage of HTTP resources (for example with JSON-RPC).

4) Binary protocols

This one ultimately ties in with several of the above; for optimized message transfer for example required in IoT devices or SDKs, several binary protocols are getting more attention and usage:
a. Apache Thrift was originally created by Facebook but is now being developed under the Apache organization and used by for example last.fm and Cloudera.
b. Google Protocol Buffers is used by all Google APIs internally.
c. Apache Avro is the primary internal protocol used by Hadoop.

Common for these is the need for an interface definition in a protocol-specific format, which is then processed by included tools to generate code for supported languages. All have support for most popular languages today – the difference between them lies in the details and naturally needs to be matched against ones specific needs.

Also worth noting is that several of the asynchronous API technologies mentioned above use a binary format – related to the bandwidth and processing restrictions imposed by their harboring devices or services.

One example of a company that has abandoned a traditional RESTful approach is Evernote; they provide their 3rd party developers with an SDK using Apache Thrift as the underlying protocol – mainly to optimize their real-time synchronization requirements – something that I’m sure many other real-time application providers will follow with interest as they decide which technologies to use for their APIs (check out this recent PW article).

Underlying a transition to any of the above is perhaps also the maturing of the API market itself; like Daniel Jacobson noted in his post referred to above, a granular REST API is perhaps good when you are targeting a large number of unknown developers – but when your API targets very specific users, markets, industries or technologies, the need to choose a more specific solution is not unreasonable - it might even result in advantages over your competitors in terms of performance, easy-of-use or security.

Obviously there is no one-size-fits-all solution for building APIs – and as the world of APIs grows it is only natural for its adopters to look elsewhere when one technology or another doesn’t fit their or their customers needs. Fortunately for us passionate technologists, building and learning new stuff and putting it to use in the best possible way for all stakeholders is what makes our world tick (or at least mine). So, I’m not opposed to this diversity, I welcome it.

It does a great job summarizing growing discontent of API practitioners against "popular REST". Hopefully it will bring us to an honest discussion about why "popular REST" wasn't RESTful at all, in the first place, and where the pop "interpretation" of REST went horribly wrong.

Case in point:

#2 has little to do with REST and everything to do with "pop" REST directly coupling internal application entity names to API messages. In REST message contains a "representation" of a resource, not the resource per se. Also what a "resource" (and therefore message) is, should be defined by the API designer, not: the "back-end developer". REST APIs do not have to be chatty at all and the complaint is really about chattiness. Breaking basic encapsulation rules and not using Facade pattern is the problem here, not: REST

#4 Binary protocol vs. JSON is a question of serialization. Proper REST APIs can be serialized in whatever transfer format, so this is purely orthogonal to the question of "to REST or not to REST".

1) Its nearly impossible to build to ideal REST API unless we have code on demand for REST API too. A RESTFUL system itself is theorized based on the working of the Web.

a)In Web its the server which defines how the state transfer should happen. Whereas in an API its the client which defines the state transfer. There is a disconnect where the server tries to mandate the state transfer via a RESTFUL API whereas the Client wants the state transfer to happen in a different manner

b) In the Web all the resources are with the servers, whereas in case of API the resources may not may not be completely with the server. So what is important is interoperability between the client and server.

What is more important is HTTP since all the communications happen over the HTTP protocol. The general perception is majority of the operations in the Web are Read Only. So with better HTTP Cacheing and proper use of HTTP status for the resources we can avoid unnecessary data transfer.

With content negotiation one can target different types of devices.

Point 1: I think its not about whether alternate systems are available are not. Point is can they scale to the Internet traffic.

Point 2: Completely agree with the author

Point 3: Its not about SDK Versus API. Its about statelessness, interoperability and backward compatibility. If an RPC system can guarantee that its well and good.

Point 4: Same as point 3. Its not about the data, its about the protocol HTTP. REST API is all about statelessness, uniform interface, cache ability

I spent a long time looking at the various Comet-like approaches for supporting responsive UI's and its ultimately hard work since you are battling really against HTTP.

Async over HTTP itself isn't itself a fundamental problem - RSS, Facebook, Twitter all prove that it can't be. I'd strongly suggest you take another look at ATOM since its not in your list. The simplicity win over a Message Broker is truly emancipating.

IoT-wise, I am a bit surprised that you think that we need to optimise (prematurely in my view) for processor or network bandwidth, since these seem to be growing faster than anything else. And as others have mentioned, there are well-trodden paths to address those areas if needed.

[...] post of the year questioned the ongoing dominance of the most prevalent method to build APIs: Is REST losing its flair &#8211; REST API alternatives. Our editor in chief,Â David Berlind, reviewed the October attack on Buffer and illustrated the [...]

The "experienced-based" APIs are state-machine-oriented, and especially when transitions are guided by hypermedia, quite in-line with RESTful architectures as described in Fielding's thesis. They don't agree with the nouns-as-resources concepts of "RESTful" as popularly understood, though, I agree.

Multiple wire formats (JSON, XML, Binary, CSV, etc.) are readily supported by REST APIs, so that's a non issue. I think a bigger opportunity exists in connection-oriented protocols for use cases where two-way, real-time communications is essential. We've succesfully layered our REST API over a websocket transport, using both binary and JSON formats, and have seen nearly an order of magnitude improvement in performance and latency.

Thanks Jon - the impression I have gotten when hearing about "experience APIs" is that any RESTfulness they might have is "by accident" - i.e. their providers have had no ambition for them to be RESTful in any way - the focus was primarily performance, usability, etc.

From what I can tell from Daniel Jacobson's description of an orchestration layer, it maps very closely to the way I have been building RESTful (and hypermedia driven) APIs for a number of years. Just because people are starting to see through the hype of "pop REST" doesn't mean that anything has changed about the properties of Fielding's REST.

&gt;&gt; "These APIs don't have any desire to follow RESTful principles â€“ they are all about optimizing both the end user and the developer experience"

"RESTful principles" aren't prohibitive to those objectives.

Designing an API â€“ any API â€“ should be about representing resources in a pragmatic, usable, efficient, stable and secure manner. Which of those attributes you choose to prioritize will influence your design, but common sense should ideally be paramount, and in my experience you'd have to go far before encountering a situation in which REST works against those guidelines.

Most of the "problems" you've raised have solutions within REST, but because of misunderstanding or incomplete knowledge we see some funky implementations. I'll only address point 2 and 3, because 1 and 4 pins REST with technology that I have not had the opportunity to test yet.

One popular and yet inaccurate belief about REST is that resources can't be aggregated. Which is the culprit in your point #2. Instead of simply aggregating resources where it *makes sense*, API developers often choose to simply include reference urls. In reality both approaches are acceptable in REST, but historically the latter has been preferred because 1) it increases the overall cachability of the API and 2) early designs of RESTful APIs weren't done with the perspective that client apps would face limitations akin to mobile networks' bandwidth. Depending on how you look at it, REST is either the way of the past, because mobile devices are here now and this approach to heavily rely on the network presents some considerable problems for them, or REST has once again gone back to be ahead of its times, because mobile technology, although popular, has not caught on. In practice though, whether to embed a resource or to simply point to its url should be a matter of careful consideration, weighing pros and cons against usage patterns (which resources get updated often? which are more likely to actually be used? proportion of mobile clients? etc).

Regarding point No.3, consider that RPC's problems don't just disappear because people who don't understand REST find it challenging (see RPC vs REST). Having observed that a significant portion of API consumers aren't well versed in REST or HTTP, I understand the rationale in providing an SDK layer on top of the API to abstract the required boilerplate, even if in RPC. But I don't see why an RPC-inspired SDK should automatically translate into also burdening the underlying API with that approach.

Let us not confused the protocol with the data that the protocol allows. HTTP allows anything as data including protocol buffers, thrift and SOAP data. The author should clarify and reference the OSI layers and speak to different protocols (not data).

It should also be specifically noted that Thrift and protobuf are NOT protocols. They are binary data formats.

And my opinion is that the use of REST (HTTP) is increasing for stateless APIs. I also feel that JSON is becoming the standard for the data of APIs. However, I would like to see more binary protocols and binary data formats being used. It is unlikely that this will happen anytime soon though.