2293 lines
66 KiB
YAML
2293 lines
66 KiB
YAML
swagger: '2.0'
|
||
info:
|
||
version: "0.0.14"
|
||
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'
|
||
|
||
'/servers/{server_id}/health':
|
||
get:
|
||
security:
|
||
- APIKeyHeader: []
|
||
summary: Perfoms health check
|
||
operationId: health_check
|
||
tags:
|
||
- Monitoring
|
||
parameters:
|
||
- name: server_id
|
||
in: path
|
||
required: true
|
||
description: The id of the server to retrieve
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: Healthcheck succeeded
|
||
schema:
|
||
type: string
|
||
example: "up"
|
||
'503':
|
||
description: Healthcheck failed
|
||
schema:
|
||
type: string
|
||
example: Down/Unknown
|
||
|
||
'/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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
|
||
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'
|
||
'400':
|
||
description: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'409':
|
||
description: 'Domain already exists (conflict)'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'500':
|
||
description: 'Internal Server Error'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
|
||
'/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.'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'403':
|
||
description: 'Forbidden'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: 'Not found'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'500':
|
||
description: 'Internal Server Error'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
|
||
'/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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'403':
|
||
description: 'Domain Access Forbidden'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'500':
|
||
description: 'Internal Server Error. There was a problem creating the key'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
post:
|
||
security:
|
||
- basicAuth: []
|
||
summary: 'Add a ApiKey key'
|
||
description: 'This methods add a new ApiKey. The actual key is generated by the server'
|
||
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'
|
||
'400':
|
||
description: 'Request is not JSON or does not respect required format'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'403':
|
||
description: 'Domain Access Forbidden'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: 'Domain or Account Not found'
|
||
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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'403':
|
||
description: 'The authenticated user has User role and is not allowed on any of the domains assigned to the key'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: 'Not found. The ApiKey with the specified apikey_id does not exist'
|
||
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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'403':
|
||
description: 'The authenticated user has User role and is not allowed on any of the domains assigned to the key'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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, accounts and 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
|
||
* Accounts can be updated only by a privileged user
|
||
* With a User role, an ApiKey needs at least one account or one domain
|
||
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'
|
||
'400':
|
||
description: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'403':
|
||
description: 'Domain Access Forbidden'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: 'Not found (ApiKey, Domain or Account)'
|
||
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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'409':
|
||
description: Duplicate Entry, either the Name or the Email is already in use
|
||
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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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)
|
||
'400':
|
||
description: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: Not found. The User with the specified user_id does not exist
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'409':
|
||
description: Duplicate (Email already assigned to another user)
|
||
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)
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
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: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'409':
|
||
description: Duplicate Entry, the Name is already in use
|
||
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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: Not found. The Account with the specified name does not exist
|
||
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)
|
||
'400':
|
||
description: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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)
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: Not found. The Account with the specified account_id does not exist
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
|
||
'/pdnsadmin/accounts/users/{account_id}':
|
||
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_users_account
|
||
tags:
|
||
- account
|
||
- user
|
||
responses:
|
||
'200':
|
||
description: List of Summarized User objects
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/definitions/User'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'404':
|
||
description: Not found. The Account with the specified account_id does not exist
|
||
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)
|
||
'400':
|
||
description: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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)
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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'
|
||
|
||
'/pdnsadmin/accounts/users/{account_id}/{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_user_account
|
||
tags:
|
||
- account
|
||
- user
|
||
responses:
|
||
'204':
|
||
description: OK. User is linked (empty response body)
|
||
'400':
|
||
description: 'Request is not JSON'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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_user_account
|
||
tags:
|
||
- account
|
||
- user
|
||
responses:
|
||
'204':
|
||
description: OK. User is unlinked (empty response body)
|
||
'401':
|
||
description: 'Unauthorized'
|
||
schema:
|
||
$ref: '#/definitions/Error'
|
||
'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 list of domains'
|
||
type: array
|
||
x-omitempty: false
|
||
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: 'An 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'
|
||
accounts:
|
||
type: array
|
||
description: 'A list of accounts bound to this ApiKey'
|
||
items:
|
||
$ref: '#/definitions/AccountSummary'
|
||
|
||
ApiKeySummary:
|
||
title: ApiKeySummary
|
||
description: Summary of an ApiKey
|
||
properties:
|
||
id:
|
||
type: integer
|
||
description: 'The ID for this key, used in the ApiKey URL endpoint.'
|
||
readOnly: true
|
||
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
|
||
apikeys:
|
||
type: array
|
||
description: A list of API Keys bound to this account
|
||
readOnly: true
|
||
items:
|
||
$ref: '#/definitions/ApiKeySummary'
|
||
|
||
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
|
||
domains:
|
||
description: The list of domains owned by this account
|
||
$ref: '#/definitions/PDNSAdminZones'
|
||
|
||
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"'
|