mca bloghttp://www.amundsen.com/blog/making progressSat, 20 Dec 2014 13:14:02 GMTen-us1802014 Fall API Academy Pacific Tourhttp://www.amundsen.com/blog/archives/1156http://www.amundsen.com/blog/archives/1156Fri, 17 Oct 2014 14:07:00 GMT<p> <a href="http://upload.wikimedia.org/wikipedia/commons/6/60/Come_fly_with_me_%28467766536%29.jpg" title="luggage tags"> <img src="http://upload.wikimedia.org/wikipedia/commons/6/60/Come_fly_with_me_%28467766536%29.jpg" width="150" align="right" class="inline"/> </a> yep - it's official! i'll be traveling the Pacific in late October and early November to present the <a href="http://www.apiacademy.co/" title="API Academy">CA API Academy</a> sessions on "How to Implement a Successful API Strategy." along the way, i'll be visiting the following cities: </p> <ul> <li> <a href="http://transform.ca.com/412761-au-API-Academy-Melbourne.html" title="Melbourne">Melbourne</a> (Oct-29) </li> <li> <a href="http://transform.ca.com/436755-au-API-Academy-Sydney.html " title="Sydney">Sydney</a> (Oct-30) </li> <li> <a href="http://g.mamund.com/tuznl" title="Hong Kong">Hong Kong</a> (Nov-04) </li> <li> <a href="http://transform.ca.com/432138-jp-SEC-API-Academy-Tokyo.html" title="Tokyo">Tokyo</a> (Nov-05) </li> </ul> <h4>Rewriting Everything</h4> <p> 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 <a href="http://www.apiacademy.co/services" title="API Academy Services">API training program</a>, this time i am pulling together content from each of our incredibly talented <a href="http://www.apiacademy.co/team" title="API Academy Team">API Academy team members</a> and highlighting the key insights each of them have on the major topics we're often asked when working with our customers. </p> <p> 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. </p> <p>here's what i have planned for the upcoming workshops</p> <h4>Apps, APIs and the Enterprise: Enabling The Future of the Web </h4> <p> The growing explosion of <b>mobile devices</b> on the Web means <b>applications</b> will continue to become smaller and more numerous, <b>deployment</b> cycles will keep getting shorter, and the speed of <b>innovation</b> will increase. At the same time, <b>product teams</b> are getting smaller and more distributed making <b>project management</b> more challenging than ever. Succeeding in this constantly evolving environment requires more than speed, it takes <b>agility</b>, <b>planning</b>, <b>leadership</b> and the ability to act quickly and decisively. </p> <p> Join me for a half-day workshop where we explore: </p> <dl> <dt>Rewriting Business</dt> <dd>Refocusing your Business through Apps and the API Economy</dd> <dt>Rewriting Software</dt> <dd>Harnessing the Power of the Cloud and Mobile</dd> <dt>Rewriting Process</dt> <dd>Using DevOps to transform your Infrastructure</dd> <dt>Rewriting the Future</dt> <dd>Rethinking Governance and Reducing the Cost of Change</dd> </dl> <h4>Join Me!</h4> <p> it's going to be a great experience and i hope you will <a href="http://www.apiacademy.co/events" title="API Academy Events">join me</a> as we review key business, software, process, and governance issues facing IT departments today and into the future. </p> <b><i>See you on the road!</i></b>mapping the api landscapehttp://www.amundsen.com/blog/archives/1155http://www.amundsen.com/blog/archives/1155Wed, 21 May 2014 15:22:00 GMT<p> <a href="http://g.mamund.com/gluecon2014-talk" title="Mapping the API Landscape"> <img src="https://pbs.twimg.com/media/BoGWUS6IcAIKan6.png:large" width="150" class="inline" align="right" /> </a> this week i had the opportunity to deliver a "lightning talk" at the <a href="http://apistrategyconference.com/2014Gluecon/" title=""> APIStrat Tech Un-Workshop </a> at <a href="http://www.gluecon.com/2014/" title=""> Gluecon 2014 </a>. 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 "<a href="http://g.mamund.com/gluecon2014-talk">Mapping the API Landscape</a>" (<a href="http://g.mamund.com/gluecon2014-slides">slides</a>). 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. </p> <h4>what Google's self-driving car tells us</h4> <p> the "gCar" has been in <a href="http://www.cnet.com/news/googles-self-driving-car-turns-out-to-be-a-very-smart-ride/"> the news again </a> 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. </p> <p> so, the Google car does not "discover" anything while drivig. it actually <i>recognizes</i> 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. </p> <h4>Norman's Action Lifecycle</h4> <p> 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. <a href="http://en.wikipedia.org/wiki/Human%E2%80%93computer_interaction">HCI</a> expert, <a href="https://twitter.com/jnd1er" title="@jnd1er">Donald Norman</a> calls this process the Action Lifecycle or <a href="http://en.wikipedia.org/wiki/Seven_stages_of_action"> Seven Stages of Action </a>. </p> <p> 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. </p> <h4>client apps and web maps</h4> <p> 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.). </p> <p> 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. </p> <h4>let's make maps!</h4> <p> 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. </p> <p> there are several description formats (see my paper <a href="http://ws-rest.org/2014/sites/default/files/wsrest2014_submission_12.pdf"> Hold your Nose vs. Follow your Nose </a> for more on this). in the book, <a href="http://restfulwebapis.com">RESTful Web APIs</a> <a href="http://twitter.com/leonardr" title="@leonardr">Leonard Richardson</a> and i <a href="http://my.safaribooksonline.com/book/web-development/9781449359713/10dot-the-hypermedia-zoo/ch10_html"> list close to 20 </a> options for expressing hypermedia in Web responses. and more have come online since the book was published last year. </p> <p> we have all we need. we just need to make more maps! </p>"I have just met you and I love you"http://www.amundsen.com/blog/archives/1154http://www.amundsen.com/blog/archives/1154Sat, 12 Apr 2014 21:44:00 GMT<p> <a href="https://www.facebook.com/pages/Dug-Pixar-Up-Character/56166874070" title="Dug - Pixar Up Character"> <img src="https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn1/t5/41594_56166874070_6603_n.jpg" align="right" class="inline" width="150"/> </a> i had the honor to speak at <a href="http://ws-rest.org/2014/" title="Fifth International Workshop on Web APIs and RESTful Design at WWW2014, 7 April 2014, Seoul, Korea">WSREST 2014</a> this past week in Seoul. This workshop was part of the <a href="http://www2014.kr/" title="23rd International World Wide Web Conference">WWW2014</a> and there were several <a href="http://ws-rest.org/2014/accepted-papers" title="WSREST 2014 - Accepted papers">good papers</a> presented and a fantastic keynote by Google's <a href="https://plus.google.com/+SamuelGoto/posts" title="Works at Google!">Sam Goto</a>. </p> <p> the <a href="http://g.mamund.com/follow-v-hold" title="Follow Your Nose or Hold Your Nose?">full script</a> 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 "<a href="http://en.wikipedia.org/wiki/Up_(2009_film)" title="Up (2009 film)">UP</a>." </p> <iframe width="560" height="315" src="http://www.youtube.com/embed/FRJyieYGEI0" frameborder="0" allowfullscreen="true"></iframe> <h4>"I have just met you and I love you."</h4> <p> 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 <a href="http://en.wikipedia.org/wiki/Power_law" title="Power law">Power Law</a> in linked systems. </p> <p> another important feature of the Web is to allow <i>machines</i> 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 <i>Web</i>. </p> <h4>your API does not love me</h4> <p> 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 <i>first</i> read a great deal of human-readable documentation and <i>then</i> 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. </p> <h4>"Squirrel!"</h4> <p> 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. </p> <p> again, this is an important aspect of the Web. we can follow new links to new places and learn new things. <a href="https://twitter.com/svrc" title="@svc">Stu Charlton</a> explains this important feature of Web-based interfaces using the phrase <a href="http://www.stucharlton.com/blog/archives/000165.html" title="Planned vs. Seredipitous Reuse">serendipitous reuse</a>. </p> <h4>these are not the links you are looking for</h4> <p> 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 <i>single service</i>. they don't allow client applications to easily discover and use new links. often even adding links <i>within</i> 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. </p> <h4>i want to love your API</h4> <p> 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." </p> <h4>describe the interface, not the service</h4> <p> 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 <i>instances</i>. this leads to building those purpose-built clients i mentioned above. </p> <p> 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 <a href="http://twitter.com/leonardr" title="@leonardr">Leonard Richardson</a> and <a href="https://github.com/fosdev" title="fosdev">Mark Foster</a> called <a href="http://alps.io" title="Application-Level Semantic Description">ALPS</a>. ALPS is meant to provide this "abstract class"-style description of web APIs. there are other possible ways to do this, too. </p> <h4>use hypermedia formats</h4> <p> another important way we can all help each other is to rely more on hypermedia formats like <a href="https://tools.ietf.org/html/rfc5023" title="AtomPub">AtomPub</a> <a href="http://stateless.co/hal_specification.html" title="Hypermedia Application Language">HAL</a>, <a href="http://amundsen.com/media-types/collection/format/" title="Cj">Collection+JSON</a>, <a href="https://github.com/kevinswiber/siren" title="Siren: a hypermedia specification for representing entities">Siren</a>, <a href="https://rawgit.com/mamund/media-types/master/uber-hypermedia.html" title="Uniform Basis for Exchanging Representations (UBER)">UBER</a> 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. </p> <p> and that's what we all want, right? to increase shared understanding and to make it possible for both people and machines to say... </p> <h4>"I have just met you and I love you."</h4>API Academy goes to Asiahttp://www.amundsen.com/blog/archives/1153http://www.amundsen.com/blog/archives/1153Thu, 03 Apr 2014 16:48:00 GMT<p> <a href="http://apiacademy.co" title="Your Guide to API Design &amp; Implementation Best Practices"> <img src="http://apiacademy.co/sites/all/themes/apiacademy/logo.png" title="" align="right" /> </a> starting april 4th, i'll be on the road for close to two weeks. along the way i have the honor of bringing the <a href="http://apiacademy.co" title="Your Guide to API Design &amp; Implementation Best Practices">API Academy</a> message of developer-focused, enterprise-scale API design and implementation to the cites of <a href="http://api.co/seoul-wrk" title="API Strategy Workshop - Seoul April 9, 1:30pm - 5pm">Seoul</a>, <a href="http://api.co/tok-wrk" title="API Strategy Workshop - Tokyo April 11, 8:30am - 12pm" >Tokyo</a>, and <a href="http://api.co/singwrk" title="API Strategy Workshop - Singapore April 15, 8:30am - 1pm">Singapore</a>. 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. </p> <p> 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. </p> <h4>WWW2014 in Seoul </h4> <p> while in Seoul, i have the honor of presenting a peer-reviewed paper to the <a href="http://www2014.kr/program/ws-rest2014/" title="WS-REST2014 (Fifth International Workshop on Web APIs and RESTful Design)">WS-REST 2014</a> Workshop which is part of the <a href="http://www2014.kr/" title="23rd International World Wide Web Conference">World Wide Web Conference</a> 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. </p> <p> 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. </p> <h4>RESTful Web APIs in Tokyo</h4> <p> i am very excited to announce that i will be attending a <a href="http://sendagayarb.doorkeeper.jp/events/10103" title="RESTful Meetup vol. 3">RESTful Meetup</a> 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 <a href="http://www.circleaf.com/groups/19" title="RESTful Web APIs">reading group</a> for the book <a href="http://restfulwebapis.org" title="RESTful Web APIs">RESTful Web APIs</a>. </p> <p> 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. <a href="http://twitter.com/leonardr" title="@leonardr">Leonard Richardson</a> 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. </p> <h4>Singapore</h4> <p> 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. </p> <h4>ok, let's go!</h4> <p> 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. </p>the next big thing is smallhttp://www.amundsen.com/blog/archives/1152http://www.amundsen.com/blog/archives/1152Sat, 29 Mar 2014 06:46:00 GMT<blockquote> This blog post covers material from my 2014-03-28 talk at <a href="http://twitter.com/apistrat" title="API Strategy and Practice">#APIStrat</a> in Amsterdam. feel free to check out <a href="http://g.mamund.com/apistrat2014-talk" title="Self-Replication, Strandbeest, and The Game of Life">the notes from my talk</a> along with the slides and related videos online. </blockquote> <p> <a href="http://mamund.site44.com/images/the-next-big-thing-00.png"> <img src="http://mamund.site44.com/images/the-next-big-thing-00.png" width="150" align="right" class="inline" /> </a> one of the challenges i think we face is the possibility of adding tens of billions of connected devices to the internet in the next few years. currently this <a href="https://www.google.com/search?q=internet+of+things" title="Internet of Things">Internet of Things</a> is expected to grow from 20 billion connected devices in 2015 to 40 billion in 2020. </p> <h4>that's a lot of things</h4> <p> 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 <a href="http://google.com/search?1=scada">SCADA</a> and others. so, adding tens of billions more in just a few short years is going to present some challenges. </p> <h4>a lot of <i>little</i> things</h4> <p> 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 capability and capacity-wise. these will not have the power or flexibility of a laptop or even a handheld mobile phone. </p> <p> these new members of the "connected community" will be tiny, single-purpose, low-power devices that "<a href="http://en.wikipedia.org/wiki/Unix_philosophy#McIlroy:_A_Quarter_Century_of_Unix" title="McIlroy's Law">do one thing and do it well</a>." and it is likely that 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. </p> <p>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 w/ each other? </p> <h4>step-by-step programming</h4> <p> most developers today write "code" by stringing long lists of imperative statments together into a coherent set of instructions for machines. to most devlopers "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 our instruction set or due to unexpected events outside our own instrution set such as other devices that do not respond to our requests or send us unexpected data, etc. doing this on tiny devices w/ limited capacity and ability is going to be a problem. </p> <p> luckily, there is another way to "program" these devices. </p> <h4>rules, not code</h4> <p> we can also use a rules-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 that you do; you write simple rules and leave the device to it's own.... well, devices. </p> <p> 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. </p> <p> that's what i mean by <i>small</i>. the code will be small, the code will be rules. </p> <h4>how does that help us w/ the IoT?</h4> <p> 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 constanly provide step-by-step instructions on how each one operates and how they all inter-operate. instead we'll rely on simple devices that do one thing well and make the history actions available (as a stream of data, occasional dumps, etc.) to other devices authorized for access to this history. </p> <p> 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 server would be massive and a huge waste of time and bandwidth. instead, most IoT devices will act on thier own, making decisions in real time using the rules provided to them. </p> <h4>so, this is a big deal, right?</h4> <p> this way of thinking about how devices will work, 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 realtime). 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. </p> <p>but yes, this is a big deal.</p> <p>BTW - 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 typical of handhelds or laptops today. 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 by 2020. </p> <p>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 this will affect the "test-driven development" movement and related practices. and that's just one example. </p> <h4>are there examples out there of this "new" kind of programing?</h4> <p> yes, there are. and i'll pick up that thread in another blog post. </p> Uber Hypermedia - Minimalism on the Webhttp://www.amundsen.com/blog/archives/1151http://www.amundsen.com/blog/archives/1151Sun, 23 Feb 2014 22:00:00 GMT<p> <a href="http://en.wikipedia.org/wiki/File:Mondrian_Comp10.jpg" title="File:Mondrian Comp10.jpg"> <img src="http://upload.wikimedia.org/wikipedia/en/9/9c/Mondrian_Comp10.jpg" width="150" align="right" class="inline" /> </a> today i posted the first working draft of a new hypermedia design i am (humbly) calling "<a href="https://rawgithub.com/mamund/media-types/master/uber-hypermedia.html" title="Uber Hypermedia">Uber Hypermedia</a>." i've been sitting on a handful of media type designs for a couple years and finally have decided to turn my scraps of notes into something tangible. this gives me a chance to work out my ideas, get feedback from others, and -- in a small way -- contribute to the improvement of media type design in general. </p> <h4>design goals</h4> <p> here is some text from the introductory copy of this current draft spec: <blockquote> The Uber message format is a minimal read/write hypermedia type designed to support simple state transfers and ad-hoc hypermedia-based transitions. This document describes both the XML and JSON variants of the format and provides guidelines for supporting Uber messages over the HTTP protocol. </blockquote> and <blockquote> The Uber message model has a number of design goals: <ul> <li>Keep the message structure as lean as possible.</li> <li>Support all the <a href="http://amundsen.com/hypermedia/hfactor/">H-Factors</a> in hypermedia controls.</li> <li>Be compatible with multiple protocols (e.g. HTTP, CoAP, etc.)</li> <li>Maintain fidelity for more than one base message format (XML, JSON, etc.)</li> </ul> </blockquote> </p> <h4>"Less is More"</h4> <p> <a href="http://en.wikipedia.org/wiki/File:Barcelona_Pavilion.jpg" title="File:Barcelona Pavilion.jpg"> <img src="http://upload.wikimedia.org/wikipedia/commons/thumb/6/62/Barcelona_Pavilion.jpg/440px-Barcelona_Pavilion.jpg" width="150" align="right" class="inline" /> </a> like Architect <a href="http://en.wikipedia.org/wiki/Ludwig_Mies_van_der_Rohe" title="Mies van der Rohe">Ludwig Mies van der Rohe</a>, i've adopted the "Less is More" approach. this media-type design has only three elements: <code>uber</code> (the doc root), <code>data</code> (a recursive element for data and transitions), and <code>error</code> (for when things go wrong). </p> <p> my hope here is that keeping the model super simple will make is easier to implement parsers and validators as well as make it easier to convert internal object models into messages and back again. </p> <h4>De Stijl</h4> <p> and similar to <a href="http://en.wikipedia.org/wiki/Piet_Mondrian" title="Piet Mondrian">Piet Mondrian</a> and other members of the Dutch <a href="http://en.wikipedia.org/wiki/De_Stijl" title="De Stijl">De Stijl</a> movement, i wanted to focus on the minimalist, abstraction of what a hypermedia message is. to this end, i tried to reduce hypermedia down to the bare essentials of data and transition. </p> <p> there is only one element (<code>data</code>) to express both content (e.g. "Mike Amundsen") as well as express all the possible hypermedia actions such as those contained in HTML's <code>a</code>, <code>img</code> <code>iframe</code>, <code>input</code>, and <code>form</code> elements. </p> <h4>repetition and recursion</h4> <p> <a href="http://en.wikipedia.org/wiki/Steve_Reich" title="Steve Reich"> <img src="http://upload.wikimedia.org/wikipedia/commons/e/eb/Steve_Reich2.jpg" width="150" align="right" class="inline" /> </a> i also find the <a href="http://en.wikipedia.org/wiki/File:Pat_Metheny-Electric_Counterpoint_III_Fast.ogg" title="File:Pat Metheny-Electric Counterpoint III Fast.ogg">reptition and recursive patterns</a> in the <a href="http://en.wikipedia.org/wiki/Minimal_music" title="Minimal Music">minimal music</a> of <a href="http://en.wikipedia.org/wiki/Steve_Reich" title="Steve Reich">Steve Reich</a> (and others) very appealing and have used that as an inspiration in creating a format where the real information is found in continuously-nested copies of the same (<code>data</code>) element, each with its own slight variation. </p> <p> essentially, creating a service that supports the <a href="https://rawgithub.com/mamund/media-types/master/uber-hypermedia.html" title="Uber Hypermedia">Uber Hypermedia</a> format means embracing the recursion and repetition that altready exists in our computer models. hopefully, this approach will make it realtively easy to handle conversions from internal object trees into external Uber messages. </p> <h4>comment, clone, and pull</h4> <p> i've posted the <a href="https://github.com/mamund/media-types" title="Uber in github">working draft in github</a> in hopes that those wishing to provide feedback can comment, add issues, clone and even submit pull requests to help me refine and improve the design. i have yet to build any client or server implementations yet (that's the next step) and would love to hear from those wishing to do the same. </p> <p> so there it is; a hypermedia format with just three elements, eleven attributes, and only seven reserved strings. i'm a man of small ambitions for this project [grin]! </p> measuring up hypermedia typeshttp://www.amundsen.com/blog/archives/1150http://www.amundsen.com/blog/archives/1150Fri, 31 Jan 2014 20:58:00 GMT<p> <a href="http://www.flickr.com/photos/anttree/5011897105/" title="Photo365-Day061-HalfInch-FLICKR by AntTree, on Flickr"> <img src="http://farm5.staticflickr.com/4086/5011897105_24b17c4392_q.jpg" width="150" height="150" align="right" class="inline" alt="Photo365-Day061-HalfInch-FLICKR" /> </a> in a <a href="https://groups.google.com/forum/#!topic/api-craft/NgjzQYVOE4s" title="HAL vs Siren vs JSON API">recent thread</a> on the API-Craft news group a question came up about how one could go about selecting one of the <a href="http://stateless.co/hal_specification.html" title="HAL - Hypertext Application Language">more</a> <a href="http://amundsen.com/media-types/collection/" title="Collection+JSON - Hypermedia Type">than</a> <a href="https://github.com/kevinswiber/siren" title="Siren: a hypermedia specification for representing entities">one-half</a> <a href="http://jsonapi.org/" title="JSON API">dozen</a> <a href="https://github.com/JornWildt/Mason" title="Mason: a hypermedia enabled JSON format">new</a> <a href="http://lapis2012.linkedservices.org/papers/1.pdf" title="The necessity of hypermedia RDF and an approach to achieve it"> hypermedia types</a> when it came time to implement your <a href="http://en.wikipedia.org/wiki/Hypermedia_API" title="Hypermedia API">Hypermedia API</a>. it's a pretty good thread since many of the designers of these new media types were in on the conversation. </p> <p> i posted a couple ways to think about assessment of a media type's applicability to the target API and thought i'd elaborate on that a bit here. the first method i recommend is to inspect the hypermedia features of the media type itself. the second measure i recommend is to try to get some information about how the media type is used in the wild. </p> <h4>H-Factors</h4> <p> one way to inspect a media type design and see if it will work for your use case is to use the <a href="http://amundsen.com/hypermedia/hfactor/" title="Hypermedia Factors">H-Factor</a> list. this is a list nine properties of hypermedia that may (or may not) be supported in the media type design. i won't go into the details of H-Factors here (you can follow the link above for details). However, the list of factors offers a way to see which hypermedia actions such as navigation links, embedding links, query forms, write bodies, the ability to select post formats, etc. (all things that Web APIs - at the <i>network level</i> must deal with) are described and supported within the media type in question. </p> <p align="center"> <img src="http://amundsen.com/images/hypermedia/hfactors-svg.png" /> <img src="http://amundsen.com/images/hypermedia/hfactors-atom.png" /> <img src="http://amundsen.com/images/hypermedia/hfactors-html.png" /> </p> <p> for example <a href="http://www.w3.org/TR/html5/" title="HTML5 : A vocabulary and associated APIs for HTML and XHTML">HTML</a> doesn't support idempotent updates (PUT and DELETE) but <a href="http://tools.ietf.org/search/rfc5023" title="The Atom Publishing Protocol">Atom</a> does. And while Atom doesn't support describing adhoc queries (ala <code>HTML.FORM@method="get"</code>), <a href="http://amundsen.com/media-types/collection/" title="Collection+JSON - Hypermedia Type">Collection+JSON</a> does. And while Collection+JSON doesn't support describing adhoc network methods (e.g. specifying POST, PUT, PATCH, etc.), <a href="https://github.com/kevinswiber/siren" title="Siren: a hypermedia specification for representing entities">Siren</a> does. And so forth. </p> <p> so one way you can decide which media types you want to support is to figure out which hypermedia features you need to support in your API and select from the list of media type designs that match those needs. </p> <h4>Implementations</h4> <p> another way to think about selecting a media type design is to focus on the existing implementations "in the wild." this can give you a sense of the stability, usability, and flexibility of the design. here are three things to consider when assessing implementations: </p> <dl> <dt>independent implementations</dt> <dd> a design that has a high number of <i>independent</i> implementations can be a sign that the design is easy to work with and that it has a broad reach/appeal. it may also be a sign that the design itself is well understood and stable. this measure is based on <a href="http://en.wikipedia.org/wiki/David_D._Clark" title="David D. Clark">David Clark</a>'s notion of "rough concensus and running code" as a guide for standards review. <blockquote> <p> We reject: kings, presidents and voting.<br /> We believe in: rough consensus and running code. </p> <p align="right"> <a href="http://www.ietf.org/old/2009/proceedings/prior29/IETF24.pdf" title="Proceedings of the Twenty-Fourth Internet Engineering Task Force"> David D. Clark (1992) </a> </p> </blockquote> </dd> <dt>inter-operable implementations</dt> <dd> the number of inter-operable implementations is a worthwhile measure, too. IOW, can two people who never met before each implement the same design and have their applications work together? This can be an indication of what <a href="https://twitter.com/svrc" title="@svc">Stu Charlton</a> calls "<a href="http://www.stucharlton.com/blog/archives/000165.html" title="Planned vs. Seredipitous Reuse">serendipitous reuse</a>." some designs don't have this as a goal; instead they are aiming for optimizing a custom interface between two "well-known" parties. one example of a design that has "serendipitous reuse" as a goal is the <a href="http://amundsen.com/media-types/maze/" title="Maze+XML - Maze Document">Maze+XML</a> media type. there are quite a number of successful implementations that all work together nicely. <blockquote> <p> The Web architecture is all about serendipity, and letting a thousand information flowers bloom, regardless of whether it serves some greater, over arching, aligned need. </p> <p align="right"> <a href="http://www.stucharlton.com/blog/archives/000165.html" title="Planned vs. Seredipitous Reuse"> Stu Charlton (2007) </a> </p> </blockquote> </dd> <dt>unexpected implementations</dt> <dd> it's also good to consider whether the design results in any "unexpected uses" - something that was not part of the original designers' goals. you'e probably experienced something like this yourself. you're working with an app, a coding framework, programming language, etc. and suddenly you notice something totally novel and say "Wow! I didn't think was even possible with this!" <a href="https://twitter.com/jnd1er" title="@jnd1er">Donald Norman</a>, one of the early advocates for studying <a href="http://en.wikipedia.org/wiki/Human%E2%80%93computer_interaction" title="Human-computer interaction">HCI</a>, refers to this feaure in the last line of his excellent 2min video on "<a href="https://www.youtube.com/watch?v=NK1Zb_5VxuM" title="">Affordances</a>." <blockquote> <p> The value of a well-designed object is when it has such a rich set of affordances that the people who use it can do things with it that the designer never imagined. </p> <p align="right"> <a href="http://www.w3.org/2011/10/integration-workshop/p/hypermedia-oriented-design.pdf" title="Hypermedia-Oriented Design"> Donald Norman (1994) </a> </p> </blockquote> </dd> </dl> <h4>Other Considerations</h4> <p> there are other ways to make judgments about the applicability of a media-type design for your use case. here are some that come to mind: </p> <dl> <dt>user activity</dt> <dd> this was mentioned in the thread that sparked this blog post. it is a good idea to check out how much online activity there is regarding the media type. for example, the "Issues" list in github, any associated news groups or help forums, and - in the case of established open standards groups - lists hosted by the governing standards body (<a href="http://lists.w3.org/Archives/Public/" title="W3C Public Mailing List Archives">W3C</a>, <a href="http://datatracker.ietf.org/list/wg/" title="Web-based Working Group E-mail Archives">IETF</a>, <a href="https://lists.oasis-open.org/archives/" title="OASIS Mailing List Directory">OASIS</a>, etc.). a healthy online community is can be a sign of a robust design. </dd> <dt>influential authors</dt> <dd> sometimes the authors of a media type hold an important position in the online community. this alone can give the design an 'instant' broad reach that some other designs won't match. for example, the primary authors of the <a href="http://jsonapi.org/" title="JSON API">JSON API</a> (<a href="https://twitter.com/steveklabnik" title="@steveklabnik">Steve Klabnik</a> and <a href="https://twitter.com/wycats" title="@wycats">Yehuda Katz</a>) are also the key contributors to a couple very popular programming tools (<a href="http://rubyonrails.org/" title="Ruby on Rails">Ruby on Rails</a> and <a href="http://emberjs.com/" title="Ember.js - A framework for creating ambitious web applications">Ember.js</a> respectively). when they get invovled in a design, it is likely that many will see it and get a chance to work with it. </dd> <dt>influential users</dt> <dd> in some cases, a design will be picked up by big names in the industry and this can increase the reach of a design. for example the <a href="http://stateless.co/hal_specification.html" title="HAL - Hypertext Application Language">HAL</a> media type was recently chosen by Amazon.com for their <a href="http://docs.aws.amazon.com/appstream/latest/developerguide/rest-api.html" title="Amazon AppStream REST API">appStream</a> API. Microsoft's <a href="http://www.odata.org/documentation/odata-version-4-0/" title="OData Version 4.0 Comittee Specification">OData</a> specification is another example of a media type design that has the opportunity to touch quite a number of developers and projects. finally, adoption by "heavy hitters" in the industry may help in cases where you need to convince your team or management to adopt the design for your own use. </dd> </dl> <h4> the choice is yours </h4> <p> there you have it: H-Factors, implementation in the wild, and community standing are just some of the ways in which you can begin to critically assess whether a particular media type design is right for your API implementation. the most important thing to keep in mind in all this is not which methods you use to decide on your media type choices. the most important thing to remember is that <i>you actively assess and make a choice</i>. </p> <p> to that end, i'll add one more quote (from <a href="https://twitter.com/fielding" title="@fielding">Roy Fielding</a>) to close out this post: </p> <blockquote> <p> [C]onsider how often we see software projects begin with adoption of the latest fad in architectural design, and only later discover whether or not the system requirements call for such an architecture. Design-by-buzzword is a common occurrence. </p> <p align="right"> <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/introduction.htm" title="Architectural Styles and the Design of Network-based Software Architectures">Roy T. Fielding (2000)</a> </p> </blockquote> <h4>don't fall victim to "Design-by-buzzword" when implementing your API!</h4> "That's not Hypermedia!"http://www.amundsen.com/blog/archives/1149http://www.amundsen.com/blog/archives/1149Sun, 19 Jan 2014 12:58:00 GMT<p> <a href="http://www.screeninsults.com/crocodile-dundee.php" title="That's not a knife. This is knife."> <img src="http://www.screeninsults.com/images/crocodile-dundee-knife2.jpg" height="150" align="right" class="inline" alt="That’s not a knife. This is knife."/> </a> i've been very pleased to see an increasing number of people speaking and writing about the use of hypermedia in their APIs. in fact, a new wikipedia entry for <a href="http://en.wikipedia.org/wiki/Hypermedia_API" title="Hypermedia API">Hypermedia API</a> has recently appeared, too. this renewed focus on a fundamental principle of the Web is a great way to improve the way we design and build apps for the Web. </p> <p> but it's important to make sure we're all talking about the same thing. that when we use the word <i>hypermedia</i> we are actually talking about, and showing examples of, <i>hypermedia</i>. </p> <h4>"That's not Hypermedia."</h4> <p> for example, this is not hypermedia: </p> <p class="code"> http://example.org/q1w2e3r4/123 </p> <p> what you see here is just a URL. you know nothing about what it represents, what you can <i>do</i> with that link, or what is at the other end. </p> <p> this is also <b>not hypermedia</b>: </p> <p class="code"> http://example.org/customers/123 </p> <p> changing some of the characters in the URL does not magicially turn it into hypermedia. even though now (with these new fancy characters) you, as a human, are ready to start making assumptions about what this link represents, what you can do with it, and what's at the other end. </p> <p> how about a test. what do you think is at the other end? </p> <ol> <li>a customer record</li> <li>a blog entry about the 'customers' product</li> <li>a photo of one of the most valuable customers for the last year</li> </ol> <p> and we haven't even started to speculate on what you can <i>do</i> with this URL. can you: </p> <ol> <li>edit the data?</li> <li>remove the record from the system?</li> <li>query and or filter the data at the other end of the URL?</li> </ol> <p> and if any of the above are possible, what are the rules for executing the action? </p> <ol> <li>are there parameters to pass?</li> <li>do you pass them in the URL line? the body?</li> <li>if you pass them in the body, what are the possible message formats for sending a body?</li> <li>what protocol details should be used here? (<a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html" title="Hypertext Transfer Protocol -- HTTP/1.1">HTTP</a>? <a href="http://tools.ietf.org/search/draft-ietf-core-coap-18" title="Constrained Application Protocol (CoAP)">CoAP</a>? which protocol method?)</li> </ol> <p> hopefully, you're getting the picture. a URL alone is nothing but a string. it might be a <i>link</i> to something else, but even that is not assured. the <a href="http://www.w3.org/RDF/" title="Resource Description Framework">RDF</a> family of technologies often uses URLs as mere identifiers (then they're URIs, actually) that may have nothing at the other end at all. </p> <h4>"<i>This</i> is Hypermedia."</h4> <p> so what does hypermedia look like? it looks like this snippet of <a href="https://github.com/kevinswiber/siren" title="Siren: a hypermedia specification for representing entities">Siren</a>: </p> <p class="code"> "actions": [ { "name":"update-customer", "title":"Update Customer", "method":"POST", "href":"http://example.org/customers/123", "type":"application/x-www-form-urlencoded", "fields": [ {"name":"status","type":"hidden","value":"partial"}, {"name":"return","type":"hidden","value":"full"}, {"name":"email","type":"text" }, {"name":"sms","type":"number" } ] } ] </p> <p> now you can see lots of information about what this URL represents, what you can do with it, and what's at the other end of the link. and you see it all in a form that is machine-readable. </p> <p> that's hypermedia. </p> <h4>but, what about REST and stuff?</h4> <p> yes, <a href="http://roy.gbiv.com/" title="Roy T. Fielding">Fielding</a> wrote a 175+ page dissertation which contains a chapter named <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm" title="Representational State Transfer (REST)">Representation State Transfer (REST)</a> which is another thing people talk about a lot. and, yes, in that chapter contains a mysterious phrase: </p> <blockquote> <p> "...hypermedia as the engine of application state." </p> <p align="right"> <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5">Sec. 5.1.5 Uniform Interface</a> </p> </blockquote> <p> which some people mangle into an ugly term of art: <a href="http://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a>. but don't get sidetracked. this blog post is about <i>hypermedia</i>, not REST. </p> <p> You see, REST <i>depends</i> on the use of hypermedia (<a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven" title="REST APIs must be hypertext-driven">Roy made that clear back in 2008</a>), but hypermedia does not depend on REST. you can build hypermedia systems without having to create something that matches all of Fielding's REST constraints. and that's an important thing to keep in mind. </p> <h4>so there you have it</h4> <p> when talking about hypermedia, you don't have to be all "REST this..." and "REST that..." and such. just be sure to talk about more than simple URLs. because hypermedia is "all that other stuff" we need in order to get work done on the web. <a href="http://twitter.com/leonardr" title="@leonardr">Leonard Richardson</a> says it really well in the book <a href="http://www.restfulwebapis.com" title="RESTful Web APIs">RESTful Web APIs</a>: </p> <blockquote> <p> "Hypermedia connects resources to each other, and describes their capabilities in machine-readable ways." and "Hypermedia is a way for the server to tell the client what HTTP requests the client might want to make in the future." </p> <p align="right"> <a href="http://bit.ly/Ku1YEJ" title="RESTful Web APIs">Chapter 4. Hypermedia</a> </p> </blockquote> <h4><i>Now, THAT's hypermedia!</i></h4>how to spot a hypermedia client apphttp://www.amundsen.com/blog/archives/1148http://www.amundsen.com/blog/archives/1148Mon, 06 Jan 2014 11:06:00 GMT<p> <a href="http://www.flickr.com/photos/retrocactus/5261318350/" title="Inside your iPhone 4 by John Biehler, on Flickr"> <img src="http://farm6.staticflickr.com/5084/5261318350_3fd95d45d9_q.jpg" width="150" height="150" alt="Inside your iPhone 4" class="inline" align="right"/> </a> it's not always easy to spot hypermedia clients 'in the wild.' there are a handful of reasons for this. however, if you know what you're looking for, it is actually pretty straight-forward to ferret out the real hypermedia clients from the posers. </p> <h4>appearances can be deceiving</h4> <p> you can't usually spot a hypermedia client from the 'outside.' it's not the way the app looks or feels that indicates true hypermedia. for example, some folks think implementing an HTML-based app is the same as implementing a hypermedia app. but, sorry, no. an HTML app can be a couple <code>DIV</code> containers and thousands of lines of javascript; that's not hypermedia. </p> <p> some think that Web apps which exhibit adaptability are hypermedia clients. not necessarily. you can achieve a great deal of flexibility and adaptability through the use of configuration (including remote configuration) and support for plug-ins or dynamically loaded modules based on configuration or user context (e.g. which user is logged in, what they are allowed to access, etc.). </p> <p> this is all good stuff, but it's not a sure sign of hypermedia use. </p> <h4>server API is not enough</h4> <p> it might seem that any server that emits a hypermedia-style API would result in hypermedia clients. but, no, that's not right either. in fact, one of the features of hypermedia implementation is that servers don't dictate how clients use their interfaces. servers merely respond with machine-readable descriptions of links (e.g. <a href="http://www.w3.org/TR/html401/struct/links.html#h-12.2" title="The A element"><code>HTML.A</code></a>, <a href="http://tools.ietf.org/search/rfc4287#section-4.2.7" title='The "atom:link" Element'><code>atom.link</code></a>, etc.) and forms (e.g. <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.3" title="The FORM element"><code>HTML.FORM</code></a>, <a href="http://amundsen.com/media-types/collection/format/#objects-template" title="The collection+json template object"><code>collection.template</code></a>, etc.) and let client apps decide what to do with them (if anything). </p> <p> it's very easy to build successful client applications that 'talk' to hypermedia interfaces on servers yet still ignore the inline affordances and just deal the content in which the client app is interested. they can even ignore all the hypermedia and 'memorize' URLs, workflow paths, etc. and continue to work fine with the server. </p> <p> until, of course, the server changes the rules. then client apps that ignore the hypermedia run the risk of misbehaving or even breaking. </p> <h4>it's what's inside that counts</h4> <p> it turns out there is a rather simple way to spot hypermedia clients - look 'inside.' this is especially easy for browser-based hypermedia apps. a quick "View Source" will almost always reveal the level to which the application is tuned to hypermedia instead of a pre-determined set of data and actions. </p> <p> imagine a simple service (<code>TASKS</code>) that tracks "to-do" tasks. it might, for example, support a small set of data and actions: </p> <ol> <li><code>id</code> - unique identifier data element</li> <li><code>text</code> - a string that describes the task to complete</li> <li><code>LIST</code> - an action that returns the list of tasks</li> <li><code>FILTER</code> - an action that returns a subset of items, filtered by title fragment</li> <li><code>ADD</code> - an action that creates a new task in the list</li> <li><code>MARK-COMPLETE</code> - an action that marks an existing tasks complete</li> </ol> <p> now, without getting tied up in the server interface (we'll <i>assume</i> the server responds w/ inline hypermedia), we can check out client-side source code and spot which client app is actually relying on inline hypermedia. </p> <p> below is a listing of the functions and shared variables from one client app using this <code>TASKS</code> service. do you think this is a hypermedia client app? </p> <script src="https://gist.github.com/mamund/8141196.js"></script> <p> not sure? how about this next one? </p> <script src="https://gist.github.com/mamund/8141221.js"></script> <p> one of these clients has 'memorized' quite a bit about the <code>TASKS</code> service and the other has very little <i>foreknowledge</i> of how things work with the <code>TASKS</code> service. that means one of these clients has a better chance of handling changes to the service workflow and data elements and the other one has a high dependency on the service specifics and will run into trouble when those specifics change over time. </p> <h4>focus on inner beauty</h4> <p> both these client apps really exist. you can find the full source code for a <a href="https://github.com/apiacademy/tasks-crud" title="simple CRUD-style server and client for a TASK service">CRUD implementation</a> and a <a href="https://github.com/apiacademy/tasks-hypermedia" title="simple hypermedia-style server and client for a TASK service">Hypermedia implementation</a> of the <code>TASKS</code> service in the <a href="https://github.com/apiacademy" title="Layer 7 API Academy">API Academy repo</a> at github. both clients are fully functional and at runtime, from the outside, you can't tell the <a href="http://en.wikipedia.org/wiki/Create,_read,_update_and_delete" title="Create, read, update, delete">CRUD</a> client from the <a href="http://amundsen.com/blog/archives/1109" title="hypermedia affordances">Hypermedia</a> client. </p> <p> however, spotting hypermedia clients is straight-forward when you know what to look for. and knowing what to look for can help you when it comes time to create <i>your own hypermedia client apps</i>. in the end, you need to focus on keeping details out of the client code including the specifics of current data elements and workflow rules. instead, you can let the server interface fill those in for you at runtime. when you do that, the <i>structure</i> of your client will become simpler and easier to maintain. </p> <p> and that's when you may begin to see an 'inner beauty' to hypermedia client apps that you might not have recognized in the past. </p>URLs are an implementation detailhttp://www.amundsen.com/blog/archives/1147http://www.amundsen.com/blog/archives/1147Sun, 13 Oct 2013 11:06:00 GMT<p> <a href="http://www.flickr.com/photos/mar00ned/229903286/sizes/l/in/photolist-mjjeL-o5ath-DUKTC-KV7ZJ-KV82q-KV875-KVgBD-KVgDg-KVgEx-KVgFt-KVgG6-KVgGD-28ZmJg-2hTUxH-2yAXWY-2Bh5VH-2Un4RM-2Urqyd-2UruMJ-3BwWp1-3RnvKf-47yKN9-4aFpBc-4fJPSi-4Krp7c-4LBujV-4UVaFA-51PZyx-52Qx91-5beGnc-5beKDR-5bj17u-5bj43E-5bj4P7-5bj6C1-5mX7wA-5oL5pA-5paWQt-5t2HkW-5tNJjh-5RDpmE-5XQpRv-662RZ7-66c7bz-68sMZG-69qazy-6j5XEJ-6uf3sB-6yHGYa-6HCnd5-6JRrJk/" title="Complicated"> <img src="http://farm1.staticflickr.com/68/229903286_4acfaa65fc_q.jpg" align="right" class="inline" /> </a> i've had a number of conversations (both online and off) about URLs, URL construction rules, URI templates, and related items. i've also been doing some research into what <a href="http://twitter.com/leonardr" title="@leonardr">Leonard Richardson</a> and i call "description formats" in our new book <a href="http://restfulwebapis.com" title="RESTful Web APIs">RESTful Web APIs</a>. these formats are designed to describe services on the Web. they are meant to make it easier for devs working on client implementations to understand how a server works; they describe the server interface. it turns out these service descriptions almost always include URLs, too. </p> <p> and that's a problem. </p> <h4>constraining server URLs</h4> <p> description formats (like <a href="http://www.w3.org/TR/wsdl" title="Web Service Definition Langauge">WSDL</a>, <a href="http://www.w3.org/Submission/wadl/" title="Web Application Description Language">WADL</a>, <a href="http://raml.org/" title="RESTful API Modeling Language">RAML</a>, and others) often include either absolute or relative URLs. these descriptions are telling clients the exact URL for various actions. it seems like a good idea, but its not. why? because these description formats are constraining the URL space for any server that wants to implement that service. IOW, servers don't control their own URLs. there are so many variables in implementing services (operating systems, programming languages, Web frameworks, etc.) that formats which tell servers how the URLs space should be managed can sometimes run afoul of implementation details for that particular server. </p> <p> and that's a bummer </p> <h4>hold your nose</h4> <p> one of the key properties of the Web is that a client should be able to "<a href="http://www.w3.org/wiki/FollowYourNose">follow your nose</a>" to locate new content and actions. IOW, clients should not memorize a set of URLs (or URL construction patterns) and should, instead, be open to discovering new links (ones that weren't there 'yesterday') and following those links (and forms) and activating them when appropriate. </p> <p> but almost all description formats ignore the "follow your nose" dictum and instead tell clients to "hold their nose" and pre-build all the URLs into source code ahead of time. Essentially, these clients are built to <i>ignore</i> new links and forms. This keeps the client from following new paths provided by the service and basically prevents small changes over time from enriching the Web. </p> <p> and that's not good. </p> <h4>actions, not addresses</h4> <p> instead of hard-coding URLs, description documents should hard-code the <i>actions</i> that are supported by the service (add, edit, approve, share, etc.) and describe the action details (protocol methods, arguments, etc.) and allow clients to recognize these actions and arguments and use whatever URLs appear at runtime to complete the actions. clients are then able to recognize the same actions used by other servers even when the exact address of these actions are different for each server implementation. </p> <p> it's the <i>actions</i> that count, not the addresses. </p> <h4>describe the service, not the server</h4> <p> essentially, what most existing description formats do is describe a particular server's implementation, not the service itself. this is fine if your single implementation is so large and popular that hundreds of client devs are happy to create apps just for that single server instance. <a href="http://twitter.com">Twitter</a>, <a href="http://facebook.com">Facebook</a>, <a href="http://plus.google.com">Google+</a>, and others are in this group. </p> <p> but what about all those hundreds of other cool servers out there doing great things on a smaller scale? what about servers like <a href="http://rstat.us">RStatus</a>, <a href="http://identi.ca">Identi.ca</a>, <a href="http://www.tout.com/">Tout</a>, and others? and what about the 500+ shopping services registered on <a href="http://www.programmableweb.com/apitag/shopping">ProgrammableWeb</a>? is describing each of these implementation separately the only way to go? </p> <p> the habit of describing each and every <i>server</i> instead of a general description of a <i>service</i> is a wasteful habit we need to break. </p> <h4>there is another way....</h4> <p> <a href="http://twitter.com/leonardr" title="@leonardr">Leonard Richardson</a> and i have been working on an alternative approach to describing services. one that does not require constraining a server's URL space. one that describes the service itself, not the implementation of a single server. an approach that focuses on describing the <i>actions</i>, not the <i>addresses</i>. it is very early in the process, but we think <a href="http://alps.io" title="Application-Level Profile Services">ALPS</a> makes it possible to break out of the bad habit of pre-defining URLs and frees client apps to get back to "following their nose" when interacting with a service, no matter <i>where</i> that service lives on the Web. </p> <p> over the coming weeks, i'll talk more about the emerging ALPS spec and explore the possible ways in which breaking the straight-jacket of URL-based description can increase both the stability and evolvability of services on the Web. </p> <p> ALPS (or something like it) can help us create better, more powerful service descriptions - and that's a good thing, right? </p>