openapi: 3.0.0
info:
  title: webMethods API Gateway Service Management APIs 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
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}/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:
  schemas:
    PackageListResponse:
      type: object
      properties:
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
    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
    ImplementationRequest:
      type: object
      properties:
        endpoints:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              isDefault:
                type: boolean
        maturityState:
          type: string
          enum:
          - BETA
          - RELEASED
          - DEPRECATED
    Package:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
    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
    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
    GatewayEndpointsRequest:
      type: object
      properties:
        gatewayEndpoints:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              url:
                type: string
              isDefault:
                type: boolean
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with API Gateway administrator credentials