Determining the appropriate Governance processes for an API initiative is not easy. There are camps inside the company that tend to pull in conflicting directions. Some focusing on the desire for speed will drive toward very little governance, while other parts of the company who are currently managing traditional IT governance processes will want the API initiative to fit into the existing model. As you might expect the best approach is somewhere in the middle.
When we talk about Governance, what exactly do we mean? Governance covers both business and technical areas (I’ll cover technical a little later). From a business perspective we are looking at topics such as:
- API Identification – probably one of the most important aspects. Creating compelling consumable APIs goes a long way to driving success. Putting appropriate roles, organization, and methodology to identify good APIs is extremely important. In addition, understanding the API portfolio and a good attempt to drive reuse are also helpful.
- Versioning – creating backward compatible APIs (as much as possible) and having a strategy for how to handle non-backward compatible APIs. See my versioning blog. Versioning is both a business and technical issue. Poor versioning can hurt the desirability of your APIs
- API Access (security) – establishing who can access each API (business asset) and setting up the visibility and security enforcement around the API.
- Entitlement and Enforcement – are the APIs going to be rate limited and if so is the enforcement of the rate limit going to be hard or soft?
- Monetization – a very large topic in itself, covered in a blog and white paper. Deciding upon the business model and setting up the monetization capability required and measurements are part of what needs to be decided.
- Privacy – ensuring Consumer privacy – Apps need to be validated to be sure they are allowed to
access the API, User identity for the App user must be secured so that the App itself does not have access to the user’s credentials and User identity must pass into the systems of record to ensure only that user’s data is accessed. Also ensuring Organization privacy – Organizations that consume the same API may be competing with one another and should not be able to see another organization’s customers or data.
- Legal – ensuring proper usage of corporate assets, especially when assets are being used by other businesses. Be prepared to answer:
- Do you own the data you are providing?
- Are all audiences entitled to access this data?
- What rights are you granting the consumer of the API to
use the data provided?
- What is the required policy for data retention?
- What requirements do you have for attribution of the content or use of your brand? Do you need to give attribution to some other entity?
- How will you find out and deal with consumers who do not use the API appropriately?
- What are your liabilities?
- Measurements – establishing success criteria, metrics to be collected and implementation of the gathering and communication of these metrics. (see Analytics).
Most businesses start their API initiatives focused on internal consumers (their own employees or contractors), then move to partner models, and finally to public API consumers. As your API initiative matures and you add additional audiences for your APIs that are less and less under your control, you need to add more considerations to your governance processes. Trying to plan and perfect everything in your governance process for every audience before starting is a mistake. Plan to learn and iterate your governance along the way and address critical concerns early while adding necessary enhancements later.
- For internal audiences – beginning efforts to think about API Identification (you will get better at this with more experience), security is internal so while always important it is a time to get comfortable with the capabilities and implementation. Versioning considerations begin but again will improve with experience. Monetization if any is usually a chargeback model for internal. Entitlement/enforcement is usually soft – notification of usage beyond a limit is all that is needed. Gathering and communication of metrics begins.
- For Partners – API Identification, Security, and versioning are firmed up. Monetization might begin to occur, and entitlement/enforcement could be either soft or hard. In addition, concerns about Privacy need to be addressed.
- For Public – All the prior, plus more focus on monetization and stricter entitlement enforcement. Legal concerns are important now.
Now a quick look at some of the technical governance considerations:
- API Standards / Best Practices / Naming conventions– setting up these criteria is often done early.
- Set up best practices around granularity and simplicity.
- Lifecycle – few stages should be required to ensure speed of delivery.
- Deployment / Publishing – early environments are usually handled synchronously. However, Production is usually isolated and requires a disconnected deployment approach (usually scripted).
- Security – setting up technical considerations around security – e.g. App security handled via App keys and secrets. Users of the App may be identified using OAuth to shield their private login information from the App itself.
- Scale – API entitlement levels are used to plan for capacity, the gateway enforces these entitlements and shields the systems of record from too many requests. Analytics can help plan for increased requirements on systems of record.
- Integration – understanding the difference between APIs and Services and creating criteria for these is critical. Will you allow simple integrations to back end services directly or does everything flow through an ESB? Generic results can be returned to the gateway and customized to the required API response to reduce the amount of data transmitted back to the API consumer.
I’ve gone beyond my normal self-imposed size limit for a blog, but as I stated at the beginning this is not an easy topic. A few final suggestions:
- Start! – Don’t wait until you get everything in place
- Learn – expect that you will improve these processes. Revisit your governance to see what is working and what might need improvement.
One of my favorite statements about governance is that “Governance should make it easy to do things the ‘right’ way, and hard to do things the ‘wrong’ way.” If your governance is slowing down everything including the ‘right’ way, then that is called bureaucracy and it needs to be improved.
To understand more about IBM’s thoughts on the API Economy visit the IBM API Economy website. IBM API Connect is IBM’s complete foundation to Create, Run, Manage, and Secure APIs. You can find more information about IBM API Connect at the API Connect website. And you can also experience a trial version of API Connect.
If you have questions, please let me know. Connect with me through comments here or via twitter @Arglick to continue the discussion.