i'm very proud to announce that InfoQ has just released a new series that I helped edit. the series is called Description, Discovery, and Profiles: The Next Level in Web APIs and the contents of this series has a series of excellent contributing authors including Ronnie Mitra of API Academy/CA, Mike Stowe with Mulesoft, Kin Lane of API Evangelist fame and, Mark Foster from Apiary. it also includes interviews with Swagger creator Tony Tam and Profile RFC editor Erik Wilde. and it's packed with material covering what i think are three key patterns/technologies in the Web API space:
- "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."
- "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."
- "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."
lots of vendors and technologies here
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:
- API Blueprint
- Visual Studio
- I/O Docs
- API Commons
- Programmable Web's API Directory
- Mashery's API Network
- Apache Zookeeper
- HashiCorp Consul
- CoreOS etcd
- Rapido API Designer
- Spring Data
and that's just in the first article in the series!
here's a quick rundown of all the articles that will br released between late May and early July:
Description, Discovery, and Profiles: A Primer
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.
From Doodles to Delivery : An API Design Process
Ronnie Mitra investigates what good design is and how using Profiles along with an iterative process can help us achieve it.
The Power of RAML
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.
APIs with Swagger : An Interview with Reverb's Tony Tam
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.
The APIs.json Discovery Format: Potential Engine in the API Economy
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.
Profiles on the Web: An Interview with Erik Wilde
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.
Programming with Semantic Profiles : In the land of magic strings, the profile-aware is king.
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.
A Resource Guide to API Description, Discovery, and Profiles
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.
looking forward to the weekly releases
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.
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.
it's that time of year again! RESTFest, one of my favorite geek events of the year, will be happening (once again) in beautiful Greenville, SC. The dates of the event this year are Sep 17-19 and there are still tickets 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 2015 promo video.
Keynote: IBM's James Snell
we're proud to announce that this year's keynote speaker is James Snell. i've known James for several years. he's a prolific man and has been involved in editing/authoring several IETF standards including the Atom Syndication format, the HTTP PATCH method, and the WC3's Activity Streams spec. his keynote, Practical Semantics, is bound to be excellent.
the RESTFest way...
at RESTFest, we have a core set of principles that we think helps make for a unique and valuable experience for everyone involved. they boil down to...
- everybody talks
- 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.
- less theory, more practice
- 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!
- hacking is good
- 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 hackday theme on the wiki.
- dont' be a jerk
- our Code of Conduct 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.
Sign Up and Start Interacting NOW
actually, RESTFest has already started! right now you can sign up at the wiki, add your people page and introduce yourself to the group. you can keep up on breaking news on our email list and secure your place at the event by purchasing one of the limited tickets for RESTFest 2015. if you're realy itching to get connected, drop into our IRC channel on freenode or link to our Twitter account and start chatting.
RESTFest is what you want it to be
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 video channel to see all the talks from the last few years. spots are limited and we'd love to see you there!
it's official! i've signed an agreement w/ O'Reilly Media to write a book focused on creating hypermedia clients. i've been putting this project off for a couple years and am glad i finally will be sitting down to cull through the collected material and work to put it into a (hopefully) useful presentation.
i've spent several weeks coding up lots of examples of hypermedia clients; experimenting with several existing media types and even some profiles. i've also been working through common patterns that make working w/ message-oriented services easier to handle for client apps. i have learned quite a bit over the last couple years of talking w/ people and assisting on various projects both large and small. and now it's time to see if i can find a coherent story in all that experience.
TBH, i'm not exactly sure where this one will lead, but i have a decent plan to follow before i start out toward the horizon. i won't belabor the details here but will pass along my general outline to give folks a feel for where i am trying to go...
Part 1 : Human-Driven Hypermedia Clients
i'll be keeping discussions of human-driven and (i'll say) machine-driven clients clearly separated in the book. not because there is always a clear line between then in real life (think parsers designed to prefetch content based on inline instructions, etc.) but because it makes the conversation a bit easier.
that said, the first part of the book will focus on the process of traveling from a client application that doesn't rely on any hypermedia, through several stages that end with a client that relies primarily on hypermedia information in responses. again, IRL there is a wide range of hypermedia in client apps for the Web (images anyone?) but this kind of approach will, i think, help bring some things into focus.
Part 2: Machine-Driven Hypermedia Clients
similar to part 1, i'll use the second half of the book to focus only on challenges related to creating hypermedia clients that don't rely directly on human intervention for each request. of course, humans will program them, but then -- at least for some level of interaction -- leave the machine to do their own thing. and that's where it gets fun.
i'll talk about how we can build a client that has the power to do basic interaction (independent request/response), how machines can be "taught" to safely navigate a selected part of the WWW environment, how they can recognize 'things' (affordances) along the way, and how to use those things as tools to manipulate the local environment. finally, i'll talk about how a client can be taught to recognize a 'goal' or 'end-state.'
in real life, humans do this kind of stuff every day. we navigate through traffic, recognize road signs/signals and are able to figure out when we reach our destination -- even if it is not the destination we had in mind at the start of our journey ("Sorry mate, the pub is closed. But the one up the road is still open."). we also go through these kind of scenarios in a more abstract or indirect way, such as when deciding we're done exercising, had enough to eat, or have collected enough trading cards to make a complete set.
it turns out, none of the cases i mentioned above require much "intelligence" or "reasoning." just the ability to pay attention to details and identify "done." and there are very many instances where this level of execution would be useful over the Web today. unfortunately, even these simple kinds of machine execution are not often supported when implementing services for the Web -- and that's a bummer.
but they could be. and that's cool.
On the Road Again
so, the next few months should be quite interesting. i always enjoy starting out on one of these adventures and this time is no different. i should also confess that i really enjoy getting to the end of a book project and putting the thing behind me ;) and i suspect that will be the true this time, too.
an added wrinkle is that i start traveling again in february and that usually takes a toll on deadlines. for that reason, i'll be drawing this project out a bit more. i hope to have the first draft completed by early summer and have it all wrapped up and out the door by fall 2015.
so, here i go, getting ready to navigate toward the horizon and hopefully recognizing when i get to "done."
should be exciting.
oops! road sign up ahead. gotta turn here. L8TR!
yep - it's official! i'll be traveling the Pacific in late October and early November to present the CA API Academy sessions on "How to Implement a Successful API Strategy." along the way, i'll be visiting the following cities:
i'm really excited about this trip because this time i am re-writing all my presentation content for the API Strategy Workshops. Instead of just collecting up the most popular content from our very successful API training program, this time i am pulling together content from each of our incredibly talented API Academy team members and highlighting the key insights each of them have on the major topics we're often asked when working with our customers.
preparing this content is a real thrill for me because it's a chance to show people examples from the wide range of expertise and experience in the API Academy. it's also a bit duanting since i need to try to get up to speed on all the things our Academy folks have been working on in the last year.
here's what i have planned for the upcoming workshops
Apps, APIs and the Enterprise: Enabling The Future of the Web
The growing explosion of mobile devices on the Web means applications will continue to become smaller and more numerous, deployment cycles will keep getting shorter, and the speed of innovation will increase. At the same time, product teams are getting smaller and more distributed making project management more challenging than ever. Succeeding in this constantly evolving environment requires more than speed, it takes agility, planning, leadership and the ability to act quickly and decisively.
Join me for a half-day workshop where we explore:
- Rewriting Business
- Refocusing your Business through Apps and the API Economy
- Rewriting Software
- Harnessing the Power of the Cloud and Mobile
- Rewriting Process
- Using DevOps to transform your Infrastructure
- Rewriting the Future
- Rethinking Governance and Reducing the Cost of Change
it's going to be a great experience and i hope you will join me as we review key business, software, process, and governance issues facing IT departments today and into the future.See you on the road!
this week i had the opportunity to deliver a "lightning talk" at the APIStrat Tech Un-Workshop at Gluecon 2014 . the event was focused on two key topics: IoT and Service Description and Discovery. i was in the Service Description/Discovery track and delivered a talk called "Mapping the API Landscape" (slides). i won't cover the entire talk here (the text BTW has lots of links to information i could not discuss on stage this week) but did want to hit some key points.
what Google's self-driving car tells us
the "gCar" has been in the news again and a key point that was disussed at some length in these articles was the fact that the car depends on a very detailed map of the roadways. in fact, the car currently can only drive in the Mountain View, CA area since that is the only landscape that is mapped well enough for the car to navigate.
so, the Google car does not "discover" anything while drivig. it actually recognizes intersections, traffic lights, etc. through a special representation of the landscape that contains all the right annotations. this reliance on a known map allows the car to navigate successfully between two points within that landscape. this is no simple feat, of course. reacting to surroundings "at speed" takes serious computing power and that's one of the things that makes the Google implementation so amazing.
Norman's Action Lifecycle
the process of navigating from A to B is a goal-driven process that we see very often in nature. ants, micro-organisms, etc. all do this. HCI expert, Donald Norman calls this process the Action Lifecycle or Seven Stages of Action .
this is how we learned to write GUI intefaces, too. wait for a keystroke or button-click, process that action, affect the UI, then allow the user to evaluate the changes and decide if another action is needed. we build Web servers like this, too. wait for a request, process it, modify the back-end (if needed) and reflect results back to the requestor. game programming works like this, too. but it's rare to see "Web Clients" written this way. they continue to look like single-minded bots that just "go from A to B" and ignore landmarks; incapable of actually reacting to surroundings.
client apps and web maps
why are most web client apps "one-off" implementations that are likely to break over time? because client dev's don't have decent "maps" of the Web landscape. and good maps are not just "photos" of the surroundings, but heavily annotated representations with recognizable symbols and landmarks. most servers today just belch out JSON or XML with almost no recognizable symbols or signage (e.g. hypermedia controls, etc.).
so what we need to do is create maps for devs to use so that they can build their own client applications and solve their own problems. client apps should be free to follow whatever route within that map that they wish -- not just follow the path that server developers decide upon.
let's make maps!
things like Service Description formats, and discovery protocols are all ways to start creating more maps for client devs to rely upon. using hypermedia in responses provides the symbols and signs client apps can use at runtime (like the Google car) in order to navigate in realtime.
there are several description formats (see my paper Hold your Nose vs. Follow your Nose for more on this). in the book, RESTful Web APIs Leonard Richardson and i list close to 20 options for expressing hypermedia in Web responses. and more have come online since the book was published last year.
we have all we need. we just need to make more maps!