Lets talk about API governance (in the enterprise).

[Joyce Stack]

Or not as it seems to be the case in this thread :-)  

I've been asked to think about some of this from our senior architect and I'm looking for some inspiration. 

We are a large distributed organisation and so we need improve our API governance processes. I came across Kin's blog post on this which is very inspiring. 

Now we need to protect the $$$ so we could use a big stick approach and rule by fear but that's not fun or practical. A recent introspection of product managers and developers highlighted some inhibitors around lack of governance and standards (we have some standards but nothing really official) 

God punishes you by answering your prayers so we should get some GOVERNANCE. OK...now what? 

Knowledge / areas I'm seeking: 

• Metrics - whats useful to highlight exemplars and causes of concern? 
• Whats the lightest touch way to start? I don't want a checklist of 500 things that people need to follow.  
• People: how to you get people to care? Do you have API stewards from each domain / context? Do internal (fun) competition like badges awarded for being compliant work or piss everyone off? 
  
• How do you incentivise teams? We all know when the delivery deadline creeps up that stuff like this gets dropped. 
• How to roll it out iteratively? We want to avoid costly quality gates at the end of every week / month. 
  
• Is it realistic to stop products being pushed to production because of not passing governance? We all have cases in our enterprise where we may have pushed something critical to production with a security vulnerability because "we'll come back to that later" * 
• Tools for automation.....? We are not going to outsource it to Akana or apigee etc so whats out there that we could use. 

* this is just a cynical example and not to be construed as a practice by our company.   

Thanks and have a good weekend. 

[Eric Johnson]

Having worked on products in the "governance" space before, there's a problem at the core. Some people, when they hear "governance", they think "control". What everyone needs, instead, is "management". Adept management identifies problems, and corrals the people involved to figure out a solution.

A key benefit of RESTful, JSON-based APIs comes from three characteristics:

• The understanding that if you see data you don't recognize, just ignore it (be lenient in what you accept)
• JSON doesn't have notions of namespace, and therefore it is obvious to everyone that the data coming from a given service is specific to that service. This means you don't spend insane amounts of time coming up with a canonical definition of customer. At worst, you spend time finding a canonical identifier for a customer, and everything else can be different.
• Think about domain concepts, rather than verbs

Why is this a key benefit? Because it requires less control, and less management.

Focus on metrics that cost your customers time & money, and metrics that slow down your development teams. Only pick a few, perhaps no more than five. And push them relentlessly.

If you've got externally facing Web APIs, these metrics occur to me:

• How many different ways does your company have to support querying ranges?
• How many different ways does your company represent the "metadata" in a JSON response?
• How many different ways does your company provide API descriptions (Swagger, none, etc...)
• How many times have API changes been backwards incompatible in the past six months? (I'm assuming you support the old version of the APIs, of course)
• ...

You could apply the same metrics to internal APIs, but also add some, like:

• After you've identified a baseline document for customer facing APIs, how long is the document for each team that creates APIs that differ from the customer-facing standards? (This is a measure of how hard it will be for a person to switch from one team to another within your company.)

Once you have the metrics, just keep publishing them, and keep putting them in front of management high-enough to cover all the relevant teams. If management doesn't care about the metrics you've identified, find new ones, and push those instead.

Eric.

[Joyce Stack]

This is awesome thank you. 

Ah yes I forgot to add that we have some external APIs but the primary focus is on internal APIs at the moment. 

I see the role of such a person as someone who can identify reusing capabilities across the organisation and no building single purpose APIs - getting folks to focus on the long term and other clients and use cases. 

Thanks again 

[Jørn Wildt]

InfoQ has recently published some interesting articles on PayPal's take on this. See https://www.infoq.com/articles/paypal-api-first-part1, https://www.infoq.com/articles/paypal-api-first-part2 and https://www.infoq.com/articles/paypal-api-first-part3

/Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[MattM]

Yes, those PayPal articles are great! We (the API Academy) have researched this topic a lot. In our experience, the carrot is much more powerful than the stick as you point out. Here are some resources that address governance for APIs and microservices...

Blog from Mike Amundsen - http://www.apiacademy.co/three-keys-to-runtime-governance/
Check out the Amundsen and Reinhardt videos here - http://transform.ca.com/API-Microservices-Best-Practices-API360-Summit-Videos.html
A Webinar I did on API Governance in the Enterprise - https://www.youtube.com/watch?v=LNn_TL4Oz5o&t=262s

We also get into governance quite a bit in Chapter 7 of our Microservice Architecture book... Here: https://www.safaribooksonline.com/library/view/microservice-architecture/9781491956328/ or here: http://transform.ca.com/API-microservice-architecture-oreilly-book.html

Feel free to reach out if you would like to discuss more.

Thanks, m@

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.