WSO2 Governance API

# Copyright (c) 2024, WSO2 LLC. (http://www.wso2.com).
#
# WSO2 LLC. licenses this file to you under the Apache License,
# Version 2.0 (the "License"); you may not use this file except
# in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License
################################################################################
openapi: 3.0.1
info:
  version: v1.1
  title: WSO2 API Manager - Governance
  description: |
    This document specifies a **RESTful API** for WSO2 **API Manager** - Governance.
  contact:
    name: WSO2
    url: http://wso2.com/products/api-manager/
    email: architecture@wso2.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://apis.wso2.com/api/am/governance/v1
tags:
  - name: Rulesets
    description: for managing rulesets.
  - name: Governance Policies
    description: for managing governance policies.
  - name: Artifact Compliance
    description: for accessing artifact compliance.
  - name: Policy Adherence
    description: for accessing policy adherence.
  - name: Deprecated
    description: resources that are deprecated.
paths:
  /rulesets:
    get:
      summary: Retrieves a list of rulesets.
      description: Returns a list of all rulesets associated with the requested organization.
      operationId: getRulesets
      tags:
        - Rulesets
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: query
          in: query
          schema:
            type: string
            example: "name:WSO2 Security Practices artifactType:REST_API ruleType:API_DEFINITION"
          description: |
            You can search for rulesets using the following format:

              - "query=name:{NAME}" searches rulesets by name.
              - "query=artifactType:{ARTIFACT_TYPE}" searches rulesets by artifact type.
              - "query=ruleType:{RULE_TYPE}" searches rulesets by rule type.

            You can combine multiple attributes to search for rulesets:
              - "query=name:{NAME} artifactType:{ARTIFACT_TYPE} ruleType:{RULE_TYPE}" searches rulesets by name, artifact type, and rule type.

            Remember to use URL encoding if your client does not support it (e.g., curl).
      responses:
        "200":
          description: OK. Successful response with a list of rulesets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetList'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_read
    post:
      summary: Create a new ruleset.
      description: Creates a new ruleset in the user's organization.
      operationId: createRuleset
      tags:
        - Rulesets
      requestBody:
        required: true
        description: JSON object containing the details of the new ruleset.
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RulesetInput'
      responses:
        "201":
          description: OK. Ruleset created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetInfo'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_manage
  /rulesets/{rulesetId}:
    get:
      summary: Retrieves details of a specific ruleset.
      description: Retrieves details of the ruleset identified by the rulesetId.
      operationId: getRulesetById
      tags:
        - Rulesets
      parameters:
        - $ref: '#/components/parameters/rulesetId'
      responses:
        "200":
          description: OK. Ruleset details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetInfo'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_read
    put:
      summary: Updates a specific ruleset.
      description: Updates the details of the ruleset identified by the `rulesetId`.
      operationId: updateRulesetById
      tags:
        - Rulesets
      parameters:
        - $ref: '#/components/parameters/rulesetId'
      requestBody:
        required: true
        description: JSON object containing the updated ruleset details.
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RulesetInput'
      responses:
        "200":
          description: OK. Ruleset updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetInfo'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_manage
    delete:
      summary: Deletes a specific ruleset.
      description: Deletes an existing ruleset identified by the rulesetId.
      operationId: deleteRuleset
      tags:
        - Rulesets
      parameters:
        - $ref: '#/components/parameters/rulesetId'
      responses:
        '204':
          description: OK. Ruleset deleted successfully.
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_manage
  /rulesets/{rulesetId}/content:
    get:
      summary: Retrieves the content of a specific ruleset.
      description: Retrieves the content of the ruleset identified by the rulesetId.
      operationId: getRulesetContent
      tags:
        - Rulesets
      parameters:
        - $ref: '#/components/parameters/rulesetId'
      responses:
        "200":
          description: OK. Ruleset content retrieved successfully.
          content:
            application/x-yaml:
              schema:
                type: string
            application/json:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_read
  /rulesets/{rulesetId}/usage:
    get:
      summary: Retrieves the policy usage of a specific ruleset.
      description: Retrieves the list of policies using the ruleset identified by the rulesetId.
      operationId: getRulesetUsage
      tags:
        - Rulesets
      parameters:
        - $ref: '#/components/parameters/rulesetId'
      responses:
        "200":
          description: OK. Ruleset usage retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                description: List of artifacts using the ruleset.
                items:
                  type: string
                  example: "123e4567-e89b-12d3-a456-426614174000"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_rule_read
  /policies:
    get:
      summary: Retrieves a list of all governance policies.
      description: Retrieves a list of governance policies for the user's organization.
      operationId: getGovernancePolicies
      tags:
        - Governance Policies
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: query
          in: query
          schema:
            type: string
            example: "name:WSO2 Best Practices state:API_CREATE label:GLOBAL"
          description: |
            You can search for governance policies using following format.

              - "query=name:{NAME}" searches policies by name.
              - "query=state:{STATE} " searches policies by state.
            
            You can also use multiple attributes to search for policies.
              - "query=name:{NAME} state:{STATE}" searches policies by name, state, and label.

            Remember to use URL encoding if your client doesn't support it (e.g., curl).
      responses:
        "200":
          description: OK. Successful response with a list of governance policies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIMGovernancePolicyList'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_policy_read
    post:
      summary: Creates a new governance policy.
      description: Creates a new governance policy for the user's organization.
      operationId: createGovernancePolicy
      tags:
        - Governance Policies
      requestBody:
        required: true
        description: JSON object containing the details of the new governance policy.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIMGovernancePolicy'
      responses:
        "201":
          description: OK. Governance policy created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIMGovernancePolicy'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_policy_manage
  /policies/{policyId}:
    get:
      summary: Get a specific governance policy
      description: Retrieves details of a specific governance policy identified by the policyId.
      operationId: getGovernancePolicyById
      tags:
        - Governance Policies
      parameters:
        - $ref: '#/components/parameters/policyId'
      responses:
        "200":
          description: OK. Governance policy details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIMGovernancePolicy'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_policy_read
    put:
      summary: Update a specific governance policy
      description: Updates the details of an existing governance policy identified by the policyId.
      operationId: updateGovernancePolicyById
      tags:
        - Governance Policies
      parameters:
        - $ref: '#/components/parameters/policyId'
      requestBody:
        required: true
        description: JSON object containing the updated governance policy details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIMGovernancePolicy'
      responses:
        "200":
          description: OK. Governance policy updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIMGovernancePolicy'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_policy_manage
    delete:
      summary: Delete a specific governance policy
      description: Deletes an existing governance policy identified by the policyId.
      operationId: deleteGovernancePolicy
      tags:
        - Governance Policies
      parameters:
        - $ref: '#/components/parameters/policyId'
      responses:
        '204':
          description: OK. Governance policy deleted successfully.
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_policy_manage
  /artifact-compliance/api:
    get:
      summary: Retrieves compliance of all API artifacts
      description: Retrieves compliance of all API artifacts within the organization visible to logged-in user.
      operationId: getComplianceStatusListOfAPIs
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      tags:
        - Artifact Compliance
      responses:
        "200":
          description: OK. Successful response with API compliance results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactComplianceList'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read
  /artifact-compliance/api/summary:
    get:
      summary: Retrieves the summary of compliance of all API artifacts
      description: Retrieves the summary of compliance of all API artifacts within the organization visible to logged-in user.
      operationId: getComplianceSummaryForAPIs
      tags:
        - Artifact Compliance
      responses:
        "200":
          description: OK. Successful response with compliance summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactComplianceSummary'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read
  /artifact-compliance/api/{apiId}:
    get:
      summary: Retrieve compliance details for a specific API
      description: Retrieve compliance details associated with a specific API using its unique UUID.
      operationId: getComplianceByAPIId
      tags:
        - Artifact Compliance
      parameters:
        - $ref: '#/components/parameters/apiId'
      responses:
        "200":
          description: Successful response with compliance details for the specified artifact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactComplianceDetails'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read
  /artifact-compliance/api/{apiId}/ruleset-validation-results/{rulesetId}:
    get:
      summary: Retrieve ruleset validation results for a specific API
      description: Retrieve ruleset validation results associated with a specific API using its unique UUID.
      operationId: getRulesetValidationResultsByAPIId
      tags:
        - Artifact Compliance
      parameters:
        - $ref: '#/components/parameters/apiId'
        - $ref: '#/components/parameters/rulesetId'
      responses:
        "200":
          description: Successful response with ruleset validation results for the specified API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetValidationResult'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read
  /policy-adherence:
    get:
      summary: Retrieve adherence status for all policies
      description: Retrieve adherence status of all governance policies within the organization.
      operationId: getPolicyAdherenceForAllPolicies
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      tags:
        - Policy Adherence
      responses:
        "200":
          description: Ok. Successful response with adherence details for all policies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyAdherenceList'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read
  /policy-adherence/summary:
    get:
      summary: Retrieves the summary of adherence for all policies
      description: Retrieves the summary of adherence for all governance policies within the organization.
      operationId: getPolicyAdherenceSummary
      tags:
        - Policy Adherence
      responses:
        "200":
          description: OK. Successful response with adherence summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyAdherenceSummary'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read
  /policy-adherence/{policyId}:
    get:
      summary: Retrieve adherence details for a specific policy
      description: Retrieve adherence details associated with a specific governance policy within the organization using its unique ID. The list of artifacts under the policy will only contain the artifacts visible to user
      operationId: getPolicyAdherenceByPolicyId
      tags:
        - Policy Adherence
      parameters:
        - $ref: '#/components/parameters/policyId'
      responses:
        "200":
          description: Ok. Successful response with adherence details for the specified policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyAdherenceDetails'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - OAuth2Security:
            - apim:gov_result_read

