it's official! i've signed an agreement w/ O'Reilly Media to write a book focused on creating hypermedia clients. i've been putting this project off for a couple years and am glad i finally will be sitting down to cull through the collected material and work to put it into a (hopefully) useful presentation.

i've spent several weeks coding up lots of examples of hypermedia clients; experimenting with several existing media types and even some profiles. i've also been working through common patterns that make working w/ message-oriented services easier to handle for client apps. i have learned quite a bit over the last couple years of talking w/ people and assisting on various projects both large and small. and now it's time to see if i can find a coherent story in all that experience.

TBH, i'm not exactly sure where this one will lead, but i have a decent plan to follow before i start out toward the horizon. i won't belabor the details here but will pass along my general outline to give folks a feel for where i am trying to go...

Part 1 : Human-Driven Hypermedia Clients

i'll be keeping discussions of human-driven and (i'll say) machine-driven clients clearly separated in the book. not because there is always a clear line between then in real life (think parsers designed to prefetch content based on inline instructions, etc.) but because it makes the conversation a bit easier.

that said, the first part of the book will focus on the process of traveling from a client application that doesn't rely on any hypermedia, through several stages that end with a client that relies primarily on hypermedia information in responses. again, IRL there is a wide range of hypermedia in client apps for the Web (images anyone?) but this kind of approach will, i think, help bring some things into focus.

Part 2: Machine-Driven Hypermedia Clients

ahh, the fun stuff! the holy grail, the unicorn of song and story!

or not.

similar to part 1, i'll use the second half of the book to focus only on challenges related to creating hypermedia clients that don't rely directly on human intervention for each request. of course, humans will program them, but then -- at least for some level of interaction -- leave the machine to do their own thing. and that's where it gets fun.

i'll talk about how we can build a client that has the power to do basic interaction (independent request/response), how machines can be "taught" to safely navigate a selected part of the WWW environment, how they can recognize 'things' (affordances) along the way, and how to use those things as tools to manipulate the local environment. finally, i'll talk about how a client can be taught to recognize a 'goal' or 'end-state.'

in real life, humans do this kind of stuff every day. we navigate through traffic, recognize road signs/signals and are able to figure out when we reach our destination -- even if it is not the destination we had in mind at the start of our journey ("Sorry mate, the pub is closed. But the one up the road is still open."). we also go through these kind of scenarios in a more abstract or indirect way, such as when deciding we're done exercising, had enough to eat, or have collected enough trading cards to make a complete set.

it turns out, none of the cases i mentioned above require much "intelligence" or "reasoning." just the ability to pay attention to details and identify "done." and there are very many instances where this level of execution would be useful over the Web today. unfortunately, even these simple kinds of machine execution are not often supported when implementing services for the Web -- and that's a bummer.

but they could be. and that's cool.

On the Road Again

so, the next few months should be quite interesting. i always enjoy starting out on one of these adventures and this time is no different. i should also confess that i really enjoy getting to the end of a book project and putting the thing behind me ;) and i suspect that will be the true this time, too.

an added wrinkle is that i start traveling again in february and that usually takes a toll on deadlines. for that reason, i'll be drawing this project out a bit more. i hope to have the first draft completed by early summer and have it all wrapped up and out the door by fall 2015.

so, here i go, getting ready to navigate toward the horizon and hopefully recognizing when i get to "done."

should be exciting.

oops! road sign up ahead. gotta turn here. L8TR!

Comments   Hypermedia

yep - it's official! i'll be traveling the Pacific in late October and early November to present the CA API Academy sessions on "How to Implement a Successful API Strategy." along the way, i'll be visiting the following cities:

Rewriting Everything

i'm really excited about this trip because this time i am re-writing all my presentation content for the API Strategy Workshops. Instead of just collecting up the most popular content from our very successful API training program, this time i am pulling together content from each of our incredibly talented API Academy team members and highlighting the key insights each of them have on the major topics we're often asked when working with our customers.

