openapi: 3.2.0
info:
  title: HAProxy Data Plane Server Template API
  description: 'API for editing and managing haproxy instances. Provides process information, configuration management,

    haproxy stats and logs.'
  version: '3.4'
  contact:
    name: HAProxy Support
    url: https://my.haproxy.com/portal/cust/login
    email: support@haproxy.com
servers:
- url: /v3
security:
- basic_auth: []
tags:
- name: ServerTemplate
paths:
  /services/haproxy/configuration/backends/{parent_name}/server_templates:
    get:
      description: Returns an array of all server templates that are configured in specified backend.
      operationId: getServerTemplates
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_templates'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return an array of server templates
      tags:
      - ServerTemplate
    post:
      description: Adds a new server template in the specified backend in the configuration file.
      operationId: createServerTemplate
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '201':
          description: Server template created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_template'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_template'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Add a new server template
      tags:
      - ServerTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/server_template'
        required: true
  /services/haproxy/configuration/backends/{parent_name}/server_templates/{prefix}:
    delete:
      description: Deletes a server template configuration by it's prefix in the specified backend.
      operationId: deleteServerTemplate
      parameters:
      - description: Server template prefix
        in: path
        name: prefix
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
        '204':
          description: Server template deleted
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Delete a server template
      tags:
      - ServerTemplate
    get:
      description: Returns one server template configuration by it's prefix in the specified backend.
      operationId: getServerTemplate
      parameters:
      - description: Server template prefix
        in: path
        name: prefix
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_template'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return one server template
      tags:
      - ServerTemplate
    put:
      description: Replaces a server template configuration by it's prefix in the specified backend.
      operationId: replaceServerTemplate
      parameters:
      - description: Server template prefix
        in: path
        name: prefix
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '200':
          description: Server template replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_template'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_template'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Replace a server template
      tags:
      - ServerTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/server_template'
        required: true
