PowerDNS-Admin/powerdnsadmin/swagger-spec.yaml

2293 lines
66 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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 servers configuration'
zones_url:
type: string
description: 'The API endpoint for this servers 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"'