Modern API Architectural Styles Offer Developers Choices

Janet Wagner, Data Journalist / Full Stack Developer
Jun. 13 2014, 12:43PM EDT

As the way we use technology evolves, so have API architectures. The current rise (and eventual prevalence) of the Internet of Things (IoT) is making it necessary to create new API architectural styles addressing scenarios that go beyond client/server.

It is for this reason that a recent study by CA Technologies was particularly interesting.

The survey was led by The API Academy, an expert group at CA Technologies that provides consulting on API business strategy, design and architecture best-practices. The survey, which was promoted to the CA customer base, resulted in 180 responses from API management professionals and enterprise architects.

Results of the survey--which focused on the future of API design and deployment--showed a fairly even split between JSON and XML, with 50.5% of respondents choosing JSON and 47.8% choosing XML. Further:

  • 43.5% support CRUD over HTTP - with an additional 18.8% intending to add CRUD support
  • 41.9% support SOAP over HTTP - with an additional 19.1% intending to add SOAP support
  • 26.3% support Hypermedia over HTTP - with an additional 28% intending to add Hypermedia support

It is that second point that led ProgrammableWeb to reach out to Irakli Nadareishvili, director of API Strategy at CA, to find out how the company interprets the high number for SOAP support over HTTP.

"We do not interpret the results of the survey as SOAP having a significant future,” he said. “We certainly don't see that in our practice, elsewhere. Rather the results are an indication that while other API design styles are probably going to gain more prominence, SOAP still represents a significant portion of current APIs. Programmable Web's independent research, while possibly skewed towards open web APIs, seems to support that belief."

(An infographic that highlights the survey responses is available for download.)

To provide more context around what design styles are being used when and why, the API Academy website has a section that covers web API architectural styles in great detail and includes several videos.

Although there are many different web architecture styles, there are four primary architectural styles that are best known and most commonly used:

View Complete Survey - Image Credit: API Academy

Tunneling Style

The tunneling style is usually associated with SOAP, which was the predominant paradigm for APIs for many years. However, the popularity and use of SOAP APIs has been on the decline for well over a decade. There are many reasons for the decline:

  • SOAP is complicated and difficult for developers to understand and consume.
  • SOAP requires a lot of infrastructure to support it. (SOAP is never used for mobile applications because it is too big.)
  • SOAP is well-defined with strict rules, and, as such, does not allow for developer innovation.

At the time of this writing, the eBay platform features 13 APIs, most of which are tunneling style APIs. ProgrammableWeb published an article last year that reviews the eBay platform suite of APIs. Another example of a tunneling-style API is the suite of PayPal Classic APIs. Tunneling style attributes include:

  • Interface at the component level
  • Binds to the components that hold the objects in the domain
  • Publish and secure endpoints
  • Uses an XML-centric message format

Although the use of SOAP among developers has declined significantly, SOAP is still used by many enterprises for specific use cases, such as when strict end-to-end security is needed and for third-party authentication.

URI Style

The URI style is probably the most well-known and commonly used web architecture style in use today. It is far less complex than the tunnel model--URI style APIs are relatively easy to build and consume.

The Box API and StackMob API are good examples of HTTP-CRUD style APIs. Last year, ProgrammableWeb published an in-depth article that looks into the Box API. URI Style attributes include:

  • Interface at the object level
  • Binds to the objects in the domain
  • Predefined URIs and query parameters
  • CRUD (also referred to as objects)

URI style APIs are often used for public APIs, mobile and web apps, and to expose web services and data for legacy systems with a SOAP back end.

Hypermedia Style

The hypermedia API architectural style uses hypermedia as the foundation of the design and is based on the REST architectural style as defined by Roy Fielding, senior principal scientist at Adobe Systems and Apache co-founder, in his dissertation for UC Irvine published in 2000. PayPal REST APIs and the Elastic Path Cortex Hypermedia API are examples of hypermedia style APIs. Hypermedia style attributes include:

  • Interface at the message level
  • Binds to messages
  • Commonly associated with REST
  • Provides its own URIs
  • HATEOAS - hypermedia as the engine of application state

ProgrammableWeb recently published an article that demonstrates how to create a hypermedia API and the benefits of HATEOAS. One of the biggest benefits of the hypermedia style API is that any API changes impacting the workflow will not break applications that are using the API. Hypermedia APIs provide extensibility, and can support client applications and services for the very long term.