preparing this content is a real thrill for me because it's a chance to show people examples from the wide range of expertise and experience in the API Academy. it's also a bit duanting since i need to try to get up to speed on all the things our Academy folks have been working on in the last year.

here's what i have planned for the upcoming workshops

Apps, APIs and the Enterprise: Enabling The Future of the Web

The growing explosion of mobile devices on the Web means applications will continue to become smaller and more numerous, deployment cycles will keep getting shorter, and the speed of innovation will increase. At the same time, product teams are getting smaller and more distributed making project management more challenging than ever. Succeeding in this constantly evolving environment requires more than speed, it takes agility, planning, leadership and the ability to act quickly and decisively.

Join me for a half-day workshop where we explore:

Rewriting Business
Refocusing your Business through Apps and the API Economy
Rewriting Software
Harnessing the Power of the Cloud and Mobile
Rewriting Process
Using DevOps to transform your Infrastructure
Rewriting the Future
Rethinking Governance and Reducing the Cost of Change

Join Me!

it's going to be a great experience and i hope you will join me as we review key business, software, process, and governance issues facing IT departments today and into the future.

See you on the road!

Comments   CA

mapping the api landscape

2014-05-21 @ 15:22#

this 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 and Discovery. i was in the Service Description/Discovery track and delivered a talk called "Mapping the API Landscape" (slides). i won't cover the entire talk here (the text BTW 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 "gCar" has been in the news again and a key point that was disussed at some length in these articles was the fact that the car depends on a very detailed map of the roadways. in fact, the car currently can only drive in the Mountain View, CA area since that is the only landscape that is mapped well enough for the car to navigate.

so, the Google car does not "discover" anything while drivig. 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. this is no simple feat, of course. reacting to surroundings "at speed" takes serious computing power and that's one of the things that makes the Google implementation 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. HCI expert, Donald Norman calls this process the Action Lifecycle or Seven Stages of Action .

this is how we learned to write GUI intefaces, 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 build Web servers like this, too. wait for a request, process it, modify the back-end (if needed) and reflect results back to the requestor. game programming works like this, too. but it's rare to see "Web Clients" written 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 and web maps

why are most web client apps "one-off" implementations that are likely to break over time? because client dev's don't have decent "maps" of the Web 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, etc.).

so what we need to do is create maps for devs to use so that they can build their own client applications and solve their own problems. client apps should be free to follow whatever route within that map that they wish -- not just follow 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 realtime.

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 we need. we just need to make more maps!

Comments   API

i had the honor to speak at WSREST 2014 this past week in Seoul. This workshop was part of the WWW2014 and there were several good papers presented and a fantastic keynote by Google's Sam Goto.

the full script and notes from my talk as well as the slides are available online. what i want to do in this blog post is focus on a key message from the talk. a good place to start is to watch this 45 second video clip from Disney's movie "UP."

"I have just met you and I love you."

in the clip, Dug is very happy to "meet" new visitors. lucky for this unusual dog, he can communicate with new visitors, too. that's because both parties share an understanding on how to communicate before they have even met the first time. that's how the Web was designed: to allow people who have not yet met to communicate their ideas and create links between each other. that's very powerful. it takes advantage of what is now known as the Power Law in linked systems.

another important feature of the Web is to allow machines to talk with each other before they have ever met. with my browser, i can follow links to other servers and, even though my browser has not ever "met" that server, my browser knows how to "talk" to that server. servers are not "islands" of information, they are part of a Web.

your API does not love me

sadly, the way most of us implement HTTP APIs does not support this fundamental aspect of the Web. instead, each API has it's own "language" and the only way to understand that language is to first read a great deal of human-readable documentation and then build a special client application for just that one single server. this means every API service is a "lonely island" that no one understands upon first meeting. a very sad thing, IMO.


another great thing about Dug the dog is that he is ready and willing to follow unexpected things he discovers. if he "sees" a squirrel, he is apt to simply stop what he is doing and go over the find out what is going on. Dug is ready for new experiences.

