mca bloghttp://www.amundsen.com/blog/making progressFri, 03 Jul 2015 00:15:03 GMTen-us180three years and countinghttp://www.amundsen.com/blog/archives/1160http://www.amundsen.com/blog/archives/1160Tue, 30 Jun 2015 14:17:00 GMT<p> <a href="http://www.apiacademy.co/" title="API Academy"> <img src="http://www.apiacademy.co/sites/all/themes/apiacademy/logo.png" align="right" class="inline" /> </a> it was three years ago <a href="http://amundsen.com/blog/archives/1132" title="Mike Amundsen, Principal API Architect">this month</a> that i joined <a href="http://twitter.com/mattmclartybc" title="@MattMcLartyBC">Matt McLarty</a> and <a href="http://twitter.com/mitraman" title="@mitraman">Ronnie Mitra</a> to form the <a href="http://apiacademy.co" title="API Academy">API Academy</a>. and i've never regretted a minute of it. </p> <h4>Layer7's brain child</h4> <p> the idea for the API Academy came out of the core leadership of what was then known as <a href="http://www.ca.com/us/lpg/layer-7-redirects.aspx" title="Layer7">Layer7</a>. basically, it was the chance to pull together some of the great people involved in APIs for the Web and focus on promoting and supporting API-related technologies and practices. from the very beginning it was decided that the API Academy would focus on "big picture stuff" -- not a particular product or technology segment. and we dove in with both feet. </p> <p> my first talk <a href="http://www.reuters.com/article/2012/06/19/idUS184375+19-Jun-2012+BW20120619">as part of the Academy</a> was June 2012 on hypermedia and node.js at QCon NYC. Ronnie and i finally met face-to-face later that summer at the Layer7 office in Vancouver. we both talked at <a href="http://2012.restfest.org/">RESTFest 2012</a> where Layer7 became a key sponsor of that event. in December of 2012, Ronnie and I were proud to join <a href="https://twitter.com/medjawii" title="@medjawii">Mehdi Medjaoui</a> at the very first <a href="http://lanyrd.com/2012/apidays/">API Days in Paris</a>. and we've been going strong ever since. </p> <h4>great people</h4> <p> the API Academy is an amazing group of people. over the last three years, along w/ Matt and Ronnie we've had the chance to host <a href="http://tiwtter.com/" title="@intalex">Alex Gaber</a>, <a href="http://twitter.com/hlgr360" title="@hlgr360">Holger Reinhardt</a> -- both of whom have moved on to other things -- and <a href="http://twitter.com/inadarei" title="@inadarei">Irakli Nadareishvili</a> who came to us from his work at National Public Radio here in the US. the oppty to work side-by-side with people of this caliber is a gift and i am happy to be a part of it. </p> <h4>CA Technologies</h4> <p> since i joined API Academy, Layer7 has merged w/ <a href="http://twitter.com/cainc" title="@CAInc">CA Technologies</a> and this has given us the chance to expand our reach and increase our contact w/ experienced people from all over the world. since joining w/ CA we've had the chance to travel to Australia, Hong Kong, Tokyo, Seoul, Beijing, and several cities Eastern Europe. later this year there will be visits to Shanghai and Rio de Janeiro along w/ dozens of cities in the US and Europe. along the way the API Academy continues to meet w/ CA product teams and leadership offering to assist in any way we can to continue the same mission we had at our founding. </p> <h4>Help People Build Great APIs for the Web</h4> <p> i've worked lots of places, with diverse teams, in all sorts of cultures. i have to say that my experience w/ the API Academy and w/ CA continues to be one of the most rewarding and supportive i've ever enjoyed. i am very lucky that i get to do the kind of work i love w/ people that challenge my thinking, support my experimenting, and offer excellent opportunities to learn and grow along the way. </p> <p> the last three years have been full of surprises and i can't wait to see what the next three years brings. i am truly a <i><b>#luckyMan</b></i> </p> the next level in Web APIshttp://www.amundsen.com/blog/archives/1159http://www.amundsen.com/blog/archives/1159Mon, 25 May 2015 21:07:00 GMT<p> <a href="http://www.infoq.com/articles/description-discovery-profiles-series-intro" title="Description, Discovery, and Profiles : The Next Level in Web APIs"> <img src="http://www.infoq.com/resource/articles/description-discovery-profiles-series-intro/en/smallimage/serieslogo.jpg" align="right" class="inline" width="150"/> </a> i'm very proud to announce that <a href="http://www.infoq.com/">InfoQ</a> has just released a new series that I helped edit. the series is called <a href="http://www.infoq.com/articles/description-discovery-profiles-series-intro">Description, Discovery, and Profiles: The Next Level in Web APIs</a> and the contents of this series has a series of excellent contributing authors including <a href="https://twitter.com/mitraman" title="@mitraman">Ronnie Mitra</a> of <a href="http://apiacademy.co">API Academy/CA</a>, <a href="https://twitter.com/mikegstowe" title="@mikegstowe">Mike Stowe</a> with <a href="https://www.mulesoft.com">Mulesoft</a>, <a href="https://twitter.com/kinlane">Kin Lane</a> of <a href="http://apievangelist.com/">API Evangelist</a> fame and, <a href="https://twitter.com/fosrias" title="@fosrias">Mark Foster</a> from <a href="https://apiary.io/">Apiary</a>. it also includes interviews with <a href="http://swagger.io">Swagger</a> creator <a href="http://twitter.com/fehguy" title="@fehguy">Tony Tam</a> and <a href="https://tools.ietf.org/html/rfc6906" title="">Profile RFC</a> editor <a href="http://twitter.com/dret" title="@dret">Erik Wilde</a>. and it's packed with material covering what i think are three key patterns/technologies in the Web API space: </p> <dl> <dt>Description</dt> <dd> "The ability to easily describe APIs including implementation details such as resources and URLs, representation formats (HTML, XML, JSON, etc.), status codes, and input arguments in both a human- and machine-readable form. There are a few key players setting the pace here." </dd> <dt>Discovery</dt> <dd> "Searching for, and selecting Web APIs that provide the desired service (e.g. shopping, user management, etc.) within specified criteria (e.g. uptime, licensing, pricing, and performance limits). Right now this is primarily a human-driven process but there are new players attempting to automate selected parts of the process." </dd> <dt>Profiles</dt> <dd> "Long a focus of librarians and information scientists, 'Profiles' that define the meaning and use of vocabulary terms carried within API requests and responses are getting renewed interest for Web APIs. Still an experimental idea, there is some evidence vendors and designers are starting to implement support for Web API Profiles." </dd> </dl> <h4>lots of vendors and technologies here</h4> <p> this is a pretty wide-ranging set of topics and lots of vendors and technologies are highlighted over the next seven articles. some of them include: </p> <ul> <li><a href="http://swagger.io">Swagger</a></li> <li><a href="http://raml.org">RAML</a></li> <li><a href="https://apiblueprint.org/">API Blueprint</a></li> <li><a href="http://www.w3.org/TR/wsdl">WSDL</a></li> <li><a href="https://www.visualstudio.com/">Visual Studio</a></li> <li><a href="https://eclipse.org/">Eclipse</a></li> <li><a href="http://smartbear.com/">SmartBear</a></li> <li><a href="http://www.mashery.com/product/io-docs">I/O Docs</a></li> <li><a href="http://apicommons.org/">API Commons</a></li> <li><a href="http://www.programmableweb.com/apis/directory">Programmable Web's API Directory</a></li> <li><a href="http://3scale.net">3Scale</a></li> <li><a href="http://developer.mashery.com/">Mashery's API Network</a></li> <li><a href="http://zookeeper.apache.org/">Apache Zookeeper</a></li> <li><a href="https://www.consul.io/">HashiCorp Consul</a></li> <li><a href="https://coreos.com/etcd/">CoreOS etcd</a></li> <li><a href="http://apis.io/">APIs.io</a></li> <li><a href="http://gmpg.org/xmdp/">XMDP</a></li> <li><a href="http://dublincore.org/documents/profile-guidelines/">DCAP</a></li> <li><a href="http://tools.ietf.org/html/draft-amundsen-richardson-foster-alps-01">ALPS</a></li> <li><a href="https://github.com/apiacademy/rapido-spa">Rapido API Designer</a></li> <li><a href="http://docs.spring.io/spring-data/rest/docs/current/reference/html/#metadata">Spring Data</a></li> <li><a href="http://www.w3.org/RDF/">RDF</a></li> </ul> <p> and that's just in the <b>first</b> article in the series! </p> <p> here's a quick rundown of all the articles that will br released between late May and early July: </p> <h4>Description, Discovery, and Profiles: A Primer</h4> <p> this articles takes a look at several formats, key vendors, and identify the opportunities and challenges in this fast-moving portion of the Web API field. </p> <h4>From Doodles to Delivery : An API Design Process</h4> <p> Ronnie Mitra investigates what good design is and how using Profiles along with an iterative process can help us achieve it. </p> <h4>The Power of RAML</h4> <p> Mike Stowe introduces us to the RAML format, reviews avilable uses and tools, and explains why Uri Sarid, the creator of RAML wanted to push beyond our current understandings and create a way to model our APIs before even writing one line of code. </p> <h4>APIs with Swagger : An Interview with Reverb's Tony Tam</h4> <p> I talk to founder and inventor Tony Tam about the history, and the future, of one of the most widely-used API Description formats today: Swagger. </p> <h4>The APIs.json Discovery Format: Potential Engine in the API Economy</h4> <p> In this piece, Kin Lane describes his APIs.json API discovery format which can provide pointers to available documentation, licensing, pricing for exsiting Web APIs. </p> <h4>Profiles on the Web: An Interview with Erik Wilde</h4> <p> In early April, 2015 Erik agreed to sit down with InfoQ to talk about Profiles, Description, Documentation, Discovery, his Sedola project and the future of Web-level metadata for APIs. </p> <h4>Programming with Semantic Profiles : In the land of magic strings, the profile-aware is king.</h4> <p> Mark Foster -- one of the editors of the ALPS specification -- explains what semantic profiles are and how they can transform the way Web APIs are desgined and implemented. </p> <h4>A Resource Guide to API Description, Discovery, and Profiles</h4> <p> To wrap up the series, we offer a listing of the key formats, specifications, tools, and articles on API Description, Discovery, and Profiles for the Web. </p> <h4>looking forward to the weekly releases</h4> <p> it was a pleasure working with such a distinguished group of authors and practitioners in this very important space and i am looking forward to the continued released between late May and early July. i'm also looking forward to feedback and discussion from readers of the series. </p> <p> the Web is a dynamic and fast-moving space and it should be interesting to keep an eye on this "meta-level" of the API eco-system for some time to come. </p>RESTFest 2015 is Sep 17-19!http://www.amundsen.com/blog/archives/1158http://www.amundsen.com/blog/archives/1158Tue, 12 May 2015 12:47:00 GMT<p> <img src="http://mamund.site44.com/images/restfest-logo.png" align="right" class="inline" /> it's that time of year again! <a href="http://restfest.org" title="RESTFest">RESTFest</a>, one of my favorite geek events of the year, will be happening (once again) in beautiful <a href="http://www.greenvillesc.gov/" title="Greenville, SC">Greenville, SC</a>. The dates of the event this year are Sep 17-19 and there are still <a href="http://www.eventbrite.com/e/rest-fest-2015-tickets-16530825143?ref=mcablog" title="tickets">tickets</a> available. And this year's event is shaping up to be another great combo of hacking, demos, lighting talks and socializing. You can see what last year was like by checking out the <a href="https://player.vimeo.com/video/124577414" title="RESTFest 2015">2015 promo video</a>. </p> <h4>Keynote: IBM's James Snell</h4> <p> we're proud to announce that this year's keynote speaker is <a href="http://twitter.com/jasnell" title="@jasnell">James Snell</a>. i've known James for several years. he's a prolific man and has been involved in editing/authoring several IETF standards including the <a href="https://tools.ietf.org/html/rfc4287" title="RFC4287">Atom Syndication</a> format, the <a href="http://tools.ietf.org/html/rfc5789" title="RFC5789">HTTP PATCH</a> method, and the WC3's <a href="http://www.w3.org/TR/activitystreams-core/" title="Activity Streams 2.0">Activity Streams</a> spec. his keynote, <a href="http://www.restfest.org/speakers" title="Practical Semantics">Practical Semantics</a>, is bound to be excellent. </p> <h4>the RESTFest way...</h4> <p> at RESTFest, we have a <a href="http://www.restfest.org/about">core set of principles</a> that we think helps make for a unique and valuable experience for everyone involved. they boil down to... <dl> <dt>everybody talks</dt> <dd> if you show up, you're delivering a talk! our first principle is "everyone talks and everybody listens." for the past five years, we've stuck to a single track event and that allows everyone to hear *all* the talks, too. we all get to interact and experience the event in the same real-time space. </dd> <dt>less theory, more practice</dt> <dd> theories, formal papers, etc. etc. are all good, but we don't need them at RESTFest. we just want to hear what's on your mind, what you're working on, and what you are interested in talking about. show us your code! </dd> <dt>hacking is good</dt> <dd> day one is "hack day" and each year has a unique theme. anyone can propose a hackday theme and we encourage attendees to submit ideas and come prepared to code in whatever format, style, and framework they love. you can track and contribute to the <a href="https://github.com/restfest/2015-greenville/wiki/Hack%20Day">hackday</a> theme on the wiki. </dd> <dt>dont' be a jerk</dt> <dd> our <a href="http://www.restfest.org/code_of_conduct">Code of Conduct</a> is very simple and very clear. essentially -- "Don't be a Jerk." it is critical that RESTFest be a safe, inviting, and positive experience for everyone. you're free to speak your mind as long as your respectful. </dd> </dl> if this sounds like something you'd enjoy, you're the right person for RESTFest. </p> <h4>Sign Up and Start Interacting NOW</h4> <p> actually, RESTFest has <a href="https://github.com/restfest/2015-greenville/wiki" title="RESTFest Wiki">already started</a>! right now you can sign up at the wiki, add your <a href="https://github.com/restfest/2015-greenville/wiki/People" title="People Pages">people page</a> and introduce yourself to the group. you can keep up on breaking news on our <a href="https://groups.google.com/forum/#!forum/rest-fest" title="Google Groups">email list</a> and secure your place at the event by purchasing one of the limited <a href="http://www.eventbrite.com/e/rest-fest-2015-tickets-16530825143?ref=mcablog" title="Tickets">tickets</a> for RESTFest 2015. if you're realy itching to get connected, drop into our <a href="http://webchat.freenode.net/?channels=restfest">IRC channel</a> on freenode or link to our <a href="http://twitter.com/restfest" title="@restfest">Twitter account</a> and start chatting. </p> <h4>RESTFest is what you want it to be</h4> <p> it's the people who show up each year that make RESTFest such a great event. each year is different and each year is amazing. check out our <a href="https://vimeo.com/channels/restfest2014" title="RESTFest on Vimeo">video channel</a> to see all the talks from the last few years. spots are limited and we'd love to see you there! </p>Learning Client Hypermedia w/ O'Reillyhttp://www.amundsen.com/blog/archives/1157http://www.amundsen.com/blog/archives/1157Mon, 26 Jan 2015 20:54:00 GMT<p> <a href="http://mamund.site44.com/images/2015-01-cj-representor.png" title="Coding a Cj representor for my LCHBook project"> <img src="http://mamund.site44.com/images/2015-01-cj-representor.png" align="right" class="inline" width="200"/> </a> it's official! i've signed an agreement w/ <a href="http://www.oreilly.com/pub/au/1192">O'Reilly Media</a> 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. </p> <p> 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. </p> <p> <a href="http://onlineslangdictionary.com/meaning-definition-of/tbh">TBH</a>, i'm not <i>exactly</i> 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... </p> <h4>Part 1 : Human-Driven Hypermedia Clients</h4> <p> 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. </p> <p> that said, the first part of the book will focus on the process of traveling from a client application that doesn't rely on <i>any</i> hypermedia, through several stages that end with a client that relies <i>primarily</i> on hypermedia information in responses. again, <a href="http://onlineslangdictionary.com/meaning-definition-of/irl">IRL</a> 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. </p> <h4>Part 2: Machine-Driven Hypermedia Clients</h4> <p> ahh, the fun stuff! the <a href="http://en.wikipedia.org/wiki/Holy_Grail">holy grail</a>, the <a href="http://en.wikipedia.org/wiki/Unicorn">unicorn</a> of song and story! </p> <p> or not. </p> <p> 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 <i>program</i> 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. </p> <p> 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' (<a href="http://en.wikipedia.org/wiki/Affordance">affordances</a>) 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.' </p> <p> 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 (<i>"Sorry mate, the pub is closed. But the one up the road is still open."</i>). 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. </p> <p> 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. </p> <p> but they <i>could</i> be. and that's cool. </p> <h4>On the Road Again</h4> <p> 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 <a href="http://www.urbandictionary.com/define.php?term=I%27m+over+it"> putting the thing behind me</a> ;) and i suspect that will be the true this time, too. </p> <p> 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. </p> <p> so, here i go, getting ready to navigate toward the horizon and hopefully recognizing when i get to "done." </p> <p> should be exciting. </p> <p> <i>oops! road sign up ahead. gotta turn here. <a href="http://www.urbandictionary.com/define.php?term=l8tr">L8TR</a>! </i> </p> 2014 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>