# Copyright 2018 Turbine Labs, Inc.
#
# Licensed 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.

swagger: '2.0'
info:
  title: Turbine Labs API
  description: |
    The Turbine Labs API provides CRUD operations for core object types, and is
    mostly RESTy. The easiest way to interact with the API is with
    [tbnctl](https://docs.turbinelabs.io/advanced/tbnctl.html).
    If you want to make direct HTTP calls, however, you can obtain an access
    token using tbnctl, and then pass it in the Authorization header,
    prefixed by `Token `:
    ```console
    curl -H "Authorization: Token <access token>" https://api.turbinelabs.io/v1.0/cluster
    ```
  version: "1.0"
# the domain of the service
host: api.turbinelabs.io
# array of all schemes that your API supports
schemes:
  - https
securityDefinitions:
  api_key:
    type: apiKey
    name: Authorization
    in: header

security:
  - api_key: []

tags:
  - name: Zone
    description: A logical deployment of services, which typically maps to a
                 datacenter, availability zone, or compute cluster.
  - name: Proxy
    description: A configuration that can be applied to one or more running
                 Proxies serving one or more Domains.
  - name: Listener
    description: An interface and port a Proxy will listen on
  - name: Domain
    description: A served hostname and port.
  - name: Route
    description: A served path within a Domain.
  - name: Shared Rules
    description: A collection of rules specifying how a request should be
                 mapped to an instance within a cluster. These may be
                 shared between multiple Routes.
  - name: Cluster
    description: A collection of Instances, homogeneous in their purpose,
                 heterogeneous in their metadata.
  - name: Audit Log
    description: A collection of events that have occurred in your
                 infrastructure. This includes changes detected by the
                 deployed collectors (new Clusters or Cluster instances)
                 as well as routing changes through the UI or API.

# will be prefixed to all paths
basePath: /v1.0
produces:
  - application/json
paths:

  /admin/user/self:
    get:
      summary: Returns the user object for the account authorized and making this request.
      description: Request the user object for an authorized requesting account.
      tags:
        - User Management
      responses:
        200:
          description: The authorized user.
          schema:
            $ref: '#/definitions/User'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'

  /admin/user/self/access_tokens:
    get:
      summary: Lists Access Tokens that are configured for the authenticated user.
      tags:
        - User Management
      responses:
        200:
          description: A list of Access Tokens defined for the authenticated user.
          schema:
            $ref: '#/definitions/MultiAccessTokens'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Creates a new Access Token and associates it with the authenticated user.
      tags:
        - User Management
      consumes:
        - application/json
      parameters:
        - name: description
          in: body
          description: A short string (<255 characters) describing the expected use of the token.
          required: true
          schema:
            $ref: '#/definitions/AccessTokenDescription'
      responses:
        200:
          description: The new Access Token that was created.
          schema:
            $ref: '#/definitions/AccessToken'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /admin/user/self/access_token/{access-token-key}:
    delete:
      summary: Delete the specified access token.
      tags:
        - User Management
      parameters:
        - name: access-token-key
          in: path
          description: the key of the Access Token that should be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: checksum
          in: query
          description: the current checksum of the user to be modified
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: An empty result if the API key deletion was successful.
        default:
          description: An error; may be unexpected or validation error if the last API was removed.
          schema:
            $ref: '#/definitions/Error'

  /changelog/adhoc:
    get:
      summary: Allows an arbitrary filter to be specified and applied to the org\'s change log.
      description: Perform an adhoc query against the change log for your org. The filter is a JSON encoded FilterSum as defined in this file.
      tags:
        - Audit Log
      parameters:
        - name: filter
          in: query
          description: Encoded FilterSums representing the query you would like to execute. See object definition for details.
          type: string
          x-ref-encoded-object: '#/definitions/FilterSums'
      responses:
        200:
          description: A list of changes that meet the provided filter.
          schema:
            $ref: '#/definitions/PaginatedChangeDescriptions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /changelog/domain-graph/{domainKey}:
    get:
      tags:
        - Audit Log
      summary: get changes related to the indicated domain
      description: |
        Gets all changes to a domain, the proxies that front the specified domain,
        routes within that domain, the shared rules of each route, the clusters
        connected via route or shared rules.
      parameters:
        - name: domainKey
          in: path
          description: the domain key to see an audit log for
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: start
          in: query
          description: |
            The beginning of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: end
          in: query
          description: |
            The end of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: max_results
          in: query
          description: |
            Determines how many ChangeDescription object should be returned to
            the calling code.
          required: false
          type: number
          format: int64
        - name: ref_id
          in: query
          description: |
            When paginating a Changelog request start on the entry that comes
            immediately before or after this ID (as determined by the direction
            argument).
          required: false
          type: string
        - name: direction
          in: query
          description: |
            If set to "before" then changes will be returned that occurred before
            reference ID. If "after" then changes will be returned that have
            occurred since the reference ID.
          required: false
          type: string
          enum:
            - before
            - after
      responses:
        200:
          description: A list of changes occurring during the requested window.
          schema:
            $ref: '#/definitions/PaginatedChangeDescriptions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /changelog/route-graph/{routeKey}:
    get:
      tags:
        - Audit Log
      summary: get changes related to the indicated route
      description: |
        Gets all changes to a route, the domains associated with it, the shared
        rules it references, and the clusters connected to it.
      parameters:
        - name: routeKey
          in: path
          description: the route key to see an audit log for
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: start
          in: query
          description: |
            The beginning of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: end
          in: query
          description: |
            The end of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: max_results
          in: query
          description: |
            Determines how many ChangeDescription object should be returned to
            the calling code.
          required: false
          type: number
          format: int64
        - name: ref_id
          in: query
          description: |
            When paginating a Changelog request start on the entry that comes
            immediately before or after this ID (as determined by the direction
            argument).
          required: false
          type: string
        - name: direction
          in: query
          description: |
            If set to "before" then changes will be returned that occurred before
            reference ID. If "after" then changes will be returned that have
            occurred since the reference ID.
          required: false
          type: string
          enum:
            - before
            - after
      responses:
        200:
          description: A list of changes occurring during the requested window.
          schema:
            $ref: '#/definitions/PaginatedChangeDescriptions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /changelog/shared-rules-graph/{sharedRulesKey}:
    get:
      tags:
        - Audit Log
      summary: get changes related to the indicated SharedRules
      description: |
        Gets all changes associated with set of Shared Rules; the domains using
        it and the clusters referenced by it.
      parameters:
        - name: sharedRulesKey
          in: path
          description: the shared rules key to see an audit log for
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: start
          in: query
          description: |
            The beginning of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: end
          in: query
          description: |
            The end of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: max_results
          in: query
          description: |
            Determines how many ChangeDescription object should be returned to
            the calling code.
          required: false
          type: number
          format: int64
        - name: ref_id
          in: query
          description: |
            When paginating a Changelog request start on the entry that comes
            immediately before or after this ID (as determined by the direction
            argument).
          required: false
          type: string
        - name: direction
          in: query
          description: |
            If set to "before" then changes will be returned that occurred before
            reference ID. If "after" then changes will be returned that have
            occurred since the reference ID.
          required: false
          type: string
          enum:
            - before
            - after
      responses:
        200:
          description: A list of changes occurring during the requested window.
          schema:
            $ref: '#/definitions/PaginatedChangeDescriptions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /changelog/cluster-graph/{clusterKey}:
    get:
      tags:
        - Audit Log
      summary: get changes related to the indicated cluster
      description: |
        Gets all changes to a cluster.
      parameters:
        - name: clusterKey
          in: path
          description: the cluster key to see an audit log for
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: start
          in: query
          description: |
            The beginning of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: end
          in: query
          description: |
            The end of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: max_results
          in: query
          description: |
            Determines how many ChangeDescription object should be returned to
            the calling code.
          required: false
          type: number
          format: int64
        - name: ref_id
          in: query
          description: |
            When paginating a Changelog request start on the entry that comes
            immediately before or after this ID (as determined by the direction
            argument).
          required: false
          type: string
        - name: direction
          in: query
          description: |
            If set to "before" then changes will be returned that occurred before
            reference ID. If "after" then changes will be returned that have
            occurred since the reference ID.
          required: false
          type: string
          enum:
            - before
            - after
      responses:
        200:
          description: A list of changes occurring during the requested window.
          schema:
            $ref: '#/definitions/PaginatedChangeDescriptions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /changelog/zone/{zoneKey}:
    get:
      tags:
        - Audit Log
      summary: get changes in a specified zone
      description: Retrieve all changes in the specified zone.
      parameters:
        - name: zoneKey
          in: path
          description: the zone key to see an audit log for
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: start
          in: query
          description: |
            The beginning of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: end
          in: query
          description: |
            The end of the window we want to see changes for; measured in
            microseconds since Unix Epoch.
          required: false
          type: number
          format: int64
        - name: max_results
          in: query
          description: |
            Determines how many ChangeDescription object should be returned to
            the calling code.
          required: false
          type: number
          format: int64
        - name: ref_id
          in: query
          description: |
            When paginating a Changelog request start on the entry that comes
            immediately before or after this ID (as determined by the direction
            argument).
          required: false
          type: string
        - name: direction
          in: query
          description: |
            If set to "before" then changes will be returned that occurred before
            reference ID. If "after" then changes will be returned that have
            occurred since the reference ID.
          required: false
          type: string
          enum:
            - before
            - after
      responses:
        200:
          description: A list of changes occurring during the requested window.
          schema:
            $ref: '#/definitions/PaginatedChangeDescriptions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /zone:
    get:
      summary: get a list of zones
      description: |
        Get all zones. possibly with filters
      tags:
        - Zone
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of ZoneFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any ZoneFilter will be included.
          type: string
      responses:
        200:
          description: A result containing an array of zones
          schema:
            $ref: '#/definitions/MultiZoneResult'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: create zone
      description: |
        Create a new zone.
      consumes:
        - application/json
      parameters:
        - name: zone
          in: body
          description: the zone to create
          required: true
          schema:
            $ref: "#/definitions/ZoneCreate"
      tags:
        - Zone
      responses:
        200:
          description: A result containing the newly created zone
          schema:
            $ref: "#/definitions/ZoneResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /zone/{zoneKey}:
    get:
      summary: get zone
      description: |
        Get details for a single zone
      tags:
        - Zone
      parameters:
        - name: zoneKey
          in: path
          description: the zone key
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
      responses:
        200:
          description: a result containing a single zone
          schema:
            $ref: "#/definitions/ZoneResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: delete zone
      description: |
        Delete a zone.
      tags:
        - Zone
      parameters:
        - name: zoneKey
          in: path
          description: the zone key
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f0724070000
        - name: checksum
          in: query
          description: the current checksum of the zone to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Empty"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  /domain:
    get:
      tags:
        - Domain
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of DomainFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any DomainFilter will be included.
          type: string
      summary: get domains
      description: Get a list of domains
      responses:
        200:
          description: a result containing a list of domains
          schema:
            $ref: "#/definitions/MultiDomainResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - Domain
      summary: create domain
      description: Create a new domain
      consumes:
        - application/json
      parameters:
        - name: domain
          in: body
          description: the domain to create
          required: true
          schema:
            $ref: "#/definitions/DomainCreate"
      responses:
        200:
          description: the newly created zone
          schema:
            $ref: "#/definitions/DomainResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /domain/{domainKey}:
    get:
      summary: get domain
      description: Get details for a single domain
      tags:
        - Domain
      parameters:
        - name: domainKey
          in: path
          description: the domain key
          required: true
          type: string
          x-example: 48cf1c9b-f027-4223-b405-d48018ffb900
      responses:
        200:
          description: a result containing a single domain
          schema:
            $ref: "#/definitions/DomainResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: delete domain
      description: Delete an existing domain
      tags:
        - Domain
      parameters:
        - name: domainKey
          in: path
          description: the domain key
          required: true
          type: string
          x-example: 48cf1c9b-f027-4223-b405-d48018ffb900
        - name: checksum
          in: query
          description: the current checksum of the domain to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Empty"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  /proxy:
    get:
      tags:
        - Proxy
      summary: list proxies
      description: Get a list of proxies
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of ProxyFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any ProxyFilter will be included.
          type: string
      responses:
        200:
          description: a result containing a list of proxies
          schema:
            $ref: "#/definitions/MultiProxyResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - Proxy
      summary: create proxy
      description: Create a new proxy
      consumes:
        - application/json
      parameters:
        - name: proxy
          in: body
          description: the proxy to create
          required: true
          schema:
            $ref: "#/definitions/ProxyCreate"
      responses:
        200:
          description: the newly created proxy
          schema:
            $ref: "#/definitions/ProxyResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /proxy/{proxyKey}:
    get:
      summary: get proxy
      description: Get details for a single proxy
      tags:
        - Proxy
      parameters:
        - name: proxyKey
          in: path
          description: the proxy key
          required: true
          type: string
          x-example: 72c86057-ee8d-4a2b-a3a7-760fbd1d3b9f
      responses:
        200:
          description: a result containing a single proxy
          schema:
            $ref: "#/definitions/ProxyResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: delete proxy
      description: Delete existing proxy
      tags:
        - Proxy
      parameters:
        - name: proxyKey
          in: path
          description: the proxy key
          required: true
          type: string
          x-example: 72c86057-ee8d-4a2b-a3a7-760fbd1d3b9f
        - name: checksum
          in: query
          description: the current checksum of the proxy to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Proxy"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  /listener:
    get:
      tags:
        - Listener
      summary: list listeners
      description: Get a list of listeners
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of ListenerFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any ListenerFilter will be included.
          type: string
      responses:
        200:
          description: a result containing a list of listeners
          schema:
            $ref: "#/definitions/MultiListenerResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - Listener
      summary: create listener
      description: Create a new listener
      consumes:
        - application/json
      parameters:
        - name: listener
          in: body
          description: the listener to create
          required: true
          schema:
            $ref: "#/definitions/ListenerCreate"
      responses:
        200:
          description: the newly created listener
          schema:
            $ref: "#/definitions/ListenerResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /listener/{listenerKey}:
    get:
      summary: get listener
      description: Get details for a single listener
      tags:
        - Listener
      parameters:
        - name: listenerKey
          in: path
          description: the listener key
          required: true
          type: string
          x-example: 72c86057-ee8d-4a2b-a3a7-760fbd1d3b9f
      responses:
        200:
          description: a result containing a single listener
          schema:
            $ref: "#/definitions/ListenerResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: modify listener
      description: Modify an existing listener
      tags:
        - Listener
      consumes:
        - application/json
      parameters:
        - name: listenerKey
          in: path
          description: the listener key
          required: true
          type: string
          x-example: 5074fe62-821e-4034-55bd-b9caa09af2a1
        - name: listener
          in: body
          description: the listener to modify
          required: true
          schema:
            $ref: "#/definitions/Listener"
      responses:
        200:
          description: A result containing the modified cluster
          schema:
            $ref: "#/definitions/ListenerResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    delete:
      summary: delete listener
      description: Delete existing listener
      tags:
        - Listener
      parameters:
        - name: listenerKey
          in: path
          description: the listener key
          required: true
          type: string
          x-example: 72c86057-ee8d-4a2b-a3a7-760fbd1d3b9f
        - name: checksum
          in: query
          description: the current checksum of the listener to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Listener"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  /shared_rules:
    get:
      summary: get shared_rules
      description: Get a list of shared_rules
      tags:
        - Shared Rules
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of SharedRulesFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any SharedRulesFilter will be included.
          type: string
      responses:
        200:
          description: a result containing a list of shared_rules
          schema:
            $ref: "#/definitions/MultiSharedRulesResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      summary: create shared_rules
      description: Create a new shared_rules object
      tags:
        - Shared Rules
      consumes:
        - application/json
      parameters:
        - name: shared_rules
          in: body
          description: the shared_rules object to create
          required: true
          schema:
            $ref: "#/definitions/SharedRulesCreate"
      responses:
        200:
          description: the newly created shared_rules object
          schema:
            $ref: "#/definitions/SharedRulesResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /shared_rules/{sharedRulesKey}:
    get:
      summary: get shared_rules object
      description: Get details for an existing shared_rules object
      tags:
        - Shared Rules
      parameters:
        - name: sharedRulesKey
          in: path
          description: the shared_rules key
          required: true
          type: string
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      responses:
        200:
          description: a result containing a single shared_rules object
          schema:
            $ref: "#/definitions/SharedRulesResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: modify shared_rules object
      description: Modify an existing shared_rules object
      tags:
        - Shared Rules
      consumes:
        - application/json
      parameters:
        - name: sharedRulesKey
          in: path
          description: the shared_rules key
          required: true
          type: string
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
        - name: shared_rules
          in: body
          description: the shared_rules object to modify
          required: true
          schema:
            $ref: "#/definitions/SharedRules"
      responses:
        200:
          description: A result containing the modified shared_rules object
          schema:
            $ref: "#/definitions/SharedRulesResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    delete:
      summary: delete shared_rules object
      description: Delete an existing shared_rules object
      tags:
        - Route
      parameters:
        - name: sharedRulesKey
          in: path
          description: the shared_rules key
          required: true
          type: string
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
        - name: checksum
          in: query
          description: the current checksum of the shared_rules to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Empty"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  /route:
    get:
      summary: get routes
      description: Get a list of routes
      tags:
        - Route
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of RouteFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any RouteFilter will be included.
          type: string
      responses:
        200:
          description: a result containing a list of routes
          schema:
            $ref: "#/definitions/MultiRouteResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      summary: create route
      description: Create a new route
      tags:
        - Route
      consumes:
        - application/json
      parameters:
        - name: route
          in: body
          description: the route to create
          required: true
          schema:
            $ref: "#/definitions/RouteCreate"
      responses:
        200:
          description: the newly created route
          schema:
            $ref: "#/definitions/RouteResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /route/{routeKey}:
    get:
      summary: get route
      description: Get details for an existing route
      tags:
        - Route
      parameters:
        - name: routeKey
          in: path
          description: the route key
          required: true
          type: string
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      responses:
        200:
          description: a result containing a single route
          schema:
            $ref: "#/definitions/RouteResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: modify route
      description: Modify an existing route
      tags:
        - Route
      consumes:
        - application/json
      parameters:
        - name: routeKey
          in: path
          description: the route key
          required: true
          type: string
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
        - name: route
          in: body
          description: the route to modify
          required: true
          schema:
            $ref: "#/definitions/Route"
      responses:
        200:
          description: A result containing the modified route
          schema:
            $ref: "#/definitions/RouteResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    delete:
      summary: delete route
      description: Delete an existing route
      tags:
        - Route
      parameters:
        - name: routeKey
          in: path
          description: the route key
          required: true
          type: string
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
        - name: checksum
          in: query
          description: the current checksum of the route to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Empty"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  /cluster:
    get:
      summary: get clusters
      description: Get a list of clusters
      tags:
        - Cluster
      parameters:
        - name: filters
          in: query
          description: |
            A JSON encoded array of ClusterFilter objects. The filter is taken
            as a union of intersections. In other words an object that matches
            every constraint in any ClusterFilter will be included.
          type: string
      responses:
        200:
          description: a result containing a list of clusters
          schema:
            $ref: "#/definitions/MultiClusterResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    post:
      summary: create cluster
      description: Create a new cluster
      tags:
        - Cluster
      consumes:
        - application/json
      parameters:
        - name: cluster
          in: body
          description: the cluster to create
          required: true
          schema:
            $ref: "#/definitions/ClusterCreate"
      responses:
        200:
          description: the newly created cluster
          schema:
            $ref: "#/definitions/ClusterResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /cluster/{clusterKey}:
    get:
      summary: get cluster
      description: Get details for an existing cluster
      tags:
        - Cluster
      parameters:
        - name: clusterKey
          in: path
          description: the cluster key
          required: true
          type: string
          x-example: 7ef80556-60bb-46bd-4cec-f4e2533aa75c
      responses:
        200:
          description: a result containing a single cluster
          schema:
            $ref: "#/definitions/ClusterResult"
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: modify cluster
      description: Modify an existing cluster
      tags:
        - Cluster
      consumes:
        - application/json
      parameters:
        - name: clusterKey
          in: path
          description: the cluster key
          required: true
          type: string
          x-example: 5074fe62-821e-4034-55bd-b9caa09af2a1
        - name: cluster
          in: body
          description: the cluster to modify
          required: true
          schema:
            $ref: "#/definitions/Cluster"
      responses:
        200:
          description: A result containing the modified cluster
          schema:
            $ref: "#/definitions/ClusterResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    delete:
      summary: delete cluster
      description: Delete an existing cluster
      tags:
        - Cluster
      parameters:
        - name: clusterKey
          in: path
          description: the cluster key
          required: true
          type: string
          x-example: 7ef80556-60bb-46bd-4cec-f4e2533aa75c
        - name: checksum
          in: query
          description: the current checksum of the cluster to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Empty"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /cluster/{clusterKey}/instances:
    post:
      tags:
        - Cluster
      summary: add instance
      description: Add a new instance to a cluster
      consumes:
        - application/json
      parameters:
        - name: clusterKey
          in: path
          description: the cluster to add the instance to
          type: string
          required: true
          x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
        - name: instance
          in: body
          description: the instance to add
          required: true
          schema:
            $ref: "#/definitions/Instance"
      responses:
        200:
          description: the newly created instance
          schema:
            $ref: "#/definitions/InstanceResult"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
  /cluster/{clusterKey}/instances/{instanceIdentifier}:
    delete:
      summary: remove instance
      description: Remove an instance from a cluster
      tags:
        - Cluster
      parameters:
        - name: checksum
          in: query
          description: the current checksum of the instance to be deleted
          required: true
          type: string
          x-example: 9cd24183-f848-48f8-6f55-0f07240700b9
        - name: clusterKey
          in: path
          type: string
          required: true
          description: the cluster to remove an instance from
          x-example: 7ef80556-60bb-46bd-4cec-f4e2533aa75c
        - name: instanceIdentifier
          in: path
          type: string
          required: true
          description: the instance to remove, identified as <host>:<port>
          x-example: foo-1.useast.test.com:8080
      responses:
        200:
          description: an empty result
          schema:
            $ref: "#/definitions/Empty"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string

  Zone:
    type: object
    required:
      - zone_key
      - name
      - checksum
    properties:
      checksum:
        type: string
      zone_key:
        type: string
      name:
        type: string

  ZoneCreate:
    type: object
    required:
      - name
    properties:
      name:
        type: string

  MultiZoneResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: '#/definitions/Zone'

  ZoneResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Zone"

  Domain:
    allOf:
      - $ref: "#/definitions/DomainCreate"
      - type: object
        required:
        - domain_key
        - checksum
        properties:
          domain_key:
            type: string
          checksum:
            type: string

  DomainCreate:
    type: object
    required:
      - zone_key
      - name
      - port
    properties:
      domain_key:
        type: string
      zone_key:
        type: string
      name:
        type: string
      port:
        type: integer
      checksum:
        type: string
      redirects:
        type: array
        items:
          $ref: "#/definitions/Redirect"
      gzip_enabled:
        description: "Experimental: if set to true will enable gzip compression on data that passes trough this domain"
        type: boolean
      ssl_config:
        $ref: "#/definitions/SSLConfig"
      cors_config:
         $ref: "#/definitions/CORSConfig"
      aliases:
        description: |
          A set of alternate names that this Domain may be referenced by. May
          start ('*.') or end ('.*') with a wildcard.
        type: array
        items:
          type: string
      force_https:
        description: |
          If set to true, requests must use TLS. If a request is not using TLS, (as determined by
          the scheme or the presence of X-Forwarded-Proto header), a 301 redirect will be sent
          telling the client to use HTTPS.
        type: boolean

  Redirect:
    description: |
      Specifies how a URL within a domain should be rewritten when requested.
    type: object
    required:
      - name
      - from
      - to
      - redirect_type
    properties:
      name:
        description: A unique (to this Domain) name for the Redirect. Must match the regexp "^[0-9a-zA-Z-]+$"
        type: string
      from:
        description: A regexp that will be matched against the URL (not including the host/port). May include capture groups for reference in "to."
        type: string
      to:
        description: The new URL that will be constructed from the request. Capture groups from "from" may be referenced as "$&lt;group number&gt;" which begins at 1.
        type: string
      redirect_type:
        description: How this redirect should be presented via HTTP response code.
        type: string
        enum:
          - permanent
          - temporary
      header_constraints:
        type: array
        items:
          $ref: "#/definitions/HeaderConstraint"

  HeaderConstraint:
    description: |
      Indicates that a request's headers should meet some requirement before being
      selected for a rewrite. Must have zore or one elements.
    type: object
    required:
      - name
    properties:
      name:
        description: |
          The header that is being checked. This must match the regexp "^[0-9a-zA-Z-]+$".
          This is checked in a case insensitive manner.
        type: string
      value:
        description: |
          If set the header's value will be compared to this. The default is to
          make case insensitive comparisons.
        type: string
      case_sensitive:
        description: If set, the header value check will be case sensitive.
        type: boolean
      invert:
        description: |
          If set, the header constraint will succeed if the match described faile.
        type: boolean

  SSLConfig:
    description: |
      Experimental: Specifies whether a domain should support SSL/TLS
      connections from clients.  If not set the proxy will expect unencrypted HTTP
      traffic.
    type: object
    required:
      - cert_key_pairs
    properties:
      cert_key_pairs:
        description: "SSLConfig must have one cert_key_pairs entry specified."
        type: array
        items:
          $ref: "#/definitions/CertKeyPathPair"
      cipher_filter:
        description: |
          An OpenSSL compatible filter string indicating the ciphers acceptable
          for this proxy to use while communicating with clients. The default value
          is EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH. For more information
          see https://wiki.openssl.org/index.php/Manual:Ciphers(1)
        type: string
      protocols:
        description: |
          A list of acceptable SSL/TLS protocol. The default values are TLSv1,
          TLSv1.1, TLSv1.2. Additional valid values are SSLv2 and SSLv3.
        type: array
        items:
          type: string
  CORSConfig:
    type: object
    description: |
      Experimental: Controls simple CORS responses for the associated domain.
      The configurable properties map closely to the CORS specification which
      should be referenced for a full discussion on their meaning:
      https://www.w3.org/TR/cors/ or https://developer.mozilla.org/docs/Web/HTTP/Access_control_CORS.
    required:
      - allowed_origins
      - allowed_methods
    properties:
      allowed_origins:
        description: |
          Must contain a single element specifying the domain (origin) allowed
          to make requsets to this domain. If any origin is acceptable '*' may
          be used as a wildcard https://www.w3.org/TR/cors/#origin-request-header,
          https://www.w3.org/TR/cors/#access-control-allow-origin-response-header.
        type: array
        items:
          type: string
      allow_credentials:
        description: |
          Indicates whether the response to request can be exposed when the
          omit credentials flag is unset
          https://www.w3.org/TR/cors/#access-control-allow-credentials-response-header.
        type: boolean
      exposed_headers:
        description: |
          Indicates which response headers may be accessed from the browser.
          https://www.w3.org/TR/cors/#http-access-control-expose-headers.
        type: array
        items:
          type: string
      max_age:
        description: |
          Sets how long (in seconds) the response to a preflight request may be
          cached. A value of -1 will disable caching. https://www.w3.org/TR/cors/#access-control-max-age-response-header.
        type: integer
      allowed_methods:
        description: |
          Indicates which HTTP request types may be used to call an endpoint.
          https://www.w3.org/TR/cors/#access-control-allow-methods-response-header.
        type: array
        items:
          type: string
      allowed_headers:
        description: |
          Specifies what headers are allowed to be set when a request is made.
          https://www.w3.org/TR/cors/#access-control-allow-headers-response-header.
        type: array
        items:
          type: string
  CertKeyPathPair:
    description: |
      A key/cert pair that will be served when a domain terminates a SSL/TLS
      request.  Paths should be absolute and accessible to the user running
      the proxy instance.
    type: object
    required:
      - certificate_path
      - key_path
    properties:
      certificate_path:
        description: |
          Path to a certificate in the PEM format for the domain. If multiple
          certificates need to be specified then should be contained in this file
          in the following order: first the primary certificate followed by any
          intermediary certificats.
        type: string
      key_path:
        description: |
          Path to a file with the secret key in the PEM format for the domain.
        type: string

  MultiDomainResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/Domain"

  DomainResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Domain"

  Proxy:
    allOf:
      - $ref: "#/definitions/ProxyCreate"
      - type: object
        required:
        - proxy_key
        - zone_key
        - checksum
        properties:
          proxy_key:
            type: string
          checksum:
            type: string

  ProxyCreate:
    type: object
    required:
      - zone_key
      - name
    properties:
      name:
        type: string
      zone_key:
        type: string
      domain_keys:
        type: array
        items:
          type: string
      listener_keys:
        type: array
        items:
          type: string

  MultiProxyResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/Proxy"

  ProxyResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Proxy"

  Listener:
    allOf:
      - $ref: "#/definitions/ListenerCreate"
      - type: object
        required:
        - listener_key
        - zone_key
        - checksum
        properties:
          listener_key:
            x-example: 9cd24183-f848-48f8-6f55-0f0724070000
            type: string
          checksum:
            type: string

  ListenerCreate:
    type: object
    required:
      - listener_key
      - name
      - host
      - port
      - protocol
    properties:
      name:
        x-example: http-web
        type: string
      ip:
        x-example: 0.0.0.0
        description: the interface this listener should bind to.
        type: string
      port:
        x-example: 80
        description: the port this listener should bind to.
        type: integer
      protocol:
        description: |
          the protocol this listener will handle. http and http2 configure the listener to only
          process requests of that type. http_auto will adapt to HTTP/1.1 and HTTP/2 as needed.
          tcp configures the listener to be a tcp proxy
        type: string
        enum:
          - http
          - http2
          - http_auto
          - tcp
      domain_keys:
        x-example: ["9cd24183-f848-48f8-6f55-0f0724070000", "9cd24183-f848-48f8-6f55-0f0724070001"]
        type: array
        items:
          type: string
      tracing_config:
        $ref: "#/definitions/TracingConfig"
      zone_key:
        type: string

  MultiListenerResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/Listener"

  ListenerResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Listener"

  TracingConfig:
    description: |
      Configures tracing operations to be performed on the given listener
    type: object
    properties:
      ingress:
        x-example: true
        type: boolean
        description: |
          Determines whether spans sent from this listener should be treated as ingress
          or egress operations.
      request_headers_for_tags:
        description: |
          the headers specified here will be added to the generated spans as annotations
        x-example: ['x-forwarded-for', 'x-user-id']
        type: array
        items:
          type: string

  Route:
    allOf:
      - $ref: "#/definitions/RouteCreate"
      - type: object
        required:
        - route_key
        - checksum
        properties:
          route_key:
            type: string
          checksum:
            type: string

  RouteCreate:
    type: object
    required:
      - domain_key
      - zone_key
      - path
      - shared_rules_key
    properties:
      route_key:
        type: string
      domain_key:
        type: string
      zone_key:
        type: string
      shared_rules_key:
        type: string
      path:
        type: string
      checksum:
        type: string
      rules:
        type: array
        items:
          $ref: "#/definitions/Rule"
      response_data:
        description: |
          When a request is served by this Route annotate the response with the
          information specified within this ResponseData object. It's possible
          that multiple response data configurations will apply; if that's the
          case then the values from Route take precedence over those from a
          SharedRules object.
        allOf:
          - $ref: "#/definitions/ResponseData"
      cohort_seed:
        $ref: "#/definitions/CohortSeed"
      retry_policy:
        $ref: "#/definitions/RetryPolicy"

  Rule:
    type: object
    properties:
      rule_key:
        type: string
      methods:
        type: array
        items:
          type: string
      matches:
        $ref: "#/definitions/Matches"
      constraints:
        $ref: "#/definitions/AllConstraints"
      cohort_seed:
        $ref: "#/definitions/CohortSeed"

  Matches:
    type: array
    items:
      $ref: "#/definitions/Match"

  Match:
    type: object
    description: |
      Represents a mapping of request attributes to constraints on a cluster
      using different matching schemes.

      Certain combinations of `kind` and `behavior` are not allowed
        | kind | behavior |
        | ---- | -------- |
        | query | regex |
        | query | range |
        | cookie | range |
    properties:
      kind:
        type: string
        description: |
          Defines the attribute by which a request should be matched on. Valid
          values are
            * cookie
            * header
            * query (for query parameter)
      behavior:
        type: string
        description: |
          Defines how a request attribute should be matched. If not specified,
          defaults to `exact`. Valid values are
            * exact
            * regex
            * range
            * prefix
            * suffix
      from:
        allOf:
          - $ref: "#/definitions/Metadatum"
        description: |
          The request attribute key and value to match. `key` must always be
          defined while `value` can be unspecified (only if behavior is set to
          `exact`) to indicate that all values should be matched. If to.value
          is also unspecified, the matched value of the request will be used as
          a constraint on the destination cluster.

          \# Behavior
            * `regex` if To.Value is unspecified, `value` must contain one and
            only one subgroup. Otherwise, `value` must not be empty.
            * `range` `value` must be specified and must be of the format
            `[start_integer, end_integer)`. Start and end must be valid integer
            values and `end_integer` must be greater than `start_integer`.
            * `prefix`/`suffix` `value` must be specified

          \# Kind
            * `cookie` does not support `range` behavior
            * `query` does not support `regex` behavior
      to:
        allOf:
          - $ref: "#/definitions/Metadatum"
        description: |
          The constraints on a cluster that a matched request should map to. If
          to.key is specified and to.value is not, the matched from.value will
          be used as a metadata constraint on instances in the destination
          cluster, keyed by to.key. If using `regex` behavior with multiple
          subgroups in from.value, variables `$1` through `$n`, where n is the
          number of subgroups in the matching regex, can be used to interpolate
          captured matches in to.value.

  Metadatum:
    type: object
    properties:
      key:
        type: string
      value:
        type: string

  Metadata:
    type: array
    items:
      $ref: "#/definitions/Metadatum"

  AllConstraints:
    type: object
    required:
      - light
    properties:
      light:
        $ref: "#/definitions/ClusterConstraints"
      dark:
        $ref: "#/definitions/ClusterConstraints"
      tap:
        $ref: "#/definitions/ClusterConstraints"

  ClusterConstraints:
    type: array
    items:
      $ref: "#/definitions/ClusterConstraint"

  ClusterConstraint:
    type: object
    properties:
      constraint_key:
        type: string
      cluster_key:
        type: string
      metadata:
        $ref: "#/definitions/Metadata"
      properties:
        $ref: "#/definitions/Metadata"
      response_data:
        allOf:
          - $ref: "#/definitions/ResponseData"
        description: |
          When a request is served by a cluster selected by this constraint annotate
          the response with the information specified within this ResponseData
          object. It's possible that multiple response data configurations will
          apply; if that's the case then the values from ClusterConstarint takes
          precedence over those from a Route or SharedRules object.
      weight:
        type: integer

  MultiRouteResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/Route"

  RouteResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Route"

  Cluster:
    allOf:
      - $ref: "#/definitions/ClusterCreate"
      - type: object
        required:
        - cluster_key
        - checksum
        properties:
          cluster_key:
            type: string
          checksum:
            type: string

  ClusterCreate:
    type: object
    required:
      - zone_key
      - name
    properties:
      zone_key:
        type: string
      name:
        type: string
      require_tls:
        description: |
          If set, requests to this collection of hosts will be made via HTTPS.
          At this time neither certificate validation and certificate pinning
          are supported for proxy clients of this cluster.
        type: boolean
      instances:
        $ref: "#/definitions/Instances"
      circuit_breakers:
        $ref: "#/definitions/CircuitBreakers"
      outlier_detection:
        $ref: "#/definitions/OutlierDetection"
      health_checks:
        $ref: "#/definitions/HealthChecks"

  Instances:
    type: array
    items:
      $ref: "#/definitions/Instance"

  Instance:
    type: object
    properties:
      host:
        type: string
      port:
        type: integer
      metadata:
        $ref: "#/definitions/Metadata"

  MultiClusterResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/Cluster"

  ClusterResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Cluster"
  InstanceResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/Instance"
  Empty:
    type: object

  CircuitBreakers:
    description: |
      Provides limits on various parameters to protect clusters against sudden
      surges in traffic.
    type: object
    properties:
      max_connections:
        type: integer
        description: |
          Maximum number of connections that will be established to all
          instances in a cluster within a proxy. If set to 0, no new connections
          will be created. If not specified, defaults to 1024.
      max_pending_requests:
        type: integer
        description: |
          Maximum number of requests that will be queued while waiting on a
          connection pool to a cluster within a proxy. If set to 0, no requests
          will be queued. If not specified, defaults to 1024.
      max_retries:
        type: integer
        description: |
          Maximum number of retries that can be outstanding to all instances in
          a cluster within a proxy. If set to 0, requests will not be retried.
          If not specified, defaults to 3.
      max_requests:
        type: integer
        description: |
          Maximum number of requests that can be outstanding to all instances in
          a cluster within  a proxy. Only applicable to HTTP/2 traffic since
          HTTP/1.1 clusters are governed by the maximum connections circuit
          breaker. If set to 0, no requests will be made. If not specified,
          defaults to 1024.

  HealthChecks:
    type: array
    items:
      $ref: "#/definitions/HealthCheck"

  HealthCheck:
    description: |
      Configures active health checking for every instance in a cluster.
    type: object
    required:
      - timeout_msec
      - interval_msec
      - unhealthy_threshold
      - healthy_threshold
      - health_checker
    properties:
      timeout_msec:
        type: integer
        description: |
          The time to wait for a health check response. If the timeout is
          reached without a response, the health check attempt will be
          considered a failure. This is a required field and must be greater
          than 0.
      interval_msec:
        type: integer
        description: |
          The interval between health checks. The first round of health checks
          will occur during startup before any traffic is routed to a cluster.
          This means that the \'no_traffic_interval_msec\' value will be used as
          the first interval of health checks.
      interval_jitter_msec:
        type: integer
        description: |
          An optional jitter amount that is added to each interval value
          calculated by the proxy. If not specified, defaults to 0.
      unhealthy_threshold:
        type: integer
        description: |
          The number of unhealthy health checks required before a host is
          marked unhealthy. Note that for *http* health checking, if a host
          responds with 503, this threshold is ignored and the host is
          considered unhealthy immediately.
      healthy_threshold:
        type: integer
        description: |
          The number of healthy health checks required before a host is marked
          healthy. Note that during startup, only a single successful health
          check is required to mark a host healthy.
      reuse_connection:
        type: boolean
        description: |
          Whether or not to reuse health check connections between health checks.
          Default is true.
      no_traffic_interval_msec:
        type: integer
        description: |
          Interval used when a cluster has never had traffic routed to it. It
          allows cluster information to be kept up to date, without sending a
          potentially large amount of active health checking traffic for no
          reason. Once a cluster has been used for traffic routing, The proxy
          will shift back to using the standard health check interval that is
          defined. Note that this interval takes precedence over any other.
          Defaults to 60s.
      unhealthy_interval_msec:
        type: integer
        description: |
          Interval used for hosts that are marked as unhealthy. As soon as the
          host is marked as healthy, The proxy will shift back to using the
          standard health check interval that is defined. This defaults to the
          same value as \'interval_msec\' if not specified.
      unhealthy_edge_interval_msec:
        type: integer
        description: |
          Interval used for the first health check right after a host is marked
          as unhealthy. For subsequent health checks, the proxy will shift back
          to using either \'unhealthy_interval_msec\' if present or the standard
          health check interval, \'interval_msec\'.
      healthy_edge_interval_msec:
        type: integer
        description: |
          Interval used for the first health check right after a host is marked
          as healthy. For subsequent health checks, the proxy will shift back to
          using the standard health check interval(\'interval_msec\') that is
          defined. Defaults to the same value as \'interval_msec\' if not
          specified.
      health_checker:
        type: object
        description: |
          Defines the type of health checker to use. Only a single health
          checker can be defined per HealthCheck.
        properties:
          http_health_check:
            $ref: "#/definitions/HTTPHealthCheck"
          tcp_health_check:
            $ref: "#/definitions/TCPHealthCheck"

  HTTPHealthCheck:
    type: object
    properties:
      host:
        type: string
        description: |
          The value of the host header in the HTTP health check request.
          If left empty, the name of the cluster being health checked
          will be used.
      path:
        type: string
        description: |
          Specifies the HTTP path that will be requested during health
          checking.
      service_name:
        type: string
        description: |
          An optional service name parameter which is used to validate
          the identity of the health checked cluster.
      request_headers_to_add:
        allOf:
          - $ref: "#/definitions/Metadata"
        description: |
          Specifies a list of HTTP headers that should be added to each request
          sent to the health checked cluster.

  TCPHealthCheck:
    type: object
    properties:
      send:
        type: string
        description: |
          Base64 encoded string representing an array of bytes to be
          sent in health check requests. Leaving this field empty
          implies a connect-only health check.
      receive:
        type: array
        items:
          type: string
        description: |
          An array of base64 encoded strings, each representing array of
          bytes that is expected in health check responses. When
          checking the response, "fuzzy" matching is performed such that
          each binary block must be found, and in the order specified,
          but not necessarily contiguously.

  OutlierDetection:
    description: |
      A form of passive health checking that dynamically determines whether
      instances in a cluster are performing unlike others and preemptively
      removes them from a load balancing set.
    type: object
    properties:
      interval_msec:
        type: integer
        description: |
          The time interval between ejection analysis sweeps. This can result in
          both new ejections due to success rate outlier detection as well as
          hosts being returned to service. Defaults to 10s and must be greater
          than 0.
      base_ejection_time_msec:
        type: integer
        description: |
          The base time that a host is ejected for. The real time is equal to
          the base time multiplied by the number of times the host has been
          ejected. Defaults to 30s. Setting this to 0 means that no host will
          be ejected for longer than `interval_msec`.
      max_ejection_percent:
        type: integer
        description: |
          The maximum % of an upstream cluster that can be ejected due to
          outlier detection. Defaults to 10% but will always eject at least one
          host.
      consecutive_5xx:
        type: integer
        description: |
          The number of consecutive 5xx responses before a consecutive 5xx ejection
          occurs. Defaults to 5. Setting this to 0 effectively turns off the
          consecutive 5xx detector.
      enforcing_consecutive_5xx:
        type: integer
        description: |
          The % chance that a host will be actually ejected when an outlier status
          is detected through consecutive 5xx. This setting can be used to disable
          ejection or to ramp it up slowly. Defaults to 100.
      enforcing_success_rate:
        type: integer
        description: |
          The % chance that a host will be actually ejected when an outlier status
          is detected through success rate statistics. This setting can be used to
          disable ejection or to ramp it up slowly. Defaults to 100.
      success_rate_minimum_hosts:
        type: integer
        description: |
          The number of hosts in a cluster that must have enough request volume to
          detect success rate outliers. If the number of hosts is less than this
          setting, outlier detection via success rate statistics is not performed
          for any host in the cluster. Defaults to 5. Setting this to 0 effectively
          triggers the success rate detector regardless of the number of valid hosts
          during an interval (as determined by `success_rate_request_volume`).
      success_rate_request_volume:
        type: integer
        description: |
          The minimum number of total requests that must be collected in one
          interval (as defined by interval_msec) to include this host
          in success rate based outlier detection. If the volume is lower than this
          setting, outlier detection via success rate statistics is not performed
          for that host. Defaults to 100. Must be greater than 0.
      success_rate_stdev_factor:
        type: integer
        description: |
          This factor is used to determine the ejection threshold for success rate
          outlier ejection. The ejection threshold is the difference between the
          mean success rate, and the product of this factor and the standard
          deviation of the mean success rate: mean - (stdev *
          success_rate_stdev_factor). This factor is divided by a thousand to get a
          double. That is, if the desired factor is 1.9, the runtime value should
          be 1900. Defaults to 1900. Setting this to 0 effectively turns off the
          success rate detector.
      consecutive_gateway_failure:
        type: integer
        description: |
          The number of consecutive gateway failures (502, 503, 504 status or
          connection errors that are mapped to one of those status codes) before a
          consecutive gateway failure ejection occurs. Defaults to 5. Setting this
          to 0 effectively turns off the consecutive gateway failure detector.
      enforcing_consecutive_gateway_failure:
        type: integer
        description: |
          The % chance that a host will be actually ejected when an outlier status
          is detected through consecutive gateway failures. This setting can be
          used to disable ejection or to ramp it up slowly. Defaults to 0.

  SharedRules:
    allOf:
      - $ref: "#/definitions/SharedRulesCreate"
      - type: object
        required:
        - shared_rules_key
        - checksum
        properties:
          shared_rules_key:
            type: string
          checksum:
            type: string

  SharedRulesCreate:
    type: object
    required:
      - name
      - zone_key
      - default
    properties:
      shared_rules_key:
        type: string
      zone_key:
        type: string
      default:
        $ref: "#/definitions/AllConstraints"
      rules:
        type: array
        items:
          $ref: "#/definitions/Rule"
      response_data:
        allOf:
          - $ref: "#/definitions/ResponseData"
        description: |
          When a request is served by a Route that is part of this SharedRules
          group the response is annotated with the information specified within
          this ResponseData object. It's possible that multiple response data
          configurations will apply; if that's the case then the values from
          the applicable Route and ClusterConstarint takes precedence over those
          specified here.
      cohort_seed:
        $ref: '#/definitions/CohortSeed'
      retry_policy:
        $ref: '#/definitions/RetryPolicy'
      properties:
        $ref: "#/definitions/Metadata"
      checksum:
        type: string

  MultiSharedRulesResult:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/SharedRules"

  SharedRulesResult:
    type: object
    properties:
      result:
        $ref: "#/definitions/SharedRules"

  PaginatedChangeDescriptions:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: '#/definitions/ChangeDescription'
      details:
        $ref: '#/definitions/PaginationDetails'

  PaginationDetails:
    type: object
    properties:
      pagination:
        $ref: '#/definitions/PageDetails'

  PageDetails:
    type: object
    properties:
      total_entries:
        type: integer
        description: |
          How many total entries would have been returned in the time window
          if it had not been paginated.
      has_more:
        type: boolean
        description: Whether or not there are more entries to be requested after this page.
      direction:
        description: The direction walked from the ref_id when building this page.
        type: string
        enum:
          - before
          - after
      ref_id:
        type: string
        description: The ID used as a reference when building this page.

  ChangeDescription:
    type: object
    properties:
      at:
        type: number
        format: int64
        description: When the change took place in milliseconds since the Unix epoch.
      txn:
        type: string
        description: |
          A unique identifier for all this transaction. It is shared by all
          attribute updates within a change.
        x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      actor_key:
        type: string
        description: The user who made the change.
        x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      comment:
        type: string
        description: A description of the change.
      diffs:
        description: A collection of attribute updates that compose this change.
        type: array
        items:
          $ref: '#/definitions/ChangeEntry'

  CohortSeed:
    type: object
    properties:
      type:
        type: string
        description: Where a request's cohort seed will be drawn from.
        enum:
          - header
          - cookie
          - query
      name:
        type: string
        description: |
          The name of the cookie, the header field, or the query argument to
          be checked for a cohort seed value.
      use_zero_value_seed:
        type: boolean
        description: |
          If true, requests with a seed source which resolves to an empty value
          will still be grouped and routed consistently. This means a misspelled
          or missing seed source on a request will sort all such traffic into a
          single backend. This could result in all traffic being assigned to a
          backend intended for only a small percentage of traffic. Use with
          caution.

  ChangeEntry:
    type: object
    properties:
      object_type:
        type: string
        description: The name of the object being being altered.
        enum:
          - org
          - user
          - zone
          - proxy
          - domain
          - route
          - shared_rules
          - cluster
      change_type:
        type: string
        description: Whether the value was added or removed to the object.
        enum:
          - addition
          - removal
      object_key:
        type: string
        description: An ID uniquely identifying the object being changed.
        x-example: 9cd24183-f848-48f8-6f55-0f0724070000
      zone_key:
        type: string
        description: The zone this object is located in.
        x-example: 9cd24183-f848-48f8-6f55-0f0724070000
      path:
        type: string
        description: A dot-separated / bracket-indexed path to the field changed on the object.
        x-example: cluster.instance[10.0.1.5:8080].metadata[pod-template-hash]
      value:
        type: string
        description: |
          The value that has been added or removed to the object at the attribute
          path indicated in path.

  TimeRange:
    type: object
    properties:
      start:
        description: The beginning of the window we want to see changes for; measured in microseconds since Unix Epoch.
        type: integer
        format: int64
      end:
        description: |
          The end of the window we want to see changes for; measured in
          microseconds since Unix Epoch.
        type: integer
        format: int64

  RetryPolicy:
    description: Number of times to retry a request and how long to wait before timing out.
    type: object
    properties:
      num_retries:
        type: integer
        format: int64
        description: |
          Number of times to retry an upstream request. Note that the initial
          connection attempt is not included in this number, hence 0 means initial
          attempt and no retries, and 1 means initial attempt plus one retry.

      per_try_timeout_msec:
        type: integer
        format: int64
        description: Time limit in milliseconds for a single attempt.

      timeout_msec:
        type: integer
        format: int64
        description: |
          Total time limit in milliseconds for all attempts (including the initial attempt)

  ResponseData:
    type: object
    properties:
      headers:
        type: array
        items:
          $ref: '#/definitions/HeaderDatum'
      cookies:
        type: array
        items:
          $ref: '#/definitions/CookieDatum'

  HeaderDatum:
    description: |
      This describes a HTTP header that should be attached to requests.
    type: object
    properties:
      name:
        type: string
        description: |
          The name of the header that will be attached to the response sent.
          This is case insensitive.
      value:
        type: string
        description: |
          A literal value to send as the header value or a reference to
          some metadatum value set on the Cluster Intsance that handles
          a specific request. If this value is empty after looking up an
          Instance metadatum value no header will be sent.
      value_is_literal:
        type: boolean
        description: |
          If true then the value attribute is treated as a literal and no attempt
          to resolve instance metadatum to find a value.

  CookieDatum:
    description: |
      This describes a cookie that should be set in response to a HTTP request.
    type: object
    properties:
      name:
        type: string
        description: The name of the cookie that will be attached to the response sent.
      value:
        type: string
        description: |
          A literal value to send as the cookie value or a reference to
          some metadatum value set on the Cluster Intsance that handles
          a specific request.
      value_is_literal:
        type: boolean
        description: |
          If true then the value attribute is treated as a literal and no attempt
          to resolve to a server metadatum.
      expires_in_sec:
        type: integer
        description: |
          This indicates how long a cookie will be valid, in seconds. If not set the
          default is to provide no expiration information. If set to 0 the cookie will
          have an 'Expires' attribute set to 'Mon, 1 Jan 0001 12:00:00 UTC'. For values
          greater than 0 the cookie's 'Max-Age' attribute will be set to that value.
      domain:
        type: string
        description: |
          Specifies the hosts to hich a cookie will be sent. Maps directly to a
          cookie's 'Domain' attribute.
      path:
        type: string
        description: |
          Specifies the path a cookie will be associated with. Maps directly to
          the 'Path' attribute.
      secure:
        type: boolean
        description: |
          If set the cookie will only be sent on subsequent requests when accessing
          a server via HTTPS. Maps directly to 'Secure' attribute.
      http_only:
        type: boolean
        description: |
          If set the cookie value will not be accessible via Document.cookie. Maps
          directly to 'HttpOnly' attribute.
      same_site:
        type: string
        enum:
          - Strict
          - Lax
        description: |
          Allows assertions how a cookie should behave wend making cross-site requests.
          Maps directly to 'SameSite' attribute. If unset no guidance will be included
          in the cookie.

  Filter:
    type: object
    properties:
      negative_match:
        type: boolean
        description: |
          If set this filter will match the all ChangeEntry records that do
          NOT meet the constraints laid out in this Filter object.
      time_range:
        $ref: '#/definitions/TimeRange'
      object_type:
        type: string
        description: The name of the object being being altered.
        enum:
          - org
          - user
          - zone
          - proxy
          - domain
          - route
          - shared_rules
          - cluster
      object_key:
        type: string
        description: An ID uniquely identifying the object being changed.
        x-example: 9cd24183-f848-48f8-6f55-0f0724070000
      change_txn:
        type: string
        description: |
          A unique identifier for all this transaction. It is shared by all
          attribute updates within a change.
        x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      zone_key:
        type: string
        description: The zone this object is located in.
        x-example: 9cd24183-f848-48f8-6f55-0f0724070000
      org_key:
        type: string
        description: The organization the objects being updated belong to.
        x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      actor_key:
        type: string
        description: The user who made the change.
        x-example: 1c7b1c5e-1a23-4d04-5cb4-eccea4d5994c
      absolute_match_only:
        type: boolean
        description: |
          If set this will return ChangeEntry values with a path that matches
          the attribute_path property exactly.
      attribute_path:
        type: string
        description: |
          A dot-separated / bracket-indexed path to the field changed on the
          object. '%' may be used as a wildcard.
        x-example: cluster.instance[%].metadata[app-name]
      change_type:
        type: string
        description: Whether the value was added or removed to the object.
        enum:
          - addition
          - removal
      attribute_value:
        type: string
        description: |
          The value that has been added or removed to the object at the attribute
          path indicated in path.
      exclude_empty_values:
        type: boolean
        description: |
          If set this will exclude ChangeEntry records that save the addition
          or removal of an empty value.

  ClusterFilter:
    type: object
    properties:
      cluster_key:
        type: string
      name:
        type: string
      zone_key:
        type: string

  DomainFilter:
    type: object
    properties:
      domain_key:
        type: string
      name:
        type: string
      proxy_keys:
        description: |
          matches Domains with a superset of the specified proxy_keys. A
          slice with a single value of "-" will produce Domains with no linked
          Proxies.
        type: array
        items:
          type: string
      zone_key:
        type: string

  SharedRulesFilter:
    type: object
    properties:
      shared_rules_key:
        type: string
      name:
        type: string
      zone_key:
        type: string

  RouteFilter:
    type: object
    properties:
      route_key:
        type: string
      domain_key:
        type: string
      shared_rules_key:
        type: string
      path:
        type: string
      path_prefix:
        type: string
      zone_key:
        type: string

  ProxyFilter:
    type: object
    properties:
      proxy_key:
        type: string
      name:
        type: string
      domain_keys:
        description: |
          matches Proxies with a superset of the specified domain_keys. A
          slice with a single value of "-" will produce Proxies with no linked
          Domains.
        type: array
        items:
          type: string
      zone_key:
        type: string

  ZoneFilter:
    type: object
    properties:
      zone_key:
        type: string
      name:
        type: string

  FilterProducts:
    type: object
    properties:
      and:
        description: An array of changelog filters that will be joined via logical AND.
        type: array
        items:
          $ref: "#/definitions/Filter"

  FilterSums:
    type: object
    properties:
      or:
        description: An array of changelog filters that will be joined via logical OR.
        type: array
        items:
          $ref: "#/definitions/FilterProducts"

  User:
    type: object
    required:
      - user_key
      - login_email
      - checksum
    properties:
      user_key:
        type: string
      login_email:
        type: string
      deleted_at:
        type: string
        description: |
          A timestamp that marks when a user was deleted. It is in the format
          yyyy-mm-ddThh:mm:ss.SZ. The timezone will always be UTC.
        x-example: 2017-08-14T17:29:11.986438Z
      checksum:
        type: string

  MultiAccessTokens:
    type: object
    properties:
      result:
        type: array
        items:
          $ref: "#/definitions/AccessToken"
  AccessToken:
    type: object
    required:
      - access_token_key
      - description
      - user_key
      - created_at
      - checksum
    properties:
      access_token_key:
        type: string
      description:
        type: string
      user_key:
        type: string
      created_at:
        type: string
        description: |
          A timestamp that marks when a user was deleted. It is in the format
          yyyy-mm-ddThh:mm:ss.SZ. The timezone will always be UTC.
      checksum:
        type: string
      signed_token:
        type: string
        description: |
          This will be set only when an AccessToken is initially created

  AccessTokenDescription:
    type: object
    required:
      - description
    properties:
      description:
        type: string