I've not blogged in quite a while here -- lots of reasons, none of them sufficient. So, today, i break the drought with a simple rant. Enjoy -- mca
It is really encouraging to see so many examples of companies and even industries spending valuable resources (time, money, people) on efforts to define, implement, and advocate for "open" APIs. in the last few years i've seen a steady rise in the number of requests to me for guidance on how to go about this work of creating and supporting APIs, too. And i hear similar stories from other API evangelists and practitioners up and down the spectrum from startups to multi-nationals. And, like i said, it is encouraging to see.
Even though i've been quite explicit in my general guidance through lots of media and modes (interviews, presentations, even full-length books), it is frustrating to see many people continue to make the same simple mistakes when going about the work of designing and deploying their APIs. so much so, that i've decided to "dis-hibernate" this blog in order to squawk about it openly.
And chief among these frustrations is the repeated attempts to design APIs based on data models. Your database is not your API! Stop it. Just stop.
Unless you are offering API consumers a SaaS (storage-as-a-service) you SHOULD NOT be using your data model as any guide for your API design. Not. At. All.
Arthur Jensen (In a loud, angry voice): "You are messing with the primal forces of nature Mr. Beale. And YOU! WILL! ATTONE!"
(Arthur pauses and leans in to whisper in Beale's ear)
Arthur: "Am I getting through to you, Mr. Beale?"
When you cast about for a handle on how to go about designing your API, the answer is straightforward and simple: Model your Actions.
It can't be stated any more directly. Model your Actions.
Don't get caught up in your current data model. Don't fall down the rabbit hole of your existing internal object model. Just. don't.
Need more? Here's a handy checklist:
- Start with a list of actions to be completed. (Jobs To Be Done) -- if that sparks your brain.
- Determine all the data elements that must be passed when performing that action.
- Identify all the data elements to be returned when the action is performed. Be sure to account for partial or total failure of the attempted action.
- Rinse and repeat.
Leonard Richardson and I offer up a long-form description of this four-step plan in our book "RESTful Web APIs".
Once you feel good about your list of actions and data points (input and output), collect related actions together. Each collection identifies a context. A boundary for a component. That might sound familiar to some folks.
Now you have an API to implement and deploy. When implementing this API, you can sort out any object models or data models you want to use (pre-existing or not). But that's all hum-drum implementation detail. Internal stuff no one consuming the API should know or care about.
All they care about are the possible actions to perform. And the data points to be supplied and returned.
That's it. Simple.
Of course, simple is not easy.
"I would have written a shorter letter but I just didn't have the time."
-- various attributions.
now, if a simple rant is not enough, i offer up an epigram i first shared publicly back in 2016:
remember, when designing your #WebAPI, your data model is not your object model is not your resource model is not your message model #API360
And if a single epigram is not motivation enough, how about a whole slide deck from APIStrat 2016 devoted to explaining that simple phrase?
Now, armed (again) with this clear, simple advice, you're ready to avoid the debacle of data-centric industry-wide APIs.
just go out there and take action (not data)!
there just a few days left before my live O'Reilly Implementing Hypermedia online tutorial on february 9th (11AM to 5PM EST). and i'm spending the day tweaking the slides and working up the six hands-on lessons. as i do this, i'm really looking forward to the interactive six hour session. we'll be covering quite a bit in a single day, too.
most of the material comes from my 2011 O'Reilly book Building Hypermedia APIs with HTML5 and Node. however, i've added a few things from RESTFul Web APIs by Leonard Richardson and even brought in a few items from my upcoming book RESTful Web Clients.
the high-level topics are:
- Designing a Hypermedia API
- Using the DORR Pattern for Coding Web APIs
- Understanding the Collection+JSON Media Type
- Building Hypermedia SPA Clients
by the time the day is done, everyone will have a fully-functional Hypermedia API service up and running and a Cj-compliant general-pourpose hypermedia client that works w/ ANY Web API that supports the Collection+JSON media type.
Greenville Hypermedia Day
the tutorial is geared toward both individual and team participation. i know some companies are arranging a full-day session with their own dev teams for this, too. and i just heard about a cool event in Greenville, SC for people who want to get the "team" spirit...
i found out that Benjamin Young is hosting a Hypermedia Day down in Greenville, SC on feb 9th. If you're in the area, you can sign up, show up, join the tutorial in progress, and chat it up w/ colleagues. I know Benjamin from our work together for RESTFest and he's a good egg w/ lots of skills. He'll be doing a Q&A during the breaks in the tutorial modules and i think he might have something planned as an "after-party" thing at the end of the day.
if you're anywhere near Greenville, SC on feb-09, you should join Benjamin's Hypermedia Day festivities!
cut me some slack
i know most of the attendees are going "solo" -- just you, me, and the code -- that's cool. O'Reilly is hosting a live private Slack channel for everyone who signs up for the tutorial. I'll be around all day (and probably some time after that, too) so we can explore the exercises, work out any bugs, and just generally chat.
it's all ready!
so, as i wrap up the slides, the hands-on lessons, the github repo, and the heroku-hosted examples, i encourage you to sign up and join us for a full day of hypermedia, NodeJS, and HTML5.
see you there!
the week of january 11th i'll be in Dallas for two events. this is my first trip of 2016 and i'm looking forward to catching up w/ my Dallas peeps. I'll be visiting with the great folks at DFW API Professionals on Jan-13 and addressing a gathering of Dallas-area IT dignitaries at AT&T Stadium during the day on the 14th.
DFW API Professionals
i've known Traxo's Chris Stevens for several years and, when i learned i would be in Dallas in January, we were able to arrange an oppty for me to address his meetup group: DFW API Professionals. I'll be talking about and demoing hypermedia API client coding patterns and taking questions, too. check out the event and, if you can, join me and the whole DFW API Pro membership.
API Management Best Practices Discussion
on thursday, i'll be at the AT&T Stadium with my fellow CA colleagues and folks from Perficient to join in the discussion on API mgmt and a look into the near future. i get to share the podium w/ CA SVp and Distinguished Engineer, Scott Morrison. in a lively open discussion (no slideware), we'll be covering API design, deployment, DevOps, Microservices, and IoT with Perficient's Director of Emerging Platform Solutions, Annel Adzem. stellar conversation, stunning view of the field -- what's not to like?
just the beginning
of course, this is just the start of my travels for 2016. i've already got the cities of Vancouver, Washington DC, E. Brunswick, Seoul, Tokyo, Melbourne, Sydney, San Francisco, Sao Paulo, Rio, Buenos Aries, and New York on my agenda. and that's just the first few months of 2016!
gonna be another great year with the API Academy! if you're anywhere near those cities, keep in touch and i hope we meetup sometime soon.
With apologies to McIlroy, Pinson, and Tague.
A number of maxims have gained currency among the builders and users of microservices to explain and promote their characteristic style:
(i) Make each microservice do one thing well. To do a new job, build afresh rather than complicate old microservices by adding new features.
(ii) Expect the output of every microservice to become the input to another, as yet unknown, microservice. Don't clutter output with extraneous information. Avoid strongly-typed or binary input formats. Don't insist on object trees as input.
(iii) Design and build microservices to be created and deployed early, ideally within weeks. Don't hesitate to throw away the clumsy parts and rebuild them.
(iv) Use testing and deployment tooling (in preference to manual efforts) to lighten a programming task, even if you have to detour to build the tools and expect to throw some of them out after you've finished using them.
this is my ring of keys -- just three of them: work, home, car. i've been focusing over the last couple years on reducing. cutting back. lightening my load, etc. and the keys are one of my more obvious examples of success.
i've also been trying to lighten my load cognitively -- to reduce the amount of things i carry in my head and pare things down to essentials. i think it helps me focus on the things that matter when i carry less things around in my head. that's me.
staring at my keys today lead me to something that's been on my mind lately. something i am seeing quite often when i visit customers. the approach these companies use for governing their IT development lack the clarity and focus of my "three keys." in fact, most of the time as i am reading these companies' governance documents, they make me wince. why? because they're bloated, over-bearing, and -- almost all of them -- making things worse, not better.
over-constraining makes everyone non-compliant
i am frequently asked to provide advice on design and implementation of API-related development programs -- most often APIs that run over HTTP. and, in that process, i am usually handed some from of "Design-Time Governance" (DTG) document that has been written in-house. sometimes it is just a rough draft. sometims it is a detailed document running over 100 pages. but, while the details vary, there are general themes i see all too often.
- Constraining HTTP
- almost every DTG approach i see lists things like HTTP methods (and how to use them), HTTP response codes (and what they mean), and HTTP Headers (including which new REQUIRED headers were invented for this organization). all carefully written. and all terribly wrong. putting limits on the use of standard protocols within your organization means every existing framework, library, and tool is essentially non-compliant for your shop. that's crazy. stop that! if your shop uses HTTP to get things done, just say so. don't try to re-invent, "improve", or otherwise muddle with the standard -- just use it.
- Designing URLs
another thing i see in DTG documents is a section outlining the much-belabored and elaborate URLs design rules for the organization. Yikes! this is almost always an unnecessary level of "bike-shedding" that can only hold you back. designing URLs for your org (esp. large orgs) is a fool's errand -- you'll never get it right and you'll never be done with it. just stop. there are more than enough agreed standards on what makes up a valid URL and that's all you need to worry about. you should resist the urge to tell people how many slashes or dashes or dots MUST appear in a URL. it doesn't improve anything.
look, i know that some orgs want to use URL design as a way to manage routing rules -- that's understandable. but, again, resist the urge to tell everyone in your org which URLs they can use for now and all eternity. some teams may not rely on the same route tooling and will use different methods. some may not use routing tools at all. and, if you change tooling after five years, your whole URL design scheme may become worthless. stop using URLs as your primary routing source.
- Canonical Models
- i really get depressed when i see all the work people put into negotiating and defining "canonical models" for the organization. like URL designs, this always goes badly sooner or later. stop trying to get everyone/every-team to use the same models! instead, use the same message formats. i know this is hard for people to grasp (i've seen your faces, srsly) but i can't emphasize this enough. there are several message formats specifically designed for data transfer between parties. use them! the only shared agreement that you need is the message format (along with the data elements carried in the message).
- Versioning Schemes
- here's one that just never seems to go away -- rules and processes for creating "new versions" of APIs. these things are a waste of time. the phrase "new version" is a euphemism for "breaking changes" and this should never happen. when you build sub-systems that are used by other teams/customers you are making a promise to them that you won't break things or invalidate their work (at least you SHOULD be making that promise!). it is not rocket-science to make backward-compatible changes -- just do it. once you finally accept your responsibility for not breaking anyone using your API, you can stop trying to come up w/ schemes to tell people you broke your promise to them and just get on with the work of building great software that works for a long time.
so, stop constraining HTTP, stop designing URLs, stop trying to dictate shared models, and forget about creating an endless series of breaking changes. "What then," you might ask, "IS the proper focus of design-time governance?" "How can I actually govern IT systems unless I control all these things?"
three keys form the base of design-time governance
ok, let me introduce you to my "three keys of DTG". these are not the ONLY things that need the focus on IT governance, but they are the bare minimum -- the essential building blocks. the starting point from which all other DTG springs.
- Protocol Governance
first, all IT shops MUST provide protocol-level governance. you need to provide clear guidance and control over which application-level protocols are to be used when interacting with other parts of the org, other sub-systems, etc. and it is as simple as saying which protocols are REQUIRED, RECOMMENDED, and OPTIONAL. for example...
"Here are BigCo, Inc. all installed components that provide an API MUST support HTTP. These components SHOULD also support XMPP and MAY also support CoAP. Any components that fail to pass this audit will be deemed non-compliant and will not be promoted to production."
you'll notice the CAPITALIZED words here. these are all special words taken from the IETF's RFC2119. they carry particular meaning here and your DTGs SHOULD use them.
- Format Governance
another essential governance element is the message formats used when passing data between sub-systems. again, nothing short of clear guidance will do here. and there is no reason to invent your own message-passing formats when there are so many good ones available. for example...
"All API data responses passed between sub-systems MUST support HTML. They SHOULD also support one of the following: Collection+JSON, HAL, Siren, or UBER. sub-systems MAY also support responses in Atom, CSV, or YAML where appropriate. When accepting data bodies on requests, all components MUST support FORM-URLENCODED and SHOULD support request bodies appropriate for related response formats (e.g. Collection+JSON, Siren, etc.). Any components that fail to pass this audit will be deemed non-compliant and will not be promoted to production."
you'll notice that my sample statement does not include TXT, JSON or XML as compliant API formats. why? because all of them suffer the same problem -- they are insufficiently structured formats.
- Vocabulary Governance
the first two keys are easy. have a meeting, argue with each other about which existing standards are acceptable and report the reusults. done. but, this last key (Vocabulary Governance) is the hard one -- the kind of work for which enterprise-level governance exists. the one that will likely result in lots of angry meetings and may hurt some feelings.
there MUST be an org-level committee that governs all the data names and action names for IT data transfers. this means there needs to be a shared dictionary (or set of them) that are the final arbiter of what a data field is named when it passes from one sub-system to the other. managing the company domain vocabulary is the most important job of enterprise-level governance.
the careful reader will see that i am not talking about governing storage models or object models here -- just the names of data fields passed within messages between sub-systems. understanding this is most critical to the success of your IT operations. models are the responsibility of local sub-systems. passing data between those sub-systems is the responsibility IT governance.
what about all those "ilities"?
as i mentioned at the opening, these three keys form the base of a solid DTG. there are still many other desirable properties of a safe and healthy IT program including availability, reliability, security, and many more. this is not about an "either/or" decision ("Well, I guess we have to choose between Mike's three keys and everything else, right?" -- ROFL!). we can discuss the many possible/desirable properties of your IT systems at some point in the near future -- after you implement your baseline.
so, there you have it. protocol, format, vocabulary. get those three right and you will be laying the important foundation for an IT shop that can retain stability without rigidity; that can adapt over time by adding new protocols, formats, and vocabularies without breaking existing sub-systems or ending up in a deep hole of technical-debt.