mca blog

i keep writing posts on web apis, media-types, RESTful APIs, not-so-RESTful APIs, XHTML-based APIs, JSON-based APIs, Web SDKs, URI Conventions, and now this one on protocol binding.

application code bindings

when dealing with application code, it's common to distribute "language bindings" for others to use. it's a way of sharing the API w/ a wide range of programming communities. for example, the very handy libcURL utility publishes it's own bindings for about forty different programming environments.

in the case of application code bindings, it's important for the publishers to keep the bindings fresh and for consumers (developers) to continually check for updates, integrate any new bindings into their own code and re-distribute the updated application that includes the result of the new bindings.

media-type protocol bindings

in the world of distributed computing a media-type is a rough analogy to the code libraries. authors want their APIs to be used by lots of folks and the media-type is the expression of that API. typically, media-types are designed with a particular protocol in mind; you could say they are bound to that protocol. usually that protocol is HTTP since it's the one API designers think of when working on the Web.

but there are lots of application-level protocols that work on the Web. and some of them are fine candidates for use w/ Web media-types; esp. ones that exhibit one or more of the H-Factors that make up hypermedia types. and the way you can leverage these other application-level protocols (FTP, Atom, WebDAV, SMTP, etc.) is to publish protocol bindings for your media-type API.

sample protocol bindings

if your web API design follows RESTful principles, you've been careful not to include URI convention instructions, but instead use link relation values and other semantic rules to tell developers how to describe and execute the available read and write semantics in your media-type. you can include sample protocol bindings in your media-type documentation. in a recent blog post, i show how this can be done for a list management sample showing both HTTP and FTP bindings for the media type API.

non-HTTP protocol bindings

there are other ways in which you can leverage application protocols for your media-type. in fact, you may be doing that already without thinking about it.

• you might have an API that allows clients to request large files for download. instead of returning a representation that has a download link that looks like this: <a href="http://www.example.org/files/q1w23e4r.zip" rel="download" />, you might use an FTP binding instead: <a href="ftp://ftp.example.org/files/q1w23e4r.zip" rel="download" />.
• it might make sense for your application to use email to send new data to the server. lots of microblogging services provide an SMTP binding for their services.
• or you might need a very specific set of network commands - your own protocol. in many cases, you can use BEEP to design your protocol and then document the new bindings for your media type read/write semantics.

bottom line

the key point here is that, just as it makes sense to publish multiple code bindings for application APIs, there are advantages to designing your media-type in a way that allows developers to use multiple protocol bindings to fit their network environments and specific needs. it is also a good way to ensure your media-type API/service can grow and adapt to changing protocols over time.