Although hypermedia APIs are starting to gain some popularity, many developers find them difficult to use.

"Hypermedia APIs can deliver a brilliant solution for large, highly distributed systems where there's a lot of unpredictability and where other styles would be challenged,” explained CA’s Nadareishvili. “They're a good fit when an API provider has little control over consumers and there's large amount of change in requirements over time. This isn't necessarily the case for everybody, so the complexity may not be worth it for everybody."

Event-Driven Style

The event-driven architectural style is fairly new and has been gaining popularity in the last few years. One example of an event-driven architectural style is the WebSocket protocol, which provides full-duplex transmission of data between a client and server. The suite of Ducksboard APIs includes a WebSocket Pull API. Another example of an event-driven style API is the CR8 CREATE 3D Print File Analysis Free API.

Event-driven style attributes include:

  • Client and/or the server listens for new events
  • Events are transmitted as they occur via asynchronous messages

Event-driven style APIs are used to build many different types of modern and next-generation apps, such as:

  • Event-driven apps with web browsers as universal clients
  • Social streaming and live messaging apps
  • Message-intensive apps such as multiplayer video games
  • Stock exchange apps that relay trading data in real time
  • Real-time BI dashboard and data analytics apps

Blurring of the lines

While it's important to be able to categorize API architectural styles, there is some blurring of the lines among them. This has led to much debate in the industry.

According to Fielding, an architectural style is a set of architectural constraints. In his dissertation he states,

"An architectural style is a coordinated set of architectural constraints that has been given a name for ease of reference. Each architectural design decision can be seen as an application of a style."

Mike Amundsen, director of API architecture, API Academy at CA Technologies, published a post on his blog that covers the constraints as described by Fielding.

Debate about “RESTful” APIs has been especially contentious. There are several perspectives regarding this debate:

  • Many people believe that REST is any HTTP-based API that doesn’t use SOAP.
  • Some people are "Fielding purists," believing that a truly RESTful API must meet the criteria as defined in Fielding's UC Irvine dissertation.
  • Some people are "Hypermedia enthusiasts," strongly advocating the use and adoption of Hypermedia APIs.
  • Some people believe in "Pragmatic REST," not strict REST as defined by Fielding. They take a pragmatic approach to API design.

The REST debate, along with discussions about hypermedia APIs and SOAP, can be seen quite often in API forums and groups. There was a recent discussion in the API Craft group about REST not too long ago.

An article about API design and Pragmatic REST was published on the Apigee blog last year. In the article, Brian Mulloy writes that,

“The API community has some agreement on what a compliant client looks like and what makes up a SOAP API, but we don’t have an intellectual framework for the way popular apps and web APIs work today. We must look at the constraints of REST and keep in mind the way custom apps are built today, by multiple app developers, using multiple apps, and web APIs."

API Academy members have been early and vocal champions of Hypermedia APIs. However, they do not see HTTP-CRUD style APIs being replaced with Hypermedia APIs.

"We don't necessarily see Hypermedia APIs as the direct replacement of HTTP CRUD style, at least not in the short term,” Nadareishvili told ProgrammableWeb. “Hypermedia APIs are currently more complex to provide and consume than HTTP CRUD APIs. They can deliver a brilliant solution for large, highly distributed systems where there's a lot of unpredictability and where other styles would be challenged. They're a good fit when an API provider has little control over consumers and there's large amount of change in requirements over time. This isn't necessarily the case for everybody, so the complexity may not be worth for everybody."

Conclusion

Not all API architecture styles are created equal, and there may not be one style that fits your needs perfectly. Organizations will need to carefully evaluate the API styles described here and others (including those coming down the pike) to determine which best fits business needs. The choice may not be easy, but when it comes to the future of your business, one thing is for sure: Using what you’ve always used, (whether it’s an API style, a scripting language, a software program, or other technology) just because you’ve always used it, is a pretty sure path to stagnancy and perhaps even eventual failure.

Janet Wagner is a data journalist and full stack developer based in Toledo, Ohio. Her focus revolves around APIs, data visualization, machine learning, and data-driven journalism. Follow her on Twitter: @webcodepro, Google+, or send her an email.

Comments