POST-traumatic Stress: On Product API Ownership

POST-traumatic Stress: On Product API Ownership

Four years ago, when I was first cutting my teeth with more rigorous technical product management, I wrote an article on my personal blog.

In lieu of a recent conversation, I thought it would be interesting to resurrect the original article and supplement it with some learnings from the years gone by.

The Original Article

Once upon a time, being a product owner was relatively simple. Okay, that’s a lie. More accurately, in the days of “boxed product”, product ownership was largely about features – features which could be easily mapped back to a customer’s stories and use cases.

The implementation of said features largely didn’t matter; Mike wants to convert a nondescript numeric value into a currency value, and as long as the application allows that somehow (ideally in a UX-friendly way), Product was happy.

After all, Product concerns itself first and foremost with the problems and looks to Engineering to provide solutions, albeit with Product ensuring said solutions can adequately address the problems in a manner effective for the business at large.

The advent of software’s increasing API-ification, though, has dramatically blurred the line where business requirements end and where implementation begins. When your customer Mike wants an end-point to convert a numeric value into a currency value, the data he provides and the response he receives are just as much business requirements and acceptance criteria as they are implementation.

So how, then, does one adequately draw the line? Who specs the API? Who owns it post-launch? How does it evolve?

Stick in the CRUD

I wish I had the clear answer to any of those quandaries, as my enterprise day job would be easier for it.

In start-ups and small companies, this kind of collaboration is a breeze, and as such these types of ownership issues are usually non-existent. Making this work with one Product Owner and one Lead Engineer is as easy as a lunch and a beer.

But in an enterprise company, I can’t begin to feel certain or even falsely confident in the correct approach; I’ve encountered only issues and no resolutions in my experience thus far.

In some enterprise circumstances, the line in the sand is clear. If your customer isn’t consuming an API as his UX (or, as I prefer, “DX”) it probably doesn’t make sense for Product to own the API, as it is truly an implementation detail.

However, with services leaning more towards integrations and service-to-service interactions, particularly in service-oriented architectures, this is increasingly rare.

A “GET”, then, is as essential to the ability of a given product to satisfy business requirements as is the need for a specific set of UX interactions which enforce a workflow.

Unfortunately, this makes translating requirements into stories difficult, as writing the right API requires fully understanding the interactions between services, or rather, the passage and manipulation of data and the application of business logic. In other words, writing a good API requires understanding a great many “implementation details”.

Giving and GETing

By necessity, it follows that Product starts to dabble in architecture and Engineering starts to dabble in stories and acceptance criteria – a situation neither party is comfortable with, at least in my experience.

Invariably, Product, who isn’t as technically adept and isn’t privy to all the technology discussions, messes up its API design or makes short-sighted implementation decisions. Meanwhile, Engineering, having not talked directly to the customer or lacking visibility to the long-term business strategy and product roadmap, fails to meet critical business requirements and acceptance criteria.

Neither team has all the information it needs to do the end-to-end job, and, because of the overlapping responsibilities and ultimate contractual artifact in the API, being pivotal to writing the stories and predicated on a concrete architecture, work is stymied by murky owners and unclear action items.

Socket To Me

So yea. We have a lot of issues, and we’ve no clear resolutions.

I’m left thinking about a parallel, analogical scenario. If a product organization today was asked to design the electric plug for a piece of hardware, who would own the plug’s design?

• The plug has a clear customer – the socket.
• The socket, the plug’s customer, expects a certain input and provides a certain output.
• The socket, the plug’s customer, abides by a structured, common standard.
• The plug’s design and its usage are interdependent and interrelated.
• The plug’s design necessitates certain aspects of its implementation.

In this case, I believe the answer is clear: both Product and Engineering own the plug, its design, and its implementation. There cannot be a delineation because the requirements imply certain aspects of implementation. It’s pretty clear.

And yet, not clear at all is how the two teams then work, in concert, to build it.

That’s a question I’m hungrily seeking the answer to – and one, I suspect, almost every software company out there building enterprise APIs is seeking, too.

Upon Reflection Years Later

In the years since I’d originally published this article, I’ve begun to believe more firmly in a singular stance: a technical product manager should own the API spec.

Part of the value of a product manager is in being passionately dispassionate about the product and the solution. Just as customers are often too close to the problem to be able to articulate what they need in place of what they say they want, so too can be developers.

By taking the ownership for defining the actual interface for integration, technical product managers are forced to truly understand, and internalize, the developer use case that they are trying to facilitate while being a degree of separation away from the technology itself.

Without any implicit bias or preference for a specific solution, then, the technical product manager, who is one degree removed from the consumption of the API, is able to make a more dispassionate recommendation by aggregating feedback from the customer developer as opposed to imbuing preferences or biases from the internal developer.

The same principle applies to user experience design. A UX designer of a restaurant POS, for example, may not be a restaurant server, but the process of research, design, testing, and iteration ensures that she can represent the requirements dispassionately and intelligently.

Providing the technical product manager is able to properly canvas the customer developer directly or customer developer community indirectly, he or she is then in a better position to represent the external requirements.

Then again, I guess GraphQL is going to render all of this old conversation moot, anyway, won’t it?