Sometimes design concepts are obvious. We know they are implicitly understood and don’t require drawn-out explanations. But sometimes these implicitly-understood concepts aren’t executed in real life because they haven’t been explicitly defined. I’ve come to the realization that designing APIs with the developer in mind is one of those ideas that often has an audience nodding their heads but which only a few take to heart and apply to their API architectures.

We in the API design world have a great opportunity to learn from our brethren in the product design world. The user-centered design approach for products has paid great dividends for those who can understand and apply the idea to their interfaces. The goal is almost stupid in simplicity – design products that your users will enjoy. But, as always, the challenge is in translating a simple concept into real strategies, methodologies and practices that do not lose that fundamental goal while staying applicable to unique marketplaces.

In our world of API design, most of us understand that machine-to-machine integration still involves a human – the developer who develops the client code. That developer – the one who makes or breaks us by deciding to use an API – is our user. While product designers talk about improving user experience, we talk about improving the developer experience.

But how does this actually happen? What do we specifically need to do in order to create APIs that are enjoyable to use? Indeed, what does enjoyable even mean in this context? This developer/API publisher relationship is a unique one and the product-based, user-centered design and human/computer interaction models cannot just be airlifted in. They need to be massaged and transformed so they are applicable to the Web API world, without losing the potential value inherent in a user-focused design.

I hope to explore these ideas over the coming months and come up with recommendations for how we can build API solutions that deliver on the promise of improved developer experience (or DX). I’ll dive deeper into the world of user-centered design and discuss methods for translating these concepts from the world of product design into our API design domain.

I had a great time presenting on API design and management trends at our London API Workshop a few weeks back. James Governor from RedMonk delivered an exciting talk on APIs, the need for API Management and some stark truths, like the fact that Java is still at the top of the programming pile. All of the trend talk and analysis was followed by a great real-world example when MoneySupermarket.com’s Cornelius Burger described his organization’s journey implementing the MoneySupermarket API with a SecureSpan API Proxy. We had excellent feedback on the event, so I know I wasn’t the only one who learned a lot from our speakers.

I was particularly impressed by the range of industries and organizations that were represented in the audience. We had developers from large enterprise shops, specialized Internet-focused start-ups and even a few entrepreneurs just getting started. I think this range of interest is indicative of the value of Web APIs for all and bodes well for a continued investment in designing great APIs, rather than just chucking them out into the ether.

Next up on the tour is our Paris API Workshop taking place tomorrow (Tuesday, October 16).  As always, we have a great set of speakers lined up, with Martin Duval from bluenove talking about building developer outreach programs and Benoit Herard from Orange Labs discussing their API launch. France has a  great start-up culture and a reputation for enterprises like Orange driving innovation, so I’m expecting good conversation, some excellent API Management presentations and – if I’m lucky – some great wines.

I had the great fortune of spending last week in India, helping a Layer 7 customer develop a Web API program from scratch. While it’s always exciting to walk into a greenfield situation and build something new, I was doubly excited to be doing this in India, where the concept of open APIs is still fairly new.

Over the last few years, we’ve seen explosive growth in open APIs across North America, lead of course by the avant garde Internet companies on the West Coast. The API Management industry has focused much of its attention on the US market but the Web API movement has definitely made its way to other markets and the push towards mobile and device-based applications is clearly having an influence on enterprise architectures.

Western Europe has had a strong influence on the API scene, with notable government and enterprise organizations diving wholeheartedly into the collaborative, developer-focused open API space. London, in particular, has developed a thriving technology scene with tons of hackathons, codeathons, meetups and start-up companies trying to change the world or at least get rich trying.

At the moment, the open API scene in India is still in its infancy and I’m looking forward to helping the concept blossom in whatever way that I can. As you may be aware, the number of mobile devices being used in India is mind-boggling and the ratio of mobile-use-to-desktop-computing is much higher than in North America or Western Europe.  This quantity of mobile client platforms, combined with the large number of motivated developers on the scene, makes this a very intriguing open API marketplace. I can’t disclose any details on the nature of the project yet… but I’m hoping to to have exciting news to share in the near future, so stay tuned.