components:
  schemas:
    Pagination:
      title: Pagination
      type: object
      properties:
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 1
        total:
          type: integer
          example: 10
        next:
          type: string
          description: |
            Link to the next subset of resources qualified.
            Empty if no more resources are to be returned.
        previous:
          type: string
          description: |
            Link to the previous subset of resources qualified.
            Empty if current subset is the first subset returned.
    Error:
      title: Error object returned with 4XX HTTP Status
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int64
        message:
          type: string
          description: Error message.
        description:
          type: string
          description: |
            A detail description about the error message.
    RulesetList:
      type: object
      description: A list of rulesets.
      properties:
        count:
          type: integer
          description: Number of rulesets returned.
          example: 2
        list:
          type: array
          description: List of rulesets.
          items:
            $ref: '#/components/schemas/RulesetInfo'
        pagination:
          $ref: '#/components/schemas/Pagination'
    RulesetInput:
      type: object
      description: Detailed information about a ruleset.
      properties:
        name:
          type: string
          maxLength: 256
          description: Name of the ruleset.
          example: "API Security Ruleset"
        description:
          type: string
          maxLength: 1024
          description: A brief description of the ruleset.
          example: "A ruleset designed to enforce security standards for APIs."
        rulesetContent:
          type: string
          description: The content of the ruleset file (YAML or JSON).
          format: binary
          example: |
            rules:
              oas2-always-use-https:
                given:
                  - '$.schemes[*]'
                severity: error
                then:
                  function: enumeration
                  functionOptions:
                    values:
                      - https
                description: >-
                  Host schemes must use the HTTPS protocol. Applies to: OpenAPI 2.0`
                message: API host schemes must use the HTTPS protocol.
                formats:
                  - oas2
        ruleCategory:
          type: string
          description: Category the rules included in ruleset.
          enum:
            - SPECTRAL
          example: SPECTRAL
          default: SPECTRAL
        ruleType:
          type: string
          description: Context or area to which the ruleset applies.
          enum:
            - API_METADATA
            - API_DEFINITION
            - API_DOCUMENTATION
          example: API_DEFINITION
          x-enum-varnames:
            - API_METADATA
            - API_DEFINITION
            - API_DOCUMENTATION
        artifactTy

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wso2/refs/heads/main/openapi/wso2-governance-api.yaml