May 23rd, 2014

Mapping the API Landscape

Mapping the API LandscapeThis week, I had the opportunity to deliver a “lightning talk” at the APIStrat Tech Un-Workshop at Gluecon 2014. The event was focused on two key topics: IoT and service description/discovery. I was in the service track and delivered a talk called Mapping the API Landscape. I won’t cover the entire talk here (BTW, the text has lots of links to information I could not discuss on stage this week) but did want to hit some key points.

What Google’s Self-Driving Car Tells Us
The Google car has been in the news again and a key point that was discussed at some length in these articles was the fact that the car depends on a very detailed map of the roadways. Right now, the car can only drive in the Mountain View, CA area since that is the only landscape mapped well enough for the car to navigate.

So, the Google car does not “discover” anything while driving. It actually recognizes intersections, traffic lights, etc. through a special representation of the landscape that contains all the right annotations. This reliance on a known map allows the car to navigate successfully between two points within that landscape – which is no simple feat, of course. Reacting to surroundings “at speed” takes serious computing power and that’s one of the reasons the Google implementation is so amazing.

Norman’s Action Lifecycle
The process of navigating from A to B is a goal-driven process that we see very often in nature. Ants, micro-organisms etc. all do this. Human-computer interaction expert Donald Norman calls this process the “action lifecycle” or “seven stages of action”.

This is how we learned to write GUI interfaces, too. Wait for a keystroke or button-click, process that action, affect the UI, then allow the user to evaluate the changes and decide if another action is needed. We also build Web servers this way. Wait for a request, process it, modify the backend (if needed) and reflect results back to the requestor. Game programming works like this, as well. But it’s rare to see the Web and mobile client applications that leverage enterprise APIs written in this way. They continue to look like single-minded bots that just go from A to B and ignore landmarks, incapable of actually reacting to surroundings.

Client Apps & Web Maps
Why are most client apps one-off implementations that are likely to break over time? It’s because client developers don’t have decent “maps” of the online landscape. And good maps are not just “photos” of the surroundings but heavily-annotated representations with recognizable symbols and landmarks. Most servers today just belch out JSON or XML with almost no recognizable symbols or signage (e.g. hypermedia controls).

So, what we need to do is create maps for devs to use so that they can build their own client applications against our APIs and solve their own problems. Client apps should be free to follow whatever route they wish within the maps – they shouldn’t be limited to following the path that server developers decide upon.

Let’s Make Maps!
Things like service description formats and discovery protocols are all ways to start creating more maps for client devs to rely upon. Using hypermedia in responses provides the symbols and signs client apps can use at runtime (like the Google car) in order to navigate in real time.

There are several description formats (see my paper Hold Your Nose vs. Follow Your Nose for more on this). In the book RESTful Web APIs, Leonard Richardson and I list close to 20 options for expressing hypermedia in Web responses. And more have come online since the book was published last year.

We have all the tools we need. We just need to use those tools to make more maps!

April 24th, 2014

SDKs Work Until They Don’t

SDKs and APIsOver the last couple of months, I’ve had many great opportunities to road test my findings on SDKs vs. APIs, with a wide variety of audiences – at our API Academy Summits in New York and London, on tour with the Nordic APIs team in Stockholm and Copenhagen and at my most recent API Workshop in Istanbul. Given the apparent relevance of the topic and the lively discussions I’ve had around it, I’d like to take this opportunity to summarize some of the insights and recommendations that have come up.

If you’ve been following our blog, you will remember that I started this topic with the observation that leveraging an API increasingly seems to involve using an SDK rather than the API itself. I followed up with a post talking about my decidedly mixed experiences of trying to use SDKs. My own experiences inspired the headline of this post: SDKs work until they don’t.

So, what are the main motivations to invest in an SDK, from an API-provider perspective?

  • Simplifying API design by extracting business logic into the client
  • Maximizing scalability by exploiting client-side processing
  • Empowering developers to leverage the API more quickly
  • Presenting an optimized client from a target-platform perspective (e.g. for mobile connectivity or constrained hardware)
  • Providing a strongly-typed presentation of the API in a variety of programming languages

Let’s contrast all this with the main drawbacks of SDKs:

  • Picking which platforms, languages and frameworks to support – some of your target developers are going to end up disappointed
  • Relying on third-party frameworks – any developer who has to integrate with two or more APIs leveraging the same framework at different version levels is bound to experience some headaches, for example
  • Adding carry-on weight of unused functionality to the application
  • Incurring long-term support costs for the SDK

But to me, the biggest risk of a SDK-first approach lies in making API design an afterthought. We have come to this point in the API evolution because pragmatic REST introduces just enough constraints to force us to think about how we can abstract the underlying business asset into a resource-based model restricted to CRUD-style interactions. An SDK-first approach might tempt us to go back to a RPC-style API design mirroring the backend implementation, resulting in all the inherent integration complexities we had with Web services.

