Tags: API Governance, API Management

What is API Governance?

API Governance is key in building great APIs and delivering an excellent API Experience.

• API governance provides a policy-driven approach that helps to enforce standards and checkpoints throughout the API lifecycle.
• It encompasses not only the API runtime, but also design through development processes.
• It includes the guidelines, standards, and processes to be followed for API identification, interface documentation, development, testing, deployment, run, and operation.
• Standards and principles defined by API governance provide API quality assurance, such as security, availability, scalability, and reliability. It underpins the API enablement aspect that is critical for the successful adoption of APIs.

Aim of API Governance

• Governance at the time of the API proposal (new/updates) must ensure that the identified APIs align to the business strategy and meet the business requirements. Funding for API development must be approved by the business and other stakeholders.
• API design and development time governance must ensure that the API software quality is maintained. It must address API versioning strategy and focus on development standards and best practices to be followed. Appropriate reviews and checkpoints must be enforced to ensure quality of the API.
• API governance must help define the right API testing strategy to ensure that APIs are delivering the necessary level of security, reliability, and governance.
• API runtime governance must look at aspects such as API monitoring, deployment, and dynamic provisioning to guarantee API runtime quality.
• API governance must ensure that the service-level agreement (SLA) is followed by the API provider and the consumer.

Meaningful customer impact with API Governance

API Governance is utilized to drive transparency and trust.

• Companies like Twilio, Okta, Stripe, etc. establish service agreements and drive customer trust with clearly communicating their Release cycle and versioning on their API documentation.

The bulk of the work on APIs goes in the infrastructure that makes APIs robust and scalable. Those are however, completely invisible to the end customer and thats part of the magic. To the customer, the only thing that is visible is API Maturity. This sets the customer expectations in following dimensions:

• Set customer expectations in terms of where an API is in its maturity.
• Establish Support SLA expectation for each level of maturity.
• Establish backward compatibility
• Documentation standards
• Set API Performance SLAs
• Take ownership for when SLAs are not met.

API Governance Model – Working backwards

An effective API Governance model will ultimately have a positive customer impact and will manifest in terms of transparency and clarity across documentation, support and SLAs.

1. Customer facing Release cycle to be published on API Docs.
2. Establish a degree of documentation, performance and support for Beta and GA APIs required for an API to be published externally.
3. Release notes with details on API maturity and timeline to GA mentioned.
4. API Products have to meet strict guidelines to progress through API Maturity.
5. APIs have to meet a degree of supportability (tickets per week) criteria to be considered GA.
6. Products cannot be in Beta for more than 6 months without VP approval. This ensures that customers are not building dependency on premature products because that would inevitably be a sub-par experience.

Tying back API Maturity to customer experience and product management

At various levels of API Maturity, customers should be able to receive a matching degree of support. From a Product manager stand point, the product manager wants to be in close sync with number of tickets coming in at various maturity levels of the API so that they can use this data for prioritization.

Case studies

There doesn’t seem to be a defined standard for how to maturity for APIs should be. So lets look at what some of the biggest players in the API space are doing.

Twilio

API SLA breach has revenue impact.

Twilio has 3 levels categories of SLA: Private Beta, Beta and GA.

GA APIs are promised 99.95% uptime percentage threshold based on level and in the event that Twilio doesn’t meet this criteria, Twilio provides customers with service credit of 10%.

API Uptime is published on status.twilio.com where customers can go to check when Twilio APIs are down. Usually API status is also published via a Twitter handle so customers can be informed if their integration might be impacted due to an incident.

For customers using Twilio APIs and subscribing to paid support, they can expect support as quickly as 1 hour for Business Critical issues and 24 hours to 7 days for Developers not on paid support.

Square

Clear versioning and release notes

Square API lifecycle is documented as:

1. Beta
2. General Availability
3. Deprecated
4. Retired.

The API Versioning documentation is kept up to date at all times.

Release notes are published meticulous and frequent tagging specific APIs.

Okta

