Three Keys to Design-Time Governance
Three Keys to Design-Time Governance
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 fewer things around in my head. That’s me.
Staring at my keys today led 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 lacks the clarity and focus of my “three keys”. In fact, as I read these companies’ governance documents, they often make me wince. Why? Because they’re bloated, overbearing and often 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. In that process, I am usually handed some form of “design-time governance” (DTG) document that has been written in-house. Sometimes it is just a rough draft. Sometimes it is a detailed document running over 100 pages. But, while the details vary, there are general themes I see all too often.Constraining HTTPAlmost 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 URLsAnother thing I see in DTG documents is a section outlining the much-belabored and elaborate URL design rules for the organization. Yikes! This is almost always an unnecessary level of “bikeshedding” that can only hold you back. Designing URLs for your organization (especially in large organizations) 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.(I know that some organizations 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 organization 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 Object ModelsI 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 models. I know this is hard for people to grasp (I’ve seen your faces, seriously) 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 – see below).Versioning SchemesHere’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 almost always just a euphemism for “breaking changes” and that 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 with schemes to tell people you broke your promise to them and you can 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 object 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 you need to focus on in IT governance but they are the bare minimum. The essential building blocks. The starting point from which all other DTG springs.Protocol GovernanceFirst, all IT shops MUST provide clear guidance and control over which application-level protocols are to be used when interacting with other parts of the organization, other sub-systems etc. And it is as simple as saying which protocols are required, recommended and optional. For example…“Here at 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 GovernanceAnother 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 GovernanceThe first two keys are easy. Have a meeting, argue with each other about which existing standards are acceptable and report the results. Done. But the 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 maybe even a few hurt feelings. There MUST be an organization-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) as 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 modelshere – 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!). Those many possible/desirable properties of your IT systems can be a topic of discussion after you implement your baseline.
So, there you have it. Protocol, Format, Vocabulary. Get those three right and you will be building and managing 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.
Those are the keys to a successful design-time governance plan.
(This post was originally published on my personal blog.)