Implementing API Governance Policies in WSO2 API Manager

Growing business demands require enterprises to manage a vast number of APIs. The volume and complexity of these integrations make maintaining quality a challenge. To address this, governing the API lifecycle—from design to retirement—has become essential. API management vendors are therefore developing tools and frameworks to assist.

What is API governance?

API governance is the practice of applying structured oversight and control throughout the API lifecycle. It involves setting and enforcing policies and standards for how APIs are designed, documented, secured, and used within an enterprise.

Why API governance?

As a leading vendor in the API management sector, WSO2 has encountered many situations where a lack of proper oversight has led to several issues:

• Deviation from standards: Organizational APIs fail to adhere to established standards.
• Security risks: Practices that compromise security and regulatory compliance, such as pushing unsecure APIs to production.
• API sprawl: Uncontrolled growth of APIs, often with multiple APIs performing the same task.
• Poor consumer experience: Usability issues due to unclear documentation.
• Scalability and performance issues: APIs become unstable or unreliable under increased load.
• Lack of monitoring: An inability to effectively track and analyze API performance.
• Misaligned goals: APIs that do not support core business objectives.

At the root of these challenges lies a single issue: a lack of control and visibility over how API developers manage their APIs.

The answer is governance. By controlling various aspects of the API lifecycle—from creation to retirement—an organization can address all the above concerns. For example, a proper governance framework allows organizations to:

• Address deviations from standards by enforcing a set of guidelines that developers must follow.
• Mitigate security risks by mandating security audits and deprecating vulnerable APIs.
• Reduce API sprawl and enhance user experience through proper documentation and improved API discovery mechanisms.
• Tackle performance and scalability issues by mandating performance testing and monitoring runtime metrics.
• Improve observability with governance dashboards that provide insights into API usage and compliance.

In short, API governance is the solution to many challenges enterprises face in the complex API landscape. Recognizing this, WSO2 API Manager and Bijira include a dedicated, built-in governance framework.

API governance concepts

The governance capabilities of WSO2 API Manager and Bijira are built on a set of core governance concepts. These concepts work together to provide fine-grained control to enterprises over how developers manage APIs.

Rule

A governance rule is a simple condition that validates a specific property of an API and is associated with a severity level such as Error, Warning, or Info.

Ruleset

A ruleset is a collection of governance rules,bounded to a specific type of API (e.g., REST or ASYNC), designed to validate one of the following aspects of an API

• API Definition – The API definition that establishes the API contract.
• API Metadata – WSO2 API Manager's interpretation of an API (api.yaml), which includes information such as security mechanisms, business information, throttling configurations, endpoint configurations, and other operational and management-level properties.
• API Documentation – API documentation that provides usage guidelines and other relevant information about the API

Policy

A governance policy serves as a structured collection of rulesets that are enforced on APIs. These policies help maintain consistency, quality, and compliance across an organization’s API ecosystem.

Policies are typically defined at the organization level, making them reusable across APIs. This centralized approach allows organizations to enforce common governance requirements, while also tailoring rulesets to suit specific groups of APIs or business units.

Policy enforcement is typically triggered when an API transitions into a specific state. Common enforcement points include: API Creation, API Update, API Deployment, and API Publication.

Depending on the severity of rule violations within the policy, it can be configured to take different actions. It may block the API operation entirely, typically during key lifecycle stages like deployment or publication. For less severe issues, the policy can trigger notifications, alerting relevant stakeholders through compliance dashboards without disrupting the API workflow.

The diagram below represents an example of a policy containing two rulesets.

Label

A label is a tag used to group and categorize APIs, making it easier to manage and streamline the application of governance policies.

When a policy is associated with a label, it is automatically applied to all APIs linked to that label. This mechanism allows for flexible and scalable governance by decoupling policy logic from individual APIs and aligning it with business-specific categories or functional groupings.

Managing API governance

WSO2 API Manager and Bijira provide organizations with a comprehensive set of capabilities to govern APIs effectively across teams and workflows:

• Defining Rulesets – Governance rules can be defined and grouped into rulesets to validate key aspects of APIs, such as documentation, security and versioning.

• Defining Policies – Governance policies can be created by organization admins to apply these rulesets across different APIs, tailored to specific organizational or team needs.

• Monitor Compliance – A detailed compliance dashboard is available to organization administrators for tracking policy adherence, identifying violations and taking corrective actions. 

In addition, API creators and publishers have access to a dedicated compliance section within each API, allowing them to monitor and address governance issues during development.

These capabilities help ensure consistent governance practices across the organization, improving API quality, security and lifecycle control, while also empowering both administrators and API teams to maintain compliance collaboratively.

When is API compliance evaluated?

API compliance is evaluated at different points in the API lifecycle based on a variety of triggering actions. These evaluations ensure that APIs remain aligned with the governance policies defined within the organization.

API state changes

Depending on the governance policies configured within the organization, when an API is created, updated, deployed, or published, the compliance of the API is evaluated against the applicable policies.

Depending on the configured governance policies:

• Blocking policies are evaluated synchronously, preventing the operation from proceeding if any violations are found.
• Non-blocking policies are evaluated asynchronously in the background. These results are later reflected in governance dashboards, allowing teams to monitor and address compliance issues over time.

Policy creation or update

When a new governance policy is created or an existing one is updated, all existing APIs to which the policy applies are re-evaluated. This applies regardless of whether the policy is blocking or non-blocking.

For example, if a new API deployment related policy is created and associated with a specific label, all previously deployed APIs with that label will be evaluated against the new policy.

Ruleset update

If a ruleset is updated, and that ruleset is used in one or more policies, all APIs governed by those policies are automatically re-evaluated. This ensures that changes to governance logic are reflected across all relevant APIs without requiring manual intervention.

This multi-stage evaluation process ensures that APIs are continuously checked for compliance, both during active changes and when governance configurations evolve.

The diagram below is an abstract representation of the above scenarios handled within the governance framework.

For more detailed guidance on configuring governance rulesets, creating policies, and understanding enforcement behavior, refer to the official WSO2 API Manager and Bijira documentation. These resources provide comprehensive instructions to help you tailor governance to your organization’s specific needs.