So, if and when you decide on a SDK, keep the above in mind. You might still come to the conclusion that you need an SDK in order to quickly onboard developers or provide the best client for your API but at least you will be able to consciously weigh the benefits against the drawbacks.

If you want to dig more deeply into the subject, I can highly recommend the following podcasts, articles and blog posts, which helped greatly in forming my own opinions:

April 3rd, 2014

Mobile Access Gateway 2.1 is Here!

Mobile Access GatewayLast week, we launched the Mobile Access Gateway 2.1 in style. The team has worked hard over the past few months to make sure the new features are coming together in a meaningful way. So, what’s in the new release?

First, we now allow customers to configure the usage of SiteMinder Session Cookies, with the Mobile SDK. In fact, the client libraries can use just about any token as the user token without breaking the existing model where we provision and manage token artifacts for users, apps and devices. With 2.1, you can use SiteMinder Session Cookies, SAML, JWT or any other user token. The Gateway administrator can configure what is relevant for the use case. As we know, there is a huge base of SiteMinder users who should now consider the Mobile Access Gateway as their mobility toolkit.

Second, the Mobile Access Gateway now supports social login for mobile apps. Social login support on the Gateway empowers developers to build apps that allow users to securely identify themselves by using sign-on credentials from social network platforms like Google Accounts, Salesforce, LinkedIn and Facebook. The social login flow is supported by the Gateway’s mobile Single Sign-On (SSO) capability. With mobile SSO and social login enabled, users login once with their social account credentials to access multiple enterprise and third-party applications from a mobile device. Additional contextual data such as geolocation can be combined with social login to provide a more secure API.

Third, with the 2.1 release, we now support Adobe PhoneGap. By leveraging the Cordova plugin interface, hybrid apps can tie in to the SSO and mutual SSL session negotiated by the native client libraries. This way, there is a unified security model for native and hybrid apps and app developers can choose to code application logic with their preferred tool chains.

Together with the existing Mobile Access Gateway features, this release provides app developers with better tools for writing awesome and secure mobile apps.

April 2nd, 2014

The Next Big Thing is Small

Written by
 

The Next Big Thing is SmallOne of the challenges facing the tech community is the addition of tens of billions of Internet-connected devices over the next few years. Currently, this Internet of Things (IoT) is expected to grow from 20 billion connected devices in 2015 to 40 billion in 2020.

That’s a Lot of Things
Estimates vary widely but most agree we have something less than 10 billion connected devices today including computers, handhelds, cars and controller devices such as SCADA and others. So, adding tens of billions more in just a few short years is definitely going to present some challenges.

A Lot of Little Things
And – if you start to think about wearables, RFID and micro/nano-size items, you realize that billions of these devices are going to be quite small. Not just physically but also in terms of capability and capacity. These devices will not have the power or flexibility of a laptop or even a handheld mobile phone.

These new members of the “connected community” will be tiny, single-purpose, low-power devices that do one thing and do it well. And it is likely that the program-ability of these devices will be limited. You might be able to flash the memory or even tweak configurations but a good number of these devices will not be hosts to custom code the way Web servers and handhelds are today.

Yet, we still need these devices to work together – even if only to publish device data, consume data from others devices and react to outside stimulus (lights on/off, heat, air movement etc.) So, how will we do that? How can we get things to interact with each other?

Step-by-Step Programming
Most developers today write “code” by stringing long lists of imperative statements together into a coherent set of instructions for machines. To most developers “programming” is just that – providing step-by-step instructions. This means we take on responsibility for any mishaps along the way, whether they occur due to problems inherent in the instruction set or due to unexpected events outside the instruction set, such as other devices not responding to our requests or sending us unexpected data. Doing this on tiny devices with limited capacity and ability is going to be a problem.

Luckily, there is another way to “program” these devices.

Rules, Not Code
We can also use a rule-based approach to programming. In this paradigm, programmers establish a set of coherent rules that tell the device how to respond to outside stimulus (“if the lights are on do X else do Y” or “if the motion detector reports true then turn on the light” etc.) And that is all you do; you write simple rules and leave the device to its own…. well, devices.

This means “programs” are much smaller (just a set of rules), easier to debug and easier to safely modify. It also means the devices themselves don’t need to do a great deal of work in order to “act” according to the rules.

That’s what I mean by small. The code will be small; the code will be rules.

How Does That Help Us with IoT?
It seems unlikely that we’ll be able to “program” billions of devices to safely and successfully interact with each other if we have to constantly provide step-by-step instructions on how each one operates and how they all interoperate. Instead, we’ll rely on simple devices each of which does one thing well and makes its action history available (as a stream of data, occasional dumps etc.) to other authorized devices.

It is also important to keep in mind that these devices will not be “phoning home” asking servers for guidance on how to proceed. The amount of traffic that tens of billions of new devices might generate if they need to constantly get instructions from distant servers would be massive and a huge waste of time and bandwidth. Instead, most IoT devices will act on their own, making decisions in real time, using the rules provided to them.