components:
  parameters:
    transaction_id:
      name: transaction_id
      in: query
      description: ID of the transaction where we want to add the operation. Cannot be used when version is specified.
      required: false
      schema:
        type: string
    version:
      name: version
      in: query
      description: Version used for checking configuration version. Cannot be used when transaction is specified, transaction has it's own version.
      required: false
      schema:
        type: integer
    parent_name:
      name: parent_name
      in: path
      description: Parent name
      required: true
      schema:
        type: string
        pattern: ^[^\r\n<>*;$#&{}"]+$
    force_reload:
      name: force_reload
      in: query
      description: If set, do a force reload, do not wait for the configured reload-delay. Cannot be used when transaction is specified, as changes in transaction are not applied directly to configuration.
      required: false
      schema:
        type: boolean
        default: false
  schemas:
    error:
      additionalProperties:
        type: string
      description: API Error
      properties:
        code:
          type:
          - integer
          - 'null'
        message:
          type:
          - string
          - 'null'
      required:
      - code
      - message
      title: Error
      type: object
    server_templates:
      title: Server templates
      description: HAProxy backend server templates array
      type: array
      items:
        $ref: '#/components/schemas/server_template'
    server_template:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/server_params'
      - properties:
          fqdn:
            type: string
          id:
            type:
            - integer
            - 'null'
          metadata:
            additionalProperties:
              type: object
          num_or_range:
            type: string
          port:
            maximum: 65535
            minimum: 1
            type:
            - integer
            - 'null'
          prefix:
            pattern: ^[^\s]+$
            type: string
        required:
        - prefix
        - num_or_range
        - fqdn
        type: object
      description: Set a template to initialize servers with shared parameters.
      example:
        fqdn: google.com
        num_or_range: 1-3
        port: 80
        prefix: srv
      title: Server template
    server_params:
      properties:
        agent-addr:
          pattern: ^[^\s]+$
          type: string
        agent-check:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            agent-port:
              required: true
        agent-inter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        agent-port:
          maximum: 65535
          minimum: 1
          type:
          - integer
          - 'null'
        agent-send:
          type: string
        allow_0rtt:
          type: boolean
        alpn:
          pattern: ^[^\s]+$
          type: string
          x-display-name: ALPN Protocols
        backup:
          enum:
          - enabled
          - disabled
          type: string
        cc:
          type: string
          x-display-name: TCP Congestion Control Algorithm
        check:
          enum:
          - enabled
          - disabled
          type: string
        check-pool-conn-name:
          pattern: ^[^\s]+$
          type: string
        check-reuse-pool:
          enum:
          - enabled
          - disabled
          type: string
        check-send-proxy:
          enum:
          - enabled
          - disabled
          type: string
        check-sni:
          pattern: ^[^\s]+$
          type: string
        check-ssl:
          enum:
          - enabled
          - disabled
          type: string
        check_alpn:
          pattern: ^[^\s]+$
          type: string
          x-display-name: Protocols
        check_proto:
          pattern: ^[^\s]+$
          type: string
          x-display-name: Name
        check_sni_auto:
          enum:
          - enabled
          - disabled
          type: string
        check_via_socks4:
          enum:
          - enabled
          - disabled
          type: string
        ciphers:
          type: string
          x-dependency:
            ssl:
              value: enabled
        ciphersuites:
          type: string
          x-dependency:
            ssl:
              value: enabled
        client_sigalgs:
          type: string
          x-dependency:
            ssl:
              value: true
        cookie:
          pattern: ^[^\s]+$
          type: string
        crl_file:
          type: string
          x-dependency:
            ssl:
              value: enabled
        curves:
          type: string
          x-dependency:
            ssl:
              value: true
        downinter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        error_limit:
          type: integer
          x-display-name: Error count
        fall:
          type:
          - integer
          - 'null'
          x-display-name: Nr. of consecutive failed checks
        fastinter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        force_sslv3:
          description: This field is deprecated in favor of sslv3, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv10:
          description: This field is deprecated in favor of tlsv10, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv11:
          description: This field is deprecated in favor of tlsv11, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv12:
          description: This field is deprecated in favor of tlsv12, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv13:
          description: This field is deprecated in favor of tlsv13, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        guid:
          pattern: ^[A-Za-z0-9-_.:]+$
          type: string
        hash_key:
          pattern: ^[^\s]+$
          type: string
        health_check_address:
          pattern: ^[^\s]+$
          type: string
        health_check_port:
          maximum: 65535
          minimum: 1
          type:
          - integer
          - 'null'
        idle_ping:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        init-addr:
          pattern: ^[^\s]+$
          type:
          - string
          - 'null'
        init-state:
          enum:
          - fully-up
          - up
          - down
          - fully-down
          type: string
        inter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        ktls:
          enum:
          - 'on'
          - 'off'
          type: string
          x-display-name: 'Enables or disables ktls for those sockets. If enabled, kTLS will be used if the kernel supports it and the cipher is compatible.

            This is only available on Linux kernel 4.17 and above.

            EXPERIMENTAL OPTION.'
        log-bufsize:
          type:
          - integer
          - 'null'
        log_proto:
          enum:
          - legacy
          - octet-count
          type: string
        maintenance:
          enum:
          - enabled
          - disabled
          type: string
        max_reuse:
          type:
          - integer
          - 'null'
        maxconn:
          type:
          - integer
          - 'null'
          x-display-name: Max Concurrent Connections
        maxqueue:
          type:
          - integer
          - 'null'
          x-display-name: Max Number of Connections
        minconn:
          type:
          - integer
          - 'null'
        namespace:
          type: string
        no_sslv3:
          description: This field is deprecated in favor of sslv3, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv10:
          description: This field is deprecated in favor of tlsv10, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv11:
          description: This field is deprecated in favor of tlsv11, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv12:
          description: This field is deprecated in favor of tlsv12, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv13:
          description: This field is deprecated in favor of force_tlsv13, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_verifyhost:
          enum:
          - enabled
          - disabled
          type: string
        npn:
          type: string
          x-dependency:
            ssl:
              value: enabled
        observe:
          enum:
          - layer4
          - layer7
          type: string
          x-dependency:
            ssl:
              value: enabled
        on-error:
          enum:
          - fastinter
          - fail-check
          - sudden-death
          - mark-down
          type: string
        on-marked-down:
          enum:
          - shutdown-sessions
          type: string
        on-marked-up:
          enum:
          - shutdown-backup-sessions
          type: string
        pool_conn_name:
          pattern: ^[^\s]+$
          type: string
        pool_low_conn:
          type:
          - integer
          - 'null'
        pool_max_conn:
          type:
          - integer
          - 'null'
        pool_purge_delay:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        proto:
          pattern: ^[^\s]+$
          type: string
        proxy-v2-options:
          items:
            enum:
            - authority
            - cert-cn
            - cert-key
            - cert-sig
            - crc32c
            - ssl
            - ssl-cipher
            - unique-id
            type: string
          type: array
          x-omitempty: true
        quic-cc-algo:
          enum:
          - cubic
          - newreno
          - bbr
          - nocc
          type: string
        quic_cc_algo_max_window:
          maximum: 4194304
          minimum: 10
          type:
          - integer
          - 'null'
          x-default-unit: k
          x-dependency:
            quic-cc-algo: null
          x-size: true
        redir:
          type: string
          x-display-name: Prefix
        renegotiate:
          description: Toggles the secure renegotiation mechanism for an SSL backend.
          enum:
          - enabled
          - disabled
          type: string
        resolve-net:
          pattern: ^([A-Za-z0-9.:/]+)(,[A-Za-z0-9.:/]+)*$
          type: string
        resolve-prefer:
          enum:
          - ipv4
          - ipv6
          type: string
        resolve_opts:
          pattern: ^(allow-dup-ip|ignore-weight|prevent-dup-ip)(,(allow-dup-ip|ignore-weight|prevent-dup-ip))*$
          type: string
        resolvers:
          pattern: ^[^\s]+$
          type: string
          x-dynamic-enum:
            operation: getResolvers
            property: name
        rise:
          type:
          - integer
          - 'null'
        send-proxy:
          enum:
          - enabled
          - disabled
          type: string
        send-proxy-v2:
          enum:
          - enabled
          - disabled
          type: string
        send_proxy_v2_ssl:
          enum:
          - enabled
          - disabled
          type: string
        send_proxy_v2_ssl_cn:
          enum:
          - enabled
          - disabled
          type: string
        set-proxy-v2-tlv-fmt:
          properties:
            id:
              type: string
            value:
              type: string
          required:
          - id
          - value
          type: object
        shard:
          type: integer
        sigalgs:
          type: string
          x-dependency:
            ssl:
              value: true
        slowstart:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        sni:
          pattern: ^[^\s]+$
          type: string
        sni_auto:
          enum:
          - enabled
          - disabled
          type: string
        socks4:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            check-via-socks4:
              required: true
        source:
          type: string
        ssl:
          enum:
          - enabled
          - disabled
          type: string
        ssl_cafile:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            ssl:
              value: enabled
          x-display-name: SSL CA File
        ssl_certificate:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            ssl:
              value: enabled
        ssl_max_ver:
          enum:
          - SSLv3
          - TLSv1.0
          - TLSv1.1
          - TLSv1.2
          - TLSv1.3
          type: string
        ssl_min_ver:
          enum:
          - SSLv3
          - TLSv1.0
          - TLSv1.1
          - TLSv1.2
          - TLSv1.3
          type: string
        ssl_reuse:
          enum:
          - enabled
          - disabled
          type: string
        sslv3:
          enum:
          - enabled
          - disabled
          type: string
        stick:
          enum:
          - enabled
          - disabled
          type: string
        strict-maxconn:
          type: boolean
        tcp_md5sig:
          pattern: ^[^\s]+$
          type: string
        tcp_ut:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        tfo:
          enum:
          - enabled
          - disabled
          type: string
        tls_tickets:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: enabled
        tlsv10:
          enum:
          - enabled
          - disabled
          type: string
        tlsv11:
          enum:
          - enabled
          - disabled
          type: string
        tlsv12:
          enum:
          - enabled
          - disabled
          type: string
        tlsv13:
          enum:
          - enabled
          - disabled
          type: string
        track:
          type: string
        verify:
          enum:
          - none
          - required
          type: string
          x-dependency:
            ssl:
              value: enabled
        verifyhost:
          type: string
          x-dependency:
            ssl:
              value: enabled
            verify:
              value: required
        weight:
          type:
          - integer
          - 'null'
        ws:
          enum:
          - auto
          - h1
          - h2
          type: string
          x-display-name: Relaying websocket stream protocol
      type: object
  responses:
    DefaultError:
      description: General Error
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    NotFound:
      description: The specified resource was not found
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    BadRequest:
      description: Bad request
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    AlreadyExists:
      description: The specified resource already exists
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
externalDocs:
  url: https://docs.haproxy.org/
  description: HAProxy Documentation