"I have just met you and I love you"
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.
"Squirrel!"
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...