openapi: 3.1.0
info:
  title: Apache APISIX Admin Consumer Groups Services API
  description: The Apache APISIX Admin API provides a RESTful interface to dynamically control and configure your deployed Apache APISIX instance. It allows management of routes, services, upstreams, consumers, SSL certificates, global rules, plugin configurations, consumer groups, secrets, and more. By default, the Admin API listens on port 9180 and requires API key authentication via the X-API-KEY header.
  version: 3.14.0
  contact:
    name: Apache APISIX
    url: https://apisix.apache.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://127.0.0.1:9180/apisix/admin
  description: Default local Admin API server
security:
- apiKey: []
tags:
- name: Services
paths:
  /services:
    get:
      operationId: listServices
      summary: Apache APISIX List All Services
      description: Fetches a list of all configured services.
      tags:
      - Services
      responses:
        '200':
          description: Successful response with list of services.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createService
      summary: Apache APISIX Create a Service
      description: Creates a new service with a server-generated ID.
      tags:
      - Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '201':
          description: Service created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
  /services/{service_id}:
    get:
      operationId: getService
      summary: Apache APISIX Get a Service
      description: Fetches the specified service by its ID.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: Successful response with service details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '404':
          description: Service not found.
    put:
      operationId: createOrUpdateService
      summary: Apache APISIX Create or Update a Service
      description: Creates a service with the specified ID, or updates it if it already exists.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '200':
          description: Service updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '201':
          description: Service created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
    patch:
      operationId: patchService
      summary: Apache APISIX Patch a Service
      description: Updates partial attributes of the specified service.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '200':
          description: Service patched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '404':
          description: Service not found.
    delete:
      operationId: deleteService
      summary: Apache APISIX Delete a Service
      description: Removes the specified service.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: Service deleted successfully.
        '404':
          description: Service not found.
components:
  schemas:
    ResourceResponse:
      type: object
      description: Standard response wrapper for a single resource.
      properties:
        key:
          type: string
          description: The etcd key path for the resource.
        value:
          type: object
          description: The resource configuration.
        modifiedIndex:
          type: integer
          description: The etcd modification index.
        createdIndex:
          type: integer
          description: The etcd creation index.
    Timeout:
      type: object
      description: Timeout settings for upstream connections.
      properties:
        connect:
          type: number
          default: 60
          description: Connection timeout in seconds.
        send:
          type: number
          default: 60
          description: Send timeout in seconds.
        read:
          type: number
          default: 60
          description: Read timeout in seconds.
    ResourceCreated:
      type: object
      description: Response wrapper for a newly created resource.
      properties:
        key:
          type: string
          description: The etcd key path for the created resource.
        value:
          type: object
          description: The created resource configuration.
    ResourceList:
      type: object
      description: Standard response wrapper for a list of resources.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/ResourceResponse'
          description: Array of resource entries.
        total:
          type: integer
          description: Total count of resources.
    Upstream:
      type: object
      description: An Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to configured rules.
      properties:
        name:
          type: string
          description: Human-readable name for the upstream.
        desc:
          type: string
          description: Description of the upstream.
        type:
          type: string
          enum:
          - roundrobin
          - chash
          - least_conn
          - ewma
          default: roundrobin
          description: Load balancing algorithm.
        nodes:
          oneOf:
          - type: object
            additionalProperties:
              type: integer
            description: Key-value pairs of address:port to weight.
          - type: array
            items:
              type: object
              properties:
                host:
                  type: string
                port:
                  type: integer
                weight:
                  type: integer
                priority:
                  type: integer
                  default: 0
            description: List of node objects.
          description: Backend service nodes.
        service_name:
          type: string
          description: Service name for service discovery.
        discovery_type:
          type: string
          description: Type of service discovery (e.g. dns, consul, nacos, eureka).
        hash_on:
          type: string
          enum:
          - vars
          - header
          - cookie
          - consumer
          - vars_combinations
          default: vars
          description: Hash input for consistent hashing load balancer.
        key:
          type: string
          description: Hash key when using chash load balancer.
        checks:
          type: object
          description: Health check configuration.
          properties:
            active:
              type: object
              description: Active health check configuration.
              properties:
                type:
                  type: string
                  enum:
                  - http
                  - https
                  - tcp
                  default: http
                timeout:
                  type: number
                  default: 1
                http_path:
                  type: string
                  default: /
                host:
                  type: string
                port:
                  type: integer
                https_verify_certificate:
                  type: boolean
                  default: true
                healthy:
                  type: object
                  properties:
                    interval:
                      type: integer
                    successes:
                      type: integer
                unhealthy:
                  type: object
                  properties:
                    interval:
                      type: integer
                    http_failures:
                      type: integer
                    tcp_failures:
                      type: integer
                    timeouts:
                      type: integer
            passive:
              type: object
              description: Passive health check configuration.
              properties:
                type:
                  type: string
                  enum:
                  - http
                  - https
                  - tcp
                  default: http
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                    successes:
                      type: integer
                unhealthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                    http_failures:
                      type: integer
                    tcp_failures:
                      type: integer
                    timeouts:
                      type: integer
        retries:
          type: integer
          description: Number of retries for failed requests.
        retry_timeout:
          type: number
          description: Timeout in seconds for retry requests.
        timeout:
          $ref: '#/components/schemas/Timeout'
        scheme:
          type: string
          enum:
          - http
          - https
          - grpc
          - grpcs
          default: http
          description: The scheme for communicating with the upstream.
        pass_host:
          type: string
          enum:
          - pass
          - node
          - rewrite
          default: pass
          description: How to set the Host header when proxying to upstream.
        upstream_host:
          type: string
          description: Host to use when pass_host is set to rewrite.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs for categorization.
        keepalive_pool:
          type: object
          description: Keepalive pool configuration.
          properties:
            size:
              type: integer
              default: 320
            idle_timeout:
              type: number
              default: 60
            requests:
              type: integer
              default: 1000
        tls:
          type: object
          description: TLS configuration for upstream connections.
          properties:
            client_cert:
              type: string
              description: Client certificate for mTLS.
            client_key:
              type: string
              description: Client private key for mTLS.
    Service:
      type: object
      description: A Service is an abstraction of an API and corresponds to an upstream service. It can be shared across routes.
      properties:
        name:
          type: string
          description: Human-readable name for the service.
        desc:
          type: string
          description: Description of the service.
        plugins:
          type: object
          description: Plugin configuration. Key is the plugin name and value is the plugin config.
        upstream:
          $ref: '#/components/schemas/Upstream'
        upstream_id:
          type: string
          description: ID of an existing upstream to use.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs for categorization.
        enable_websocket:
          type: boolean
          description: Enable WebSocket proxying.
        hosts:
          type: array
          items:
            type: string
          description: A list of hosts for the service.
  parameters:
    ServiceId:
      name: service_id
      in: path
      required: true
      description: Unique identifier of the service.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Admin API key for authentication.