I’ve spent most of the summer in North America, for a variety of reasons and I’m excited that I will finally be getting back home to the UK so I can re-engage with the European API and mobile scene. We have some great Layer 7 API workshops scheduled across Europe over the next few months and hopefully we will uncover a few new and noteworthy European API publishers while we are on tour.

As the leader of Layer 7’s North American API Architecture & Design Practice, I often get asked to review Web solutions. Rarely do people ask me if the implementation is appropriate for the intended use. Instead they want to know if the work fits a label invented over a decade ago by a PhD candidate in his dissertation. They want to know if what they’ve come up with is “RESTful”.

Essentially, REST (representational state transfer) is a style. Specifically, it’s a style of network-based software architecture. This style was first defined in 2000 by Roy Fielding. Fielding stated that “an architectural style is a coordinated set of architectural constraints that has been given a name for ease of reference”.

The set of architectural constraints Fielding defined in his dissertation remain the key criteria by which we judge whether or not a service is RESTful. Back in 2000, Fielding did a very good job of defining the six primary constraints: client-server; stateless; cache; uniform interface; layered system; code-on-demand.

However, REST is also defined by four “interface constraints” that are only partially defined in the dissertation: identification of resources; manipulation of resources through representations; self-descriptive messages; hypermedia as the engine of application state. In particular, the definitions of self-descriptive messages and hypermedia are still debated.

Assuming you can decide on clear definitions of all 10 constraints, all that remains is to identify each of them within the target design. If the implementation does not exhibit all ten (well nine, since code-on-demand is optional), then it is not RESTful. This last step is not difficult. It is the previous step (agreeing on definitions) that causes problems.

Still not sure if your service is RESTful? Well, I originally published this post, in expanded form, on my personal blog. If you want to dig deeper, take a look over there.

In the previous blog post in this series (Using WebSockets – Part 1: Minding the Gates), Ronnie Mitra talked about the promise of the WebSocket protocol, as well as some security aspects. In this post, I’ll talk about some of the details of the protocol and what they mean for those planning their own WS implementations.

The first thing to keep in mind is that WebSocket is a high-level protocol with its own registered schemes (WS: and WSS:). The specification describes it as: “… intended to be as close to just exposing raw TCP to script as possible.” This is very different from HTTP, which is “…  an application-level protocol for distributed, collaborative, hypermedia information systems.”

That’s good and bad news. It means you have almost the full range of TCP at your disposal. It also means you have none of the established constraints and conventions of the more detailed and focused HTTP specification. This has implications for both design and implementation of WS solutions.

Originally designed with Web browsers in mind, the WS protocol can also be implemented for mobile, desktop, and other stand-alone clients. There are quite a few checks and balances in the specification in order to make it easy (and safe) for browsers to switch from HTTP to WS conversations, all from JavaScript.

However, since many installed browsers do not yet natively support the WS protocol, these checks and balances are not always employed. Instead, WebSockets implementations often take advantage of browser workarounds and fallbacks, in order to support the real-time communications the WS protocol was designed to provide.

It’s also important to remember the specification states: “While this protocol is intended to be used by scripts in web pages, it can also be used directly by hosts [which] can therefore send fake ‘Origin’ header fields, misleading the server.” Implementations that will receive requests from non-browser clients should include additional checks to ensure these requests are valid.

Finally, as the protocol was designed to support real-time communications, it won’t scale in the same way HTTP does. Since the server will keep connections open to all active clients in order to track and broadcast content, servers will need to maintain (or persist) information about each connected client (including knowing when that client is no longer connected!)

If your current HTTP implementations rely on server-based session state, you may not see much difference in the scaling limits of WS. Remember though, the Web’s scaling success is largely based on HTTP’s ability to handle client requests without requiring server-persisted data. Also, some software and implementation patterns designed for HTTP will not work for WS.

Implementing WS is not for the faint-of-heart: it’s not yet widely supported on installed browsers; it uses a different implementation model; it takes more effort/resources to scale it up as services become popular. However, there are some good libraries for coding WS solutions and it can be relatively easy to get started on implementing WebSockets.

But be ready. If you experience great success, you’re likely to have a challenge on your hands!