Model Actions, Not Data
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.
But…
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)!