openapi: 3.0.0
info:
  title: webMethods API Gateway Service Management API
  description: >-
    The webMethods API Gateway Service Management API provides REST endpoints for
    managing APIs within the Software AG API Gateway platform. It supports creating,
    reading, updating, and deleting REST, SOAP, WebSocket, and OData APIs, as well
    as managing policies, applications, gateway endpoints, and publishing APIs to
    the Developer Portal.
  version: '11.0'
  contact:
    name: Software AG Developer Community
    url: https://techcommunity.softwareag.com/
  license:
    name: Software AG License
    url: https://www.softwareag.com/

servers:
  - url: http://localhost:5555/rest/apigateway
    description: Local webMethods API Gateway instance

security:
  - basicAuth: []

tags:
  - name: APIs
    description: API lifecycle management operations
  - name: Applications
    description: Application and consumer management
  - name: Policies
    description: Policy and scope management
  - name: Publishing
    description: API portal publishing operations

paths:
  /apis:
    get:
      operationId: getAPIs
      summary: List All APIs
      description: Retrieve all or a filtered subset of APIs registered in the API Gateway with pagination support.
      tags:
        - APIs
      parameters:
        - name: apiIds
          in: query
          description: Comma-separated list of API IDs to filter
          required: false
          schema:
            type: string
        - name: from
          in: query
          description: Starting index for pagination
          required: false
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          description: Number of results to return
          required: false
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: List of APIs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createAPI
      summary: Create API
      description: Create a new API in the API Gateway from a file, URL, or from scratch. Supports REST, SOAP, WebSocket, and OData APIs.
      tags:
        - APIs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIRequest'
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: OpenAPI, Swagger, RAML, or WSDL spec file
                apiName:
                  type: string
                apiDescription:
                  type: string
                apiVersion:
                  type: string
                type:
                  type: string
                  enum: [REST, SOAP, WEBSOCKET, ODATA]
      responses:
        '200':
          description: API created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteAPIs
      summary: Delete Multiple APIs
      description: Remove multiple inactive APIs from the API Gateway.
      tags:
        - APIs
      parameters:
        - name: apiIds
          in: query
          required: true
          description: Comma-separated list of API IDs to delete
          schema:
            type: string
        - name: forceDelete
          in: query
          required: false
          description: Force delete even if API has active subscriptions
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: APIs deleted successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /apis/{apiId}:
    get:
      operationId: getAPI
      summary: Get API
      description: Fetch a specific API definition from the API Gateway with optional format export.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Export format for the API definition
          schema:
            type: string
            enum: [swagger, raml, openapi, odata]
      responses:
        '200':
          description: API retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '404':
          description: API not found
    put:
      operationId: updateAPI
      summary: Update API
      description: Update an API definition in the API Gateway, preserving existing policies and settings.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
        - name: overwriteTags
          in: query
          required: false
          description: Whether to overwrite existing tags
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAPIRequest'
      responses:
        '200':
          description: API updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '400':
          description: Invalid request
        '404':
          description: API not found
    delete:
      operationId: deleteAPI
      summary: Delete API
      description: Remove an inactive API from the API Gateway.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '204':
          description: API deleted successfully
        '400':
          description: API is active and cannot be deleted
        '404':
          description: API not found

  /apis/{apiId}/activate:
    put:
      operationId: activateAPI
      summary: Activate API
      description: Expose an API to consumers by activating it in the API Gateway.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: API activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '404':
          description: API not found

  /apis/{apiId}/deactivate:
    put:
      operationId: deactivateAPI
      summary: Deactivate API
      description: Hide an API from consumers by deactivating it in the API Gateway.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: API deactivated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '404':
          description: API not found

  /apis/{apiId}/applications:
    get:
      operationId: getApplications
      summary: List API Applications
      description: Retrieve all applications that are registered to consume this API.
      tags:
        - Applications
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: Applications retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationListResponse'
        '404':
          description: API not found

  /apis/{apiId}/globalPolicies:
    get:
      operationId: getAssociatedGlobalPolicies
      summary: Get Global Policies
      description: Retrieve all global policies applicable to this API.
      tags:
        - Policies
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: Global policies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyListResponse'
        '404':
          description: API not found

  /apis/{apiId}/publish:
    put:
      operationId: publishAPI
      summary: Publish API to Portal
      description: Register an API to the webMethods Developer Portal for consumer discovery.
      tags:
        - Publishing
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishAPIRequest'
      responses:
        '200':
          description: API published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '400':
          description: Invalid publish request
        '404':
          description: API not found

  /apis/{apiId}/gatewayEndpoints:
    put:
      operationId: updateGatewayEndpoints
      summary: Update Gateway Endpoints
      description: Create, update, or delete custom gateway endpoints for an API.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayEndpointsRequest'
      responses:
        '200':
          description: Gateway endpoints updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '404':
          description: API not found

  /apis/{apiId}/implementation:
    put:
      operationId: updateAPIImplementation
      summary: Update API Implementation
      description: Update the backend implementation endpoints and maturity state of an API.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImplementationRequest'
      responses:
        '200':
          description: Implementation updated successfully
        '404':
          description: API not found

  /apis/{apiId}/mock/enable:
    put:
      operationId: enableAPIMock
      summary: Enable API Mocking
      description: Enable mock responses for an API for testing purposes.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: API mocking enabled
        '404':
          description: API not found

  /apis/{apiId}/mock/disable:
    put:
      operationId: disableAPIMock
      summary: Disable API Mocking
      description: Disable mock responses for an API.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: API mocking disabled
        '404':
          description: API not found

  /apis/{apiId}/tracing/enable:
    put:
      operationId: enableAPITracing
      summary: Enable API Tracing
      description: Enable diagnostic tracing for an API to capture request/response details.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: API tracing enabled
        '404':
          description: API not found

  /apis/{apiId}/tracing/disable:
    put:
      operationId: disableAPITracing
      summary: Disable API Tracing
      description: Disable diagnostic tracing for an API.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: API tracing disabled
        '404':
          description: API not found

  /apis/{apiId}/providerspecification:
    get:
      operationId: downloadProviderSpecification
      summary: Download Provider Specification
      description: Export the API specification without gateway endpoint modifications.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: Provider specification downloaded
          content:
            application/json:
              schema:
                type: object
        '404':
          description: API not found

  /apis/{apiId}/packages:
    get:
      operationId: getAPIPackages
      summary: List API Packages
      description: Retrieve all packages that include this API.
      tags:
        - APIs
      parameters:
        - name: apiId
          in: path
          required: true
          description: Unique identifier of the API
          schema:
            type: string
      responses:
        '200':
          description: Packages retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageListResponse'
        '404':
          description: API not found

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with API Gateway administrator credentials

  schemas:
    APIListResponse:
      type: object
      properties:
        apiResponse:
          type: object
          properties:
            apis:
              type: array
              items:
                $ref: '#/components/schemas/API'
            count:
              type: integer
              description: Total number of APIs matching the filter

    APIResponse:
      type: object
      properties:
        apiResponse:
          type: object
          properties:
            api:
              $ref: '#/components/schemas/API'

    API:
      type: object
      properties:
        id:
          type: string
          description: Unique API identifier
        apiName:
          type: string
          description: Name of the API
        apiVersion:
          type: string
          description: Version of the API
        apiDescription:
          type: string
          description: Description of the API
        type:
          type: string
          enum: [REST, SOAP, WEBSOCKET, ODATA]
          description: API type
        isActive:
          type: boolean
          description: Whether the API is currently active
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the API
        systemVersion:
          type: integer
          description: Internal system version number
        maturityState:
          type: string
          enum: [BETA, RELEASED, DEPRECATED]
          description: API maturity state
        created:
          type: string
          format: date-time
          description: API creation timestamp
        modified:
          type: string
          format: date-time
          description: API last modification timestamp

    CreateAPIRequest:
      type: object
      required:
        - type
        - apiName
      properties:
        type:
          type: string
          enum: [REST, SOAP, WEBSOCKET, ODATA]
        apiName:
          type: string
        apiVersion:
          type: string
          default: '1.0'
        apiDescription:
          type: string
        swagger:
          type: string
          description: URL to a Swagger/OpenAPI spec
        url:
          type: string
          description: URL to the API spec or backend service

    UpdateAPIRequest:
      type: object
      properties:
        apiName:
          type: string
        apiVersion:
          type: string
        apiDescription:
          type: string
        tags:
          type: array
          items:
            type: string
        maturityState:
          type: string
          enum: [BETA, RELEASED, DEPRECATED]

    PublishAPIRequest:
      type: object
      required:
        - portalGatewayId
      properties:
        portalGatewayId:
          type: string
          description: ID of the API Portal gateway to publish to
        communities:
          type: array
          items:
            type: string
          description: Community names to publish the API to
        endpoints:
          type: array
          items:
            type: string
          description: Custom endpoint URLs for the portal

    GatewayEndpointsRequest:
      type: object
      properties:
        gatewayEndpoints:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              url:
                type: string
              isDefault:
                type: boolean

    ImplementationRequest:
      type: object
      properties:
        endpoints:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              isDefault:
                type: boolean
        maturityState:
          type: string
          enum: [BETA, RELEASED, DEPRECATED]

    ApplicationListResponse:
      type: object
      properties:
        applications:
          type: array
          items:
            $ref: '#/components/schemas/Application'

    Application:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        owner:
          type: string
        identifiers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string

    PolicyListResponse:
      type: object
      properties:
        policies:
          type: array
          items:
            $ref: '#/components/schemas/Policy'

    Policy:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        enabled:
          type: boolean

    PackageListResponse:
      type: object
      properties:
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'

    Package:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string