again, this is an important aspect of the Web. we can follow new links to new places and learn new things. Stu Charlton explains this important feature of Web-based interfaces using the phrase serendipitous reuse.

these are not the links you are looking for

but most Web APIs today want us to ignore new links. they lead developers to design purpose-build applications just for the links within a single service. they don't allow client applications to easily discover and use new links. often even adding links within the service (e.g. a new feature) results in a "new API" through the use of a versioning pattern. clients are told to ignore new things and that is not at all like the Web.

i want to love your API

we need to change the way we design and implement APIs on the Web. we need to get back to the fundamental features that make the Web so powerful. we need more "love" and more "squirrels."

describe the interface, not the service

one of the first things we can do is to start describing Web APIs as "abstract classes" with only an interface that explains what is possible. right now we use decription languages that provide all the implementation details for a single server. in OO-speak, we describe server instances. this leads to building those purpose-built clients i mentioned above.

instead, we could describe interfaces alone. the interface becomes the shared understanding. and we can do it in a way that others (both server and clients) can implement in a shared way. one possible solution for this is a format i am working on with Leonard Richardson and Mark Foster called ALPS. ALPS is meant to provide this "abstract class"-style description of web APIs. there are other possible ways to do this, too.

use hypermedia formats

another important way we can all help each other is to rely more on hypermedia formats like AtomPub HAL, Collection+JSON, Siren, UBER and others when implementing our APIs for the web. using these formats for APIs it the equivalent of using HTML for Web pages. they all offer a high degree of shared understanding "before we have even met" and that can increase the linking value of all APIs. using shared hypermedia formats makes is possible for a single client application to "talk" to multiple services without the need for special coding.

and that's what we all want, right? to increase shared understanding and to make it possible for both people and machines to say...

"I have just met you and I love you."

Comments   API

API Academy goes to Asia

2014-04-03 @ 16:48#

starting april 4th, i'll be on the road for close to two weeks. along the way i have the honor of bringing the API Academy message of developer-focused, enterprise-scale API design and implementation to the cites of Seoul, Tokyo, and Singapore. in each of these cities we'll be hosting a free 1/2 day seminar covering some of the most popular topics the API Academy offers in our private onsite training to companies the world over.

i will also have the chance to do some additional presentations and make new connections while on this trip. as much as i enjoy the workshops, it is the chance to connect with those i've only known online and to meet new people that really makes these trips a great experience.

WWW2014 in Seoul

while in Seoul, i have the honor of presenting a peer-reviewed paper to the WS-REST 2014 Workshop which is part of the World Wide Web Conference in Seoul. it is not often that i get the oppty to speak at events of this calibre and i am also looking forward to catching up with several people who work on W3C projects; people i rarely get to meet in person.

there will also be an informal meetup in Seoul on the evening of April 8th near the COEX complex where the WWW2014 event is held and not far from the API Academy public workshop on the 9th. i don't have all the details and promise to post them as soon as i have them.

RESTful Web APIs in Tokyo

i am very excited to announce that i will be attending a RESTful Meetup in Tokyo the evening of April 12th. this was organized, in part, by a group of people who have also been hosting a bi-weekly reading group for the book RESTful Web APIs.

this group popped up last year to allow people to come together and translate the English-language edition of "RESTful Web APIs" in 'real time' by taking turns reading the content and then discussing it as a group. Leonard Richardson and i are very grateful for this kind of enthusiasm and i am looking forward to meeting some of the people behind this col project.


i arrive in Singapore on monday, april 14th and don't have any additional meetups scheduled yet. if you're in Singapore and want to set up something, ping me and let's see if we can get something going while i am in town for the public workshop on the 15th.

ok, let's go!

the chance to visit customers, developers, and designers in Seoul, Tokyo, and Singapore really has me energized. if you've not yet signed up for one of the public workshops, please do. and come up and tell me 'hello.' i'd love to hear about what your working on and how the API Academy can learn from your experience and help you reach your goals for building great applications for the Web and the enterprtise.

Comments   Layer7