So, This is a Big Deal, Right?
This way of thinking about how devices will work and how we will “program” them is a big change for many developers. But not all of them: There are people today who build “low-level” device handlers and other things that do pretty much what I describe here. Motion detectors, security systems etc. all operate on this model (simple rules executed in real time). The difference we’ll see in the near future is that more of us will need to start designing and coding for devices that use this rule-based model.

But yes, this is a big deal.

By the way, I see quite a number of people building “Internet of Things” apps and models still assuming that the devices will be high-powered, fully-programmable computers similar to today’s handhelds and laptops. This is a mistake. While there may be some IoT devices with that profile, I suspect it will be a very small minority of the projected 40 billion devices.

So, start thinking ahead. Start planning for a new way to program devices. Those who start working like this now will have a jump on their peers and competitors. And there is good reason to start contemplating this right away. Rule-based systems will require different training and even different tooling. Think about how this will affect the “test-driven development” movement and related practices. And that’s just one example.

Are There Examples of This “New” Kind of Programming?
Yes, there are. And I’ll pick up that thread in a future post.

(This post, which was originally published on my personal blog, covers material from my recent talk at the API Strategy Conference in Amsterdam. You can see the notes from my talk online, along with the slides and related videos.)

March 27th, 2014

SDK vs API – Round 2

SDK vs APIInspired by a conversation with Kin Lane and Mike Amundsen at last year’s APIdays conference in Paris, I decided to dig deeper into the SDK-vs-API debate.

As I wrote in my last post, I had noticed a pattern of using API SDKs rather than the underlying Web APIs. Let’s quickly define what I mean by SDK. There used to be a time, not so long ago, when “SDK” meant documentation, code samples, build scripts and libraries all bundled together. Today, you find all the former on the Web and usually only the library remains. When I use the term SDK, I mean a programmatic API (e.g. JS, Ruby, PHP, Python) on top of the Web API (usually REST/JSON).

As it happens, my wife gave me a small wearable activity monitor as a Christmas present (I could not possibly think of any reason why I would need that – and the new weight scale in the bathroom must have been pure coincidence). Since the gadget was uploading my stats to a cloud service and this cloud service had an API and my wife gave it to me as a present, I figured I had a perfect excuse to do some coding. My goal was to write a client-side app using JavaScript, pulling my stats from the cloud service via the API (and to keep notes on my experiences).

After registering at the developer portal, I hit my first stumbling block – no client-side JavaScript SDK. The closest I could find was a PHP SDK – which, of course, meant that I had to install PHP (I had not used PHP before) and the framework(s) used by the SDK. I also had to enable a Web server and debug the SDK’s OAuth implementation. That was not quite what I had in mind. Even though I got it running after one day and a half, I ended up being quite frustrated. All that work for a simple Web page displaying the stats for a hardcoded day!

So, I decided to take a different approach and use the SDK provided by Temboo. Again, no client-side Javascript SDK. While I could have used a Node.js SDK instead, I decided to stick with my PHP install and opted for the PHP SDK. From there, the integration was quick and I was up and running within an hour. What I did not like about the SDK was the footprint (it included all possible integrations) and how its abstraction and data presentation leaked into my application code. If I were to build a commercial product using it, I would have to consider the potential stickiness of the SDK. Personally, this did not feel right either. So, I went back to the drawing board and looked at my options.

What had I learned so far? My frame of reference going into the experiment was a client-side app using JavaScript. Yet the only SDKs I had found were written for server-side integration. Since it was the only choice offered to me, I had to invest a significant amount of time finding all the necessary information to get the server-side components and dependencies installed and configured. But even after going through all of this, the experience with either form of SDK left something to be desired.

I had started this exercise thinking that using an SDK was much easier than coding against the Web API – maybe it was time to reassess that assumption.

Looking back at the API documentation, I could not find anything inherently difficult. Looking at the vendor-provided PHP SDK, it dawned on me that the complexity of the client was entirely due to OAuth and the use of XML as payload. This finally gave me the opening I had been looking for. If I could avoid the complexities of OAuth on the client and use JSON as the payload format, I should be able to implement my client-side app with a few lines of JavaScript against the Web API. As a regular guest at Webshell‘s APIdays conference, I was familiar with the company’s OAuth Broker service. It took me a few minutes to get set up, configure the service and download their oauth.js client library. I cut and pasted the sample code into a JavaScript file, consulted the API docs to learn about switching to JSON format and did the API call. I was done in less than five lines of code!

While this experiment is just a single data point, I think it nicely illustrates some of the key lessons in the SDK-vs-API debate. I will attempt to provide a summary from both the API consumer and the API provider perspectives in my next post. I will also be talking about the SDK-vs-API issue in more detail during the upcoming Nordic APIs tour in Stockholm and Copenhagen and at the APIdays conference in Berlin.