Okta does a great job of laying out in clear terms how to interpret the maturity of their APIs. They set expectations with the customers so that customers can make informed decisions about which product is mature enough to be used for their production workflows.

Okta features travel through a regular life cycle:

• Beta
  • Beta: Involves regular contact with Okta, which may include conference calls between you and Okta that cover specific use cases, deployment guidance, and feedback. Betas are also announced to customers through the Ozone newsletter and Communities. Okta may also solicit customers to participate in a Beta via email.
  • Beta (Self-Service): Self-directed without ongoing support or regular contact with Okta. Contact is primarily limited to collecting feedback. If you are interested in a Beta Self-Service feature, you can enable that feature for your org from the Settings > Features page in the Admin Console.
• Early Access (EA)
  • A feature in an Early Access (EA) stage is new or enhanced functionality made available for you to selectively opt-in to and use in both Production and non-Production environments.
• General Availability (GA)

A feature in General Availability (GA) is new or enhanced functionality that is enabled by default for all customers. Beginning in February 2017, features move from EA (enabled by request) to GA (enabled for all orgs) in a regular cadence:

1. EA features become GA in preview orgs in the first release of the month.
2. These same features become GA in production orgs in the first release of the next month.

Shopify

Shopify provides detailed documentation, release schedules and communication channels.

• Shopify provides developers detailed information about how they define release candidates, versioned and un-versioned APIs.
• They also provide a release schedule with clear timelines
• They explain to the user what to expect for APIs at different stages of the lifecycle
• They list all the ways customers can find out about changes to the APIs.
• They mentioned when APIs are for use in development vs production to avoid customers from running into issues and plan their development cycles effectively.

Microsoft Graph API

Microsoft defines maturity in terms of Beta, General Availability, Deprecated status set customer expectation on if an API is ready for prime time.

Versions

The following versions of the Microsoft Graph API are currently available.

Beta version

In general, APIs debut in the beta version and are accessible in the https://graph.microsoft.com/beta endpoint. For beta API documentation, see Microsoft Graph beta endpoint reference. Expect breaking changes and deprecation of APIs in the beta version from time to time. Do not take a production dependency on beta APIs.

We make no guarantees that a beta feature will be promoted to the current version. When the Microsoft Graph API team believes that a beta feature is ready for general availability, we will add that feature to the latest current version. If the promotion of the feature would result in a breaking change to the current version, the version number will be incremented, with the new version becoming the current version. Our developer community can post feature requests on the Microsoft 365 Developer Platform ideas forum, including requests for new features as well as requests to promote existing beta APIs to the current version.

Current version

The current version of Microsoft Graph is v1.0. Exposed under https://graph.microsoft.com/v1.0, the Microsoft Graph API v1.0 version contains features that are generally available and ready for production use. Browse the documentation for the v1.0 APIs.

Preview status

An API or feature in Microsoft Graph is labelled as "(preview)" to indicate its behavior is unique in the beta endpoint.

The behavior of most APIs and features in the v1.0 version is in parity with the beta version. "preview" qualifies a minority of APIs and features in one of the following two cases:

• Available in only beta
• Available in beta differently than in v1.0

Like any other API in the beta endpoint, APIs marked in the documentation as "(preview)" may experience breaking changes without notice. Do not access APIs from the beta endpoint in production apps.

As an example, attack simulation training is a feature that has been generally available for administrators in the Microsoft 365 Defender portal. When the REST API for attack simulation training becomes available in Microsoft Graph in only the beta endpoint, the REST API documentation is labelled as "(preview)". The "(preview)" label applies to the REST API and its documentation in Microsoft Graph, even though the service itself is generally available.

Deprecated and unsupported versions

There are currently no deprecated versions of Microsoft Graph.

Ebay

APIs has 3 release stages in addition to Limited Release API (invite only), Experimental APIs and Deprecated APIs.

Suggested Reading

February 10, 2022 Net API Notes for 2022/02/10 - Issue 189 by Matthew Reinbold API Management: An Architect's Guide to Developing and Managing APIs for Your Organization by Brijesh De