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.

Yes, looks like some SEO-centric article to push organic traffic for the company who's doing something with APIs.

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.

This is the kind of task where I feel like GraphQL should shine in theory.

In practice, it feels like we don't really have good tooling for this kind of stuff, and you end up writing everything DIY. There are also some annoying limitations in the GraphQL schema and query languages, so you might end up wanting to compile/generate those from something else. The promises there, but the implementation is quite a headache without proper tooling/library/framework support.