I just came back from Apps World 2014, having attended most of the sessions on the API Strategies track among others.  Apps World covers a wide spectrum of technical topics from mobile front-end development using HTML5 to back-end API development and management.  Apps World also has a wide representation of consumer and enterprise mobile developers that highlights the variety of use cases faced by mobile applications.

Because of this breadth and range of coverage, I could talk about many things that I learned and observed.  This blog post captures some of my thoughts on a particular challenge in API development: the lack of standards for APIs and mobile both as a former practitioner and now as a vendor for API development.

Old Challenges: Lack of Conventions and Standards

In his presentation, Travis Broughton, an enterprise architect from Intel, showed how APIs have evolved.  He referred to the Gartner report that states “…75% of the Fortune 500 will have some form of API (either internal or external)“.  He also cited new-generation companies like Twitter, Twilio, DropBox, and Box whose entire product strategy centers around their APIs.  There’s no question that APIs have come a long way from being an afterthought to something important to (or at least on the radar of) corporate strategy.

No matter how much things change, some things glaringly stay the same.  From presentations I heard and audience question and answer sessions, there is STILL a jungle of lack of standards, DIY tools, and the technical debt of first generation APIs. Mobile apps are propelling the need for APIs and highlighting these challenges.

Practitioner Point of View

Has REST really won?  For external-facing web APIs it certainly has, at least on the surface.  However, the reality is that enterprises still have many legacy APIs with a mish-mash of SOAP and proprietary data formats over HTTP.  Even for companies that have some sort of REST API, there is little consistency among them because REST is not a standard, but rather an “architectural style.”  REST leaves itself open to wide interpretation and varying implementations because there is no official specification.

Here are examples of differing URI conventions with nouns, verbs, and operations as first-class citizen resources.

GET http://acme.com/api/catalog?method=getItemsById&sort=desc
 
GET http://acme.com/api/catalog/getItemsById?sort=desc

These two samples both conform to the REST style of retrieving a resource as an idempotent operation with HTTP GET, which is a great start.  (Remember the early days of faux-REST proprietary APIs over HTTP where you could actually do actions all through a simple GET? (tongue)).

The problem with the first example is the retrieval of the catalog items as a sub-resource and not just a reference from the catalog is mixed into the query string parameters for data retrieval.   Furthermore, it mixes in verbs into query string parameters where the HTTP noun should be used against a noun specified on the URL path itself.

The second example mixes in a specific operation as a first-class citizen resource as what would otherwise be “items” and again it mixes in verbs into the URL path.  While acceptable, this confusingly blurs the line between REST as a resource-based API versus a remote procedure based API.  The first rule of thumb to nouns over verbs with many resources over many operations has always been tricky.

GET http://acme.com/api/catalog/items?sort=-id
GET http://acme.com/api/catalog/items?sort={id:desc}

The sample above shows a couple of variants that might have been a better way to address retrieval of items from the catalog by ID in descending order.  The first calls out the sub-resource from the catalog explicitly.  Although the catalog may have more than one child resource, the granularity can be specified with the recursive convention /resource/sub-resource/….  The second entry refines the first entry to make arguments more extensible by encapsulating into JSON.  You can imagine adding more sort parameters by adding more to the JSON string, e.g. sort={id:desc, name:asc}.

Vendor Point of View

Vendors building products to support such a wide interpretation of what REST APIs should look like are faced with generalizing their solutions to meet all types of use cases.

When REST started to take hold, it was still a best practice to specify content-type for delivery to be flexible; for example, as shown below.

GET http://acme.com/api/catalog/items?format=json
GET http://acme.com/api/catalog/items?format=xml
OR
sending HTTP headers to set x-li-format=json/xml

This flexibility wasn’t just driven by external parties lagging behind on consumption but also because behind the scenes, the enterprise’s own infrastructure was still tied to old standards.  Part of the vendor’s burden was to support the legacy infrastructure for services driven by XML while surfacing a JSON representation that complied with RESTful standards.  This need to mediate on the fly between different content types is still a key delivery function for API gateways.  Again, a lack of standards for APIs means that the vendor needs to build a pluggable swiss-army-knife of mediation layers to transform and massage the final data output with things like built-in pagination (especially for mobile).  What if the legacy API wasn’t even structured as SOAP with at least a WSDL or schema?  Now the vendor would need to build functionality that enables you to map from the legacy data payload to some JSON representation expressed as a REST endpoint.

Solution

REST needs standardization to enable API developers to improve velocity and productivity.  This is particularly true when building a value-add solution that depends on multiple cloud-based services in conjunction with enterprise legacy services.  There have been failed attempts at standardization, such as re-purposing WSDL, Google’s partial attempt to gather some consensus around WADL, and newer specifications like swaggerGoogle API Discovery ServiceRAML, and so on.  Even with a standard, only the next generation of REST APIs will be able to take advantage of it.  As everyone knows, the scariest part of exposing an API is that it lives practically forever and supporting it can become burdensome.

StrongLoop provides a solution to the challenges due to lack of standards: open-source based solutions and tooling to surface modern APIs and contend with diverse legacy infrastructure.  Our vision goes beyond the browser, smartphone, and tablet to the world we’re evolving toward with machine-to-machine (M2M) and Internet of Things (IoT).   The heart of our solution is the LoopBack API framework built on top of Node.js.  Node has become the pre-eminent technology to glue toether existing data and services (in the enterprise datacenter and the cloud) and expose uniform APIs.

Use LoopBack to build APIs in Node.js

LoopBack is an open source framework for building APIs in Node. Install locally or on your favorite cloud, with a simple npm install.

LoopBack API Explorer

 

What’s next?

  • What’s in the upcoming Node v0.12 version? Big performance optimizations, read the blog by Ben Noordhuis to learn more.
  • Watch Bert Belder’s comprehensive video presentation on all the new upcoming features in v0.12
  • Need performance monitoring, profiling and cluster capabilites for your Node apps? Check out StrongOps! We’ve made it easy to get started with a simple npm install.