Aligning on Your API Design Using Jobs to Be Done

Found this rather hand wavy personally. As an alternative resource on the same topic I got a huge amount of value out of Google’s documentation on API design

https://cloud.google.com/apis/design and https://google.aip.dev/

I’m not sure who the audience is supposed to be. This feels like something a non-technical manager will read and suddenly feel empowered to make technical implementation decisions. It even comes with a handy acronym (ADDR) that can slip its way into corporate jargon.

I’m personally a big fan of the Odata way of doing APIs, especially because they sort of write themselves according to your data model and basically works on anything where a full graph api would be overkill.

The one thing these articles never really deep dive into is access control, however, and that’s probably the area I personally need the most guidance on. Maybe that’s just me, but in this new GDPR world where every piece of data is basically categorised what I’ve found my teams to need to most is a best practice for linking data to employee functions and roles.

The Google api for gmail is sort of the good example. “Your messages” -> “your data”, but what happens when employees performing different functions in different parts of the organisation needs to access the same data but with different access to specific fields in it? Say you have 100 asset managers who each manage 50 things. They all have access to the overall data on all the things, but then they each have restricted access to the financial data on the specific things they manage.

You can link an asset manager to a thing, but you need to do it in a way that allows the asset manager role to change employee, without anyone actually going in to change “Mark” to “Hannah” manually when mark finds a new job.

That sort of hell is what I need best API practices for.