powerdns-admin/swagger-specv2.yaml

swagger: '2.0'
info:
  version: "0.0.13"
  title: PowerDNS Admin Authoritative HTTP API
  license:
    name: MIT
host: localhost:80
basePath: /api/v1
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  # X-API-Key: abcdef12345
  APIKeyHeader:
    type: apiKey
    in: header
    name: X-API-Key
  basicAuth:
    type: basic

# Overall TODOS:
# TODO: Return types are not consistent across documentation
#       We need to look at the code and figure out the default HTTP response
#       codes and adjust docs accordingly.
paths:
  '/servers':
    get:
      security:
        - APIKeyHeader: []
      summary: List all servers
      operationId: listServers
      tags:
        - servers
      responses:
        '200':
          description: An array of servers
          schema:
            type: array
            items:
              $ref: '#/definitions/Server'

  '/sync_domains':
    get:
      security:
        - APIKeyHeader: []
      summary: Sync PDNS with PDNSAdmin
      operationId: synchronizeDomains
      tags:
        - pdnsadmin_zones
      responses:
        '200':
          description: Synchronize PDNS Domains with PDNSAdmin
        '403':
          description: Wrong authentication

  '/servers/{server_id}':
    get:
      security:
        - APIKeyHeader: []
      summary: List a server
      operationId: listServer
      tags:
        - servers
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
      responses:
        '200':
          description: A server
          schema:
            $ref: '#/definitions/Server'

  '/servers/{server_id}/cache/flush':
    put:
      security:
        - APIKeyHeader: []
      summary: Flush a cache-entry by name
      operationId: cacheFlushByName
      tags:
        - servers
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: domain
          in: query
          required: true
          description: The domain name to flush from the cache
          type: string
      responses:
        '200':
          description: Flush successful
          schema:
            $ref: '#/definitions/CacheFlushResult'

  '/servers/{server_id}/zones':
    get:
      security:
        - APIKeyHeader: []
      summary: List all Zones in a server
      operationId: listZones
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone
          in: query
          required: false
          type: string
          description: |
            When set to the name of a zone, only this zone is returned.
            If no zone with that name exists, the response is an empty array.
            This can e.g. be used to check if a zone exists in the database without having to guess/encode the zone's id or to check if a zone exists.            
      responses:
        '200':
          description: An array of Zones
          schema:
            type: array
            items:
              $ref: '#/definitions/Zone'
    post:
      security:
        - APIKeyHeader: []
      summary: Creates a new domain, returns the Zone on creation.
      operationId: createZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: rrsets
          in: query
          description: '“true” (default) or “false”, whether to include the “rrsets” in the response Zone object.'
          type: boolean
          default: true
        - name: zone_struct
          description: The zone struct to patch with
          required: true
          in: body
          schema:
            $ref: '#/definitions/Zone'
      responses:
        '201':
          description: A zone
          schema:
              $ref: '#/definitions/Zone'

  '/servers/{server_id}/zones/{zone_id}':
    get:
      security:
        - APIKeyHeader: []
      summary: zone managed by a server
      operationId: listZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: A Zone
          schema:
            $ref: '#/definitions/Zone'
    delete:
      security:
        - APIKeyHeader: []
      summary: Deletes this zone, all attached metadata and rrsets.
      operationId: deleteZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '204':
          description: 'Returns 204 No Content on success.'
    patch:
      security:
        - APIKeyHeader: []
      summary: 'Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success.'
      operationId: patchZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
        - name: zone_struct
          description: The zone struct to patch with
          required: true
          in: body
          schema:
            $ref: '#/definitions/Zone'
      responses:
        '204':
          description: 'Returns 204 No Content on success.'

    put:
      security:
        - APIKeyHeader: []
      summary: Modifies basic zone data (metadata).
      description: 'Allowed fields in client body: all except id, url and name. Returns 204 No Content on success.'
      operationId: putZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
        - name: zone_struct
          description: The zone struct to patch with
          required: true
          in: body
          schema:
            $ref: '#/definitions/Zone'
      responses:
        '204':
          description: 'Returns 204 No Content on success.'

  '/servers/{server_id}/zones/{zone_id}/notify':
    put:
      security:
        - APIKeyHeader: []
      summary: Send a DNS NOTIFY to all slaves.
      description: 'Fails when zone kind is not Master or Slave, or master and slave are disabled in the configuration. Only works for Slave if renotify is on. Clients MUST NOT send a body.'
      operationId: notifyZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: OK

  '/servers/{server_id}/zones/{zone_id}/axfr-retrieve':
    put:
      security:
        - APIKeyHeader: []
      summary: Retrieve slave zone from its master.
      description: 'Fails when zone kind is not Slave, or slave is disabled in the configuration. Clients MUST NOT send a body.'
      operationId: axfrRetrieveZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: OK

  '/servers/{server_id}/zones/{zone_id}/export':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Returns the zone in AXFR format.'
      operationId: axfrExportZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: OK
          schema:
            type: string

  '/servers/{server_id}/zones/{zone_id}/check':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Verify zone contents/configuration.'
      operationId: checkZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: OK
          schema:
            type: string

  '/servers/{server_id}/zones/{zone_id}/rectify':
    put:
      security:
        - APIKeyHeader: []
      summary: 'Rectify the zone data.'
      description: 'This does not take into account the API-RECTIFY metadata. Fails on slave zones and zones that do not have DNSSEC.'
      operationId: rectifyZone
      tags:
        - zones
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: OK
          schema:
            type: string

  '/servers/{server_id}/config':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Returns all ConfigSettings for a single server'
      operationId: getConfig
      tags:
        - config
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
      responses:
        '200':
          description: List of config values
          schema:
            type: array
            items:
              $ref: '#/definitions/ConfigSetting'

  '/servers/{server_id}/config/{config_setting_name}':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Returns a specific ConfigSetting for a single server'
      description: 'NOT IMPLEMENTED'
      operationId: getConfigSetting
      tags:
        - config
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: config_setting_name
          in: path
          required: true
          description: The name of the setting to retrieve
          type: string
      responses:
        '200':
          description: List of config values
          schema:
            $ref: '#/definitions/ConfigSetting'

  '/servers/{server_id}/statistics':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Query statistics.'
      description: 'Query PowerDNS internal statistics. Returns a list of BaseStatisticItem derived elements.'
      operationId: getStats
      tags:
        - stats
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
      responses:
        '200':
          description: List of Statistic Items
          schema:
            type: array
            items:
            # these can be commented because the swagger code generator fails on them
            # and replaced with
            # type: string
            # or something like that
              $ref: '#/definitions/MapStatisticItem'
            # - $ref: '#/definitions/StatisticItem'
            # - $ref: '#/definitions/RingStatisticItem'

  '/servers/{server_id}/search-data':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Search the data inside PowerDNS'
      description: 'Search the data inside PowerDNS for search_term and return at most max_results. This includes zones, records and comments. The * character can be used in search_term as a wildcard character and the ? character can be used as a wildcard for a single character.'
      operationId: searchData
      tags:
        - search
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: q
          in: query
          required: true
          description: 'The string to search for'
          type: string
        - name: max
          in: query
          required: true
          description: 'Maximum number of entries to return'
          type: integer
      responses:
        '200':
          description: Returns a JSON array with results
          schema:
            $ref: '#/definitions/SearchResults'

  '/servers/{server_id}/zones/{zone_id}/metadata':
    get:
      security:
        - APIKeyHeader: []
      summary: Get all the MetaData associated with the zone.
      operationId: listMetadata
      tags:
        - zonemetadata
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: List of Metadata objects
          schema:
            type: array
            items:
              $ref: '#/definitions/Metadata'
    post:
      security:
        - APIKeyHeader: []
      summary: 'Creates a set of metadata entries'
      description: 'Creates a set of metadata entries of given kind for the zone. Existing metadata entries for the zone with the same kind are not overwritten.'
      operationId: createMetadata
      tags:
        - zonemetadata
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
        - name: metadata
          description: List of metadata to add/create
          required: true
          in: body
          schema:
            type: array
            items:
              $ref: '#/definitions/Metadata'
      responses:
        '204':
          description: OK

  '/servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}':
    get:
      security:
        - APIKeyHeader: []
      summary: Get the content of a single kind of domain metadata as a list of MetaData objects.
      operationId: getMetadata
      tags:
        - zonemetadata
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
        - name: metadata_kind
          type: string
          in: path
          required: true
          description: '???'
      responses:
        '200':
          description: List of Metadata objects
          schema:
            $ref: '#/definitions/Metadata'
    put:
      security:
        - APIKeyHeader: []
      summary: 'Modify the content of a single kind of domain metadata.'
      operationId: modifyMetadata
      tags:
        - zonemetadata
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
        - name: metadata_kind
          description: The kind of metadata
          required: true
          type: string
          in: path
        - name: metadata
          description: metadata to add/create
          required: true
          in: body
          schema:
            $ref: '#/definitions/Metadata'
      responses:
        '204':
          description: OK
    delete:
      security:
        - APIKeyHeader: []
      summary: 'Delete all items of a single kind of domain metadata.'
      operationId: deleteMetadata
      tags:
        - zonemetadata
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
        - name: metadata_kind
          type: string
          in: path
          required: true
          description: '???'
      responses:
        '204':
          description: OK

  '/servers/{server_id}/zones/{zone_id}/cryptokeys':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Get all CryptoKeys for a zone, except the privatekey'
      operationId: listCryptokeys
      tags:
        - zonecryptokey
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '200':
          description: List of Cryptokey objects
          schema:
            type: array
            items:
              $ref: '#/definitions/Cryptokey'
    post:
      security:
        - APIKeyHeader: []
      summary: 'Creates a Cryptokey'
      description: 'This method adds a new key to a zone. The key can either be generated or imported by supplying the content parameter. if content, bits and algo are null, a key will be generated based on the default-ksk-algorithm and default-ksk-size settings for a KSK and the default-zsk-algorithm and default-zsk-size options for a ZSK.'
      operationId: createCryptokey
      tags:
        - zonecryptokey
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
        - name: cryptokey
          description: Add a Cryptokey
          required: true
          in: body
          schema:
            $ref: '#/definitions/Cryptokey'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Cryptokey'

  '/servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}':
    get:
      security:
        - APIKeyHeader: []
      summary: 'Returns all data about the CryptoKey, including the privatekey.'
      operationId: getCryptokey
      tags:
        - zonecryptokey
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
        - name: cryptokey_id
          type: string
          in: path
          required: true
          description: 'The id value of the CryptoKey'
      responses:
        '200':
          description: Cryptokey
          schema:
            $ref: '#/definitions/Cryptokey'
    put:
      security:
        - APIKeyHeader: []
      summary: 'This method (de)activates a key from zone_name specified by cryptokey_id'
      operationId: modifyCryptokey
      tags:
        - zonecryptokey
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
        - name: cryptokey_id
          description: Cryptokey to manipulate
          required: true
          in: path
          type: string
        - name: cryptokey
          description: the Cryptokey
          required: true
          in: body
          schema:
            $ref: '#/definitions/Cryptokey'
      responses:
        '204':
          description: OK
        '422':
          description: 'Returned when something is wrong with the content of the request. Contains an error message'
    delete:
      security:
        - APIKeyHeader: []
      summary: 'This method deletes a key specified by cryptokey_id.'
      operationId: deleteCryptokey
      tags:
        - zonecryptokey
      parameters:
        - name: server_id
          in: path
          required: true
          description: The id of the server to retrieve
          type: string
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
        - name: cryptokey_id
          type: string
          in: path
          required: true
          description: 'The id value of the Cryptokey'
      responses:
        '204':
          description: OK
        '422':
          description: 'Returned when something is wrong with the content of the request. Contains an error message'

  '/pdnsadmin/zones':
    get:
      security:
        - basicAuth: []
      summary: List all Zones in a server
      operationId: api_login_list_zones
      tags:
        - pdnsadmin_zones
      responses:
        '200':
          description: An array of Zones
          schema:
            type: array
            items:
              $ref: '#/definitions/PDNSAdminZones'
    post:
      security:
        - basicAuth: []
      summary: Creates a new domain, returns the Zone on creation.
      operationId: api_login_create_zone
      tags:
        - pdnsadmin_zones
      parameters:
        - name: zone_struct
          description: The zone struct to patch with
          required: true
          in: body
          schema:
            $ref: '#/definitions/Zone'
      responses:
        '201':
          description: A zone
          schema:
              $ref: '#/definitions/Zone'
  '/pdnsadmin/zones/{zone_id}':
    parameters:
      - name: zone_id
        type: string
        in: path
        required: true
        description: The id of the zone to retrieve (without dot)
    delete:
      security:
        - basicAuth: []
      summary: Deletes this zone, all attached metadata and rrsets.
      operationId: api_login_delete_zone
      tags:
        - pdnsadmin_zones
      parameters:
        - name: zone_id
          type: string
          in: path
          required: true
          description: The id of the zone to retrieve
      responses:
        '204':
          description: 'Returns 204 No Content on success.'
  '/pdnsadmin/apikeys':
    get:
      security:
        - basicAuth: []
      summary: 'Get all ApiKey on the server, except the actual key'
      operationId: api_get_apikeys
      tags:
        - apikey
      responses:
        '200':
          description: List of ApiKey objects
          schema:
            type: array
            items:
              $ref: '#/definitions/ApiKey'
        '500':
          description: 'Internal Server Error, keys could not be retrieved. Contains error message'
          schema:
            $ref: '#/definitions/Error'
    post:
      security:
        - basicAuth: []
      summary: 'Add a ApiKey key'
      description: 'This methods add a new ApiKey. The actual key can be generated by the server or be provided by the client'
      operationId: api_generate_apikey
      tags:
        - apikey
      parameters:
        - name: apikey
          description: The ApiKey to add
          required: true
          in: body
          schema:
            $ref: '#/definitions/ApiKey'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ApiKey'
        '422':
          description: 'Unprocessable Entry, the ApiKey provided has issues.'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Internal Server Error. There was a problem creating the key'
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/apikeys/{apikey_id}':
    parameters:
      - name: apikey_id
        type: integer
        in: path
        required: true
        description: The id of the apikey to retrieve
    get:
      security:
        - basicAuth: []
      summary: 'Get a specific apikey on the server, hashed'
      operationId: api_get_apikey_by_id
      tags:
        - apikey
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/ApiKey'
        '403':
          description: 'The authenticated user has User role and is not allowed on any of the domains assigned to the key'
        '404':
          description: 'Not found. The ApiKey with the specified apikey_id does not exist'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Internal Server Error, keys could not be retrieved. Contains error message'
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - basicAuth: []
      summary: 'Delete the ApiKey with apikey_id'
      operationId: api_delete_apikey
      tags:
        - apikey
      responses:
        '204':
          description: 'OK, key was deleted'
        '404':
          description: 'Not found. The ApiKey with the specified apikey_id does not exist'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Internal Server Error. Contains error message'
          schema:
            $ref: '#/definitions/Error'
    put:
      security:
        - basicAuth: []
      description: |
        The ApiKey at apikey_id can be changed in multiple ways:
         * Role, description, domains can be updated
         * Role can be changed to Administrator only if user has Operator or Administrator privileges
         * Domains will be updated only if user has access to them
        Only the relevant fields have to be provided in the request body.        
      operationId: api_update_apikey
      tags:
        - apikey
      parameters:
        - name: apikey
          description: ApiKey object with the new values
          schema:
            $ref: '#/definitions/ApiKey'
          in: body
          required: true
      responses:
        '204':
          description: OK. ApiKey is changed.
          schema:
            $ref: '#/definitions/ApiKey'
        '404':
          description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Internal Server Error. Contains error message'
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/users':
    get:
      security:
        - basicAuth: []
      summary: 'Get all User entries'
      operationId: api_list_users
      tags:
        - user
      responses:
        '200':
          description: List of User objects
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        '500':
          description: Internal Server Error, users could not be retrieved. Contains error message
          schema:
            $ref: '#/definitions/Error'
    post:
      security:
        - basicAuth: []
      summary: Add a User
      description: This methods adds a new User
      operationId: api_create_user
      tags:
        - user
      parameters:
        - in: body
          name: user
          description: The user to create
          schema:
            type: object
            required:
              - username
              - email
            properties:
              username:
                type: string
                description: Login name for user (unique, immutable)
              password:
                type: string
                description: Hashed password for authentication
              plain_text_password:
                type: string
                description: Plain text password (will be hashed) for authentication
              firstname:
                type: string
                description: Firstname of user
              lastname:
                type: string
                description: Lastname of user
              email:
                type: string
                description: Email address if user (must be unique)
              otp_secret:
                type: string
                description: OTP secret
              confirmed:
                type: string
                description: Confirmed status
              role_name:
                type: string
                description: Name of role to be assigned to user (default 'User')
              role_id:
                type: integer
                description: Role ID of role to be assigned to user
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/User'
        '400':
          description: Unprocessable Entry, the User data provided has issues
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. There was a problem creating the user
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/users/{username}':
    parameters:
      - name: username
        type: string
        in: path
        required: true
        description: The username of the user to retrieve
    get:
      security:
        - basicAuth: []
      summary: Get a specific User on the server
      operationId: api_get_user
      tags:
        - user
      responses:
        '200':
          description: Retrieve a specific User
          schema:
            $ref: '#/definitions/UserDetailed'
        '404':
          description: Not found. The User with the specified username does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error, user could not be retrieved. Contains error message
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/users/{user_id}':
    parameters:
      - name: user_id
        type: integer
        in: path
        required: true
        description: The id of the user to modify or delete
    put:
      security:
        - basicAuth: []
      summary: Modify a specific User on the server with supplied parameters
      operationId: api_update_user
      tags:
        - user
      parameters:
        - in: body
          name: user
          schema:
            type: object
            properties:
              username:
                type: string
                description: Login name for user (unique, immutable)
              password:
                type: string
                description: Hashed password for authentication
              plain_text_password:
                type: string
                description: Plain text password (will be hashed) for authentication
              firstname:
                type: string
                description: Firstname of user
              lastname:
                type: string
                description: Lastname of user
              email:
                type: string
                description: Email address if user (must be unique)
              otp_secret:
                type: string
                description: OTP secret
              confirmed:
                type: string
                description: Confirmed status
              role_name:
                type: string
                description: Name of role to be assigned to user (default 'User')
              role_id:
                type: string
                description: Role id of role to be assigned to user
      responses:
        '204':
          description: OK. User is modified (empty response body)
        '404':
          description: Not found. The User with the specified user_id does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. Contains error message
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - basicAuth: []
      summary: Delete a specific User
      operationId: api_delete_user
      tags:
        - user
      responses:
        '204':
          description: OK. User is deleted (empty response body)
        '404':
          description: Not found. The User with the specified user_id does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. Contains error message
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/accounts':
    get:
      security:
        - basicAuth: []
      summary: Get all Account entries
      operationId: api_list_accounts
      tags:
        - account
      responses:
        '200':
          description: List of Account objects
          schema:
            type: array
            items:
              $ref: '#/definitions/Account'
        '500':
          description: Internal Server Error, accounts could not be retrieved. Contains error message
          schema:
            $ref: '#/definitions/Error'
    post:
      security:
        - basicAuth: []
      summary: Add an Account
      description: This methods adds a new Account
      operationId: api_create_account
      tags:
        - account
      parameters:
        - in: body
          name: account
          schema:
            required:
              - name
            properties:
              name:
                type: string
                description: Name for account (unique, immutable)
              description:
                type: string
                description: Description of account
              contact:
                type: string
                description: Contact information
              mail:
                type: string
                description: Email address for contact
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Account'
        '400':
          description: Unprocessable Entry, the Account data provided has issues.
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. There was a problem creating the account
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/accounts/{account_name}':
    parameters:
      - name: account_name
        type: string
        in: path
        required: true
        description: The name of the account to retrieve
    get:
      security:
        - basicAuth: []
      summary: Get a specific Account on the server
      operationId: api_get_account_by_name
      tags:
        - user
      responses:
        '200':
          description: Retrieve a specific account
          schema:
            $ref: '#/definitions/Account'
        '404':
          description: Not found. The Account with the specified name does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error, account could not be retrieved. Contains error message
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/accounts/{account_id}':
    parameters:
      - name: account_id
        type: integer
        in: path
        required: true
        description: The id of the account to modify or delete
    put:
      security:
        - basicAuth: []
      summary: Modify a specific Account on the server with supplied parameters
      operationId: api_update_account
      tags:
        - user
      parameters:
        - in: body
          name: account
          schema:
            required:
              - name
            properties:
              name:
                type: string
                description: Name for account (unique, immutable)
              description:
                type: string
                description: Description of account
              contact:
                type: string
                description: Contact information
              mail:
                type: string
                description: Email address for contact
      responses:
        '204':
          description: OK. Account is modified (empty response body)
        '404':
          description: Not found. The Account with the specified account_id does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. Contains error message
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - basicAuth: []
      summary: Delete a specific Account
      operationId: api_delete_account
      tags:
        - user
      responses:
        '204':
          description: OK. Account is deleted (empty response body)
        '404':
          description: Not found. The Account with the specified account_id does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. Contains error message
          schema:
            $ref: '#/definitions/Error'

  '/pdnsadmin/accounts/{account_id}/users':
    parameters:
      - name: account_id
        type: integer
        in: path
        required: true
        description: The id of the account to list users linked to account
    get:
      security:
        - basicAuth: []
      summary: List users linked to a specific account
      operationId: api_list_account_users
      tags:
        - account
        - user
      responses:
        '200':
          description: List of Summarized User objects
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        '404':
          description: Not found. The Account with the specified account_id does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error, accounts could not be retrieved. Contains error message
          schema:
            $ref: '#/definitions/Error'
  '/pdnsadmin/accounts/{account_id}/users/{user_id}':
    parameters:
      - name: account_id
        type: integer
        in: path
        required: true
        description: The id of the account to link/unlink users to account
      - name: user_id
        type: integer
        in: path
        required: true
        description: The id of the user to (un)link to/from account
    put:
      security:
        - basicAuth: []
      summary: Link user to account
      operationId: api_add_account_user
      tags:
        - account
        - user
      responses:
        '204':
          description: OK. User is linked (empty response body)
        '404':
          description: Not found. The Account or User with the specified id does not exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. Contains error message
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - basicAuth: []
      summary: Unlink user from account
      operationId: api_remove_account_user
      tags:
        - account
        - user
      responses:
        '204':
          description: OK. User is unlinked (empty response body)
        '404':
          description: Not found. The Account or User with the specified id does not exist or user was not linked to account
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error. Contains error message
          schema:
            $ref: '#/definitions/Error'

definitions:
  Server:
    title: Server
    properties:
      type:
        type: string
        description: 'Set to “Server”'
      id:
        type: string
        description: 'The id of the server, “localhost”'
      daemon_type:
        type: string
        description: '“recursor” for the PowerDNS Recursor and “authoritative” for the Authoritative Server'
      version:
        type: string
        description: 'The version of the server software'
      url:
        type: string
        description: 'The API endpoint for this server'
      config_url:
        type: string
        description: 'The API endpoint for this server’s configuration'
      zones_url:
        type: string
        description: 'The API endpoint for this server’s zones'

  Servers:
    type: array
    items:
      $ref: '#/definitions/Server'

  Zone:
    title: Zone
    description: This represents an authoritative DNS Zone.
    properties:
      id:
        type: string
        description: 'Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs.'
      name:
        type: string
        description: 'Name of the zone (e.g. “example.com.”) MUST have a trailing dot'
      type:
        type: string
        description: 'Set to “Zone”'
      url:
        type: string
        description: 'API endpoint for this zone'
      kind:
        type: string
        enum:
          - 'Native'
          - 'Master'
          - 'Slave'
        description: 'Zone kind, one of “Native”, “Master”, “Slave”'
      rrsets:
        type: array
        items:
          $ref: '#/definitions/RRSet'
        description: 'RRSets in this zone'
      serial:
        type: integer
        description: 'The SOA serial number'
      notified_serial:
        type: integer
        description: 'The SOA serial notifications have been sent out for'
      masters:
        type: array
        items:
          type: string
        description: ' List of IP addresses configured as a master for this zone (“Slave” type zones only)'
      dnssec:
        type: boolean
        description: 'Whether or not this zone is DNSSEC signed (inferred from presigned being true XOR presence of at least one cryptokey with active being true)'
      nsec3param:
        type: string
        description: 'The NSEC3PARAM record'
      nsec3narrow:
        type: boolean
        description: 'Whether or not the zone uses NSEC3 narrow'
      presigned:
        type: boolean
        description: 'Whether or not the zone is pre-signed'
      soa_edit:
        type: string
        description: 'The SOA-EDIT metadata item'
      soa_edit_api:
        type: string
        description: 'The SOA-EDIT-API metadata item'
      api_rectify:
        type: boolean
        description: ' Whether or not the zone will be rectified on data changes via the API'
      zone:
        type: string
        description: 'MAY contain a BIND-style zone file when creating a zone'
      account:
        type: string
        description: 'MAY be set. Its value is defined by local policy'
      nameservers:
        type: array
        items:
          type: string
        description: 'MAY be sent in client bodies during creation, and MUST NOT be sent by the server. Simple list of strings of nameserver names, including the trailing dot. Not required for slave zones.'
      tsig_master_key_ids:
        type: array
        items:
          type: string
        description: 'The id of the TSIG keys used for master operation in this zone'
        externalDocs:
          url: 'https://doc.powerdns.com/authoritative/tsig.html#provisioning-outbound-axfr-access'
      tsig_slave_key_ids:
        type: array
        items:
          type: string
        description: 'The id of the TSIG keys used for slave operation in this zone'
        externalDocs:
          url: 'https://doc.powerdns.com/authoritative/tsig.html#provisioning-signed-notification-and-axfr-requests'

  Zones:
    type: array
    items:
      $ref: '#/definitions/Zone'

  RRSet:
    title: RRSet
    description: This represents a Resource Record Set (all records with the same name and type).
    required:
      - name
      - type
      - ttl
      - changetype
      - records
    properties:
      name:
        type: string
        description: 'Name for record set (e.g. “www.powerdns.com.”)'
      type:
        type: string
        description: 'Type of this record (e.g. “A”, “PTR”, “MX”)'
      ttl:
        type: integer
        description: 'DNS TTL of the records, in seconds. MUST NOT be included when changetype is set to “DELETE”.'
      changetype:
        type: string
        description: 'MUST be added when updating the RRSet. Must be REPLACE or DELETE. With DELETE, all existing RRs matching name and type will be deleted, including all comments. With REPLACE: when records is present, all existing RRs matching name and type will be deleted, and then new records given in records will be created. If no records are left, any existing comments will be deleted as well. When comments is present, all existing comments for the RRs matching name and type will be deleted, and then new comments given in comments will be created.'
      records:
        type: array
        description: 'All records in this RRSet. When updating Records, this is the list of new records (replacing the old ones). Must be empty when changetype is set to DELETE. An empty list results in deletion of all records (and comments).'
        items:
          $ref: '#/definitions/Record'
      comments:
        type: array
        description: 'List of Comment. Must be empty when changetype is set to DELETE. An empty list results in deletion of all comments. modified_at is optional and defaults to the current server time.'
        items:
          $ref: '#/definitions/Comment'

  Record:
    title: Record
    description: The RREntry object represents a single record.
    required:
      - content
      - disabled # PatchZone endpoint complains if this is missing
    properties:
      content:
        type: string
        description: 'The content of this record'
      disabled:
        type: boolean
        description: 'Whether or not this record is disabled'
      set-ptr:
        type: boolean
        description: 'If set to true, the server will find the matching reverse zone and create a PTR there. Existing PTR records are replaced. If no matching reverse Zone, an error is thrown. Only valid in client bodies, only valid for A and AAAA types. Not returned by the server.'

  Comment:
    title: Comment
    description: A comment about an RRSet.
    properties:
      content:
        type: string
        description: 'The actual comment'
      account:
        type: string
        description: 'Name of an account that added the comment'
      modified_at:
        type: integer
        description: 'Timestamp of the last change to the comment'

  TSIGKey:
    title: TSIGKey
    description: A TSIG key that can be used to authenticate NOTIFYs and AXFRs
    properties:
      name:
        type: string
        description: 'The name of the key'
      id:
        type: string
        description: 'The ID for this key, used in the TSIGkey URL endpoint.'
        readOnly: true
      algorithm:
        type: string
        description: 'The algorithm of the TSIG key'
      key:
        type: string
        description: 'The Base64 encoded secret key, empty when listing keys. MAY be empty when POSTing to have the server generate the key material'
      type:
        type: string
        description: 'Set to "TSIGKey"'
        readOnly: true

  PDNSAdminZones:
    title: PDNSAdminZones
    description: A ApiKey that can be used to manage domains through API
    type: array
    items:
      properties:
        id:
          type: integer
          description: 'The ID for this PDNSAdmin zone'
          readOnly: true
        name:
          type: string
          description: 'Name of the zone'

  PDNSAdminRole:
    title: PDNSAdminRole
    description: Roles of PowerDNS Admin
    properties:
      id:
        type: integer
        description: 'The ID for this PDNSAdmin role'
        readOnly: true
      name:
        type: string
        description: 'The Name of PDNSAdmin role'

  ApiKey:
    title: ApiKey
    description: A ApiKey that can be used to manage domains through API
    properties:
      id:
        type: integer
        description: 'The ID for this key, used in the ApiKey URL endpoint.'
        readOnly: true
      plain_key:
        type: string
        description: 'ApiKey key is return in plain text only at first POST'
      key:
        type: string
        description: 'not used on POST, POSTing to server generates the key material'
      domains:
        $ref: '#/definitions/PDNSAdminZones'
        description: 'domains to which this apikey has access'
      role:
        $ref: '#/definitions/PDNSAdminRole'
      description:
        type: string
        description: 'Some user defined description'

  User:
    title: User
    description: User that can access the gui/api
    properties:
      id:
        type: integer
        description: The ID for this user (unique)
        readOnly: true
      username:
        type: string
        description: The username for this user (unique, immutable)
        readOnly: false
      password:
        type: string
        description: The hashed password for this user
        readOnly: false
      firstname:
        type: string
        description: The firstname of this user
        readOnly: false
      lastname:
        type: string
        description: The lastname of this user
        readOnly: false
      email:
        type: string
        description: Email addres for this user
        readOnly: false
      otp_secret:
        type: string
        description: OTP secret
        readOnly: false
      confirmed:
        type: boolean
        description: The confirmed status
        readOnly: false
      role:
        $ref: '#/definitions/PDNSAdminRole'

  UserDetailed:
    title: User
    description: User that can access the gui/api
    properties:
      id:
        type: integer
        description: The ID for this user (unique)
        readOnly: true
      username:
        type: string
        description: The username for this user (unique, immutable)
        readOnly: false
      password:
        type: string
        description: The hashed password for this user
        readOnly: false
      firstname:
        type: string
        description: The firstname of this user
        readOnly: false
      lastname:
        type: string
        description: The lastname of this user
        readOnly: false
      email:
        type: string
        description: Email addres for this user
        readOnly: false
      otp_secret:
        type: string
        description: OTP secret
        readOnly: false
      confirmed:
        type: boolean
        description: The confirmed status
        readOnly: false
      role:
        $ref: '#/definitions/PDNSAdminRole'
      accounts:
        type: array
        items:
          $ref: '#/definitions/AccountSummary'

  Account:
    title: Account
    description: Account that 'owns' zones
    properties:
      id:
        type: integer
        description: The ID for this account (unique)
        readOnly: true
      name:
        type: string
        description: The name for this account (unique, immutable)
        readOnly: false
      description:
        type: string
        description: The description for this account
        readOnly: false
      contact:
        type: string
        description: The contact details for this account
        readOnly: false
      mail:
        type: string
        description: The email address of the contact for this account
        readOnly: false

  AccountSummary:
    title: AccountSummry
    description: Summary of an Account that 'owns' zones
    properties:
      id:
        type: integer
        description: The ID for this account (unique)
        readOnly: true
      name:
        type: string
        description: The name for this account (unique, immutable)
        readOnly: false

  ConfigSetting:
    title: ConfigSetting
    properties:
      name:
        type: string
        description: 'set to "ConfigSetting"'
      type:
        type: string
        description: 'The name of this setting (e.g. ‘webserver-port’)'
      value:
        type: string
        description: 'The value of setting name'

  BaseStatisticItem:
    title: BaseStatisticItem
    properties:
      name:
        type: string
        description: 'The name of this item (e.g. ‘uptime’)'

  StatisticItem:
    title: StatisticItem
    allOf:
    - $ref: "#/definitions/BaseStatisticItem"
    - properties:
        type:
          enum: [StatisticItem]
          description: 'set to "StatisticItem"'
        value:
          type: string
          description: 'The value of item'

  MapStatisticItem:
    title: MapStatisticItem
    allOf:
    - $ref: "#/definitions/BaseStatisticItem"
    - properties:
        type:
          enum: [MapStatisticItem]
          description: 'set to "MapStatisticItem"'
        value:
          type: array
          description: 'named statistic values'
          items:
            type: object
            properties:
              name:
                type: string
                description: 'item name'
              value:
                type: string
                description: 'item value'

  RingStatisticItem:
    title: RingStatisticItem
    allOf:
    - $ref: "#/definitions/BaseStatisticItem"
    - properties:
        type:
          enum: [RingStatisticItem]
          description: 'set to "RingStatisticItem"'
        size:
          type: integer
          description: 'for RingStatisticItem objects, the size of the ring'
        value:
          type: array
          description: 'named ring statistic values'
          items:
            type: object
            properties:
              name:
                type: string
                description: 'item name'
              value:
                type: string
                description: 'item value'

  SearchResultZone:
    title: SearchResultZone
    properties:
      name:
        type: string
      object_type:
        type: string
        description: 'set to "zone"'
      zone_id:
        type: string

  SearchResultRecord:
    title: SearchResultRecord
    properties:
      content:
        type: string
      disabled:
        type: boolean
      name:
        type: string
      object_type:
        type: string
        description: 'set to "record"'
      zone_id:
        type: string
      zone:
        type: string
      type:
        type: string
      ttl:
        type: integer

  SearchResultComment:
    title: SearchResultComment
    properties:
      content:
        type: string
      name:
        type: string
      object_type:
        type: string
        description: 'set to "comment"'
      zone_id:
        type: string
      zone:
        type: string

# FIXME: This is problematic at the moment, because swagger doesn't support this type of mixed response
#  SearchResult:
#    anyOf:
#      - $ref: '#/definitions/SearchResultZone'
#      - $ref: '#/definitions/SearchResultRecord'
#      - $ref: '#/definitions/SearchResultComment'

# Since we can't do 'anyOf' at the moment, we create a 'superset object'
  SearchResult:
    title: SearchResult
    properties:
      content:
        type: string
      disabled:
        type: boolean
      name:
        type: string
      object_type:
        type: string
        description: 'set to one of "record, zone, comment"'
      zone_id:
        type: string
      zone:
        type: string
      type:
        type: string
      ttl:
        type: integer

  SearchResults:
    type: array
    items:
      $ref: '#/definitions/SearchResult'

  Metadata:
    title: Metadata
    description: Represents zone metadata
    properties:
      kind:
        type: string
        description: 'Name of the metadata'
      metadata:
        type: array
        items:
          type: string
        description: 'Array with all values for this metadata kind.'

  Cryptokey:
    title: Cryptokey
    description: 'Describes a DNSSEC cryptographic key'
    properties:
      type:
        type: string
        description: 'set to "Cryptokey"'
      id:
        type: string
        description: 'The internal identifier, read only'
      keytype:
        type: string
        enum: [ksk, zsk, csk]
      active:
        type: boolean
        description: 'Whether or not the key is in active use'
      dnskey:
        type: string
        description: 'The DNSKEY record for this key'
      ds:
        type: array
        items:
          type: string
        description: 'An array of DS records for this key'
      privatekey:
        type: string
        description: 'The private key in ISC format'
      algorithm:
        type: string
        description: 'The name of the algorithm of the key, should be a mnemonic'
      bits:
        type: integer
        description: 'The size of the key'

  Error:
    title: Error
    description: 'Returned when the server encounters an error. Either in client input or internally'
    properties:
      error:
        type: string
        description: 'A human readable error message'
      errors:
        type: array
        items:
          type: string
        description: 'Optional array of multiple errors encountered during processing'
    required:
      - error

  CacheFlushResult:
    title: CacheFlushResult
    description: 'The result of a cache-flush'
    properties:
      count:
        type: number
        description: 'Amount of entries flushed'
      result:
        type: string
        description: 'A message about the result like "Flushed cache"'