openapi: 3.1.0
-$id: "PDNS Auth webserver"
+servers:
+ - url: http://localhost/api/vi
+
info:
version: "0.0.17"
title: PowerDNS Authoritative HTTP API
+ description: PowerDNS Authoritative HTTP API
license:
name: MIT
-basePath: /api/v1
-consumes:
- - application/json
-produces:
- - application/json
-securityDefinitions:
- # X-API-Key: abcdef12345
- APIKeyHeader:
- type: apiKey
- in: header
- name: X-API-Key
+ contact:
+ name: "PowerDNS"
+ url: "https://www.powerdns.com/"
+
security:
- APIKeyHeader: []
+tags:
+ - name: zones
+ description: Zone related endpoints
+ - name: zonecryptokey
+ description: Zone DNSSEC Key related endpoints
+ - name: zonemetadata
+ description: Zone Metadata related endpoints
+ - name: tsigkey
+ description: TSIG related endpoints
+ - name: views
+ description: View related endpoints
+ - name: networks
+ description: Network related endpoints
+ - name: servers
+ description: Server related endpoints
+ - name: autoprimary
+ description: Auto-Primary related endpoints
+ - name: search
+ description: Search related endpoints
+ - name: stats
+ description: Statistics related endpoints
+ - name: config
+ description: Configuration related endpoints
+ - name: errors
+ description: Endpoints for errors
+
# 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:
- "/error":
- get:
- summary: Will always generate an error
- operationId: error
- responses: &commonErrors
- "400":
- description: The supplied request was not valid
+components:
+ schemas: &schemas
+ Server:
+ $id: Server
+ type: object
+ 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:
+ $id: Servers
+ type: array
+ items:
+ $ref: "#/components/schemas/Server"
+
+ Zone:
+ $id: Zone
+ title: Zone
+ description: This represents an authoritative DNS Zone.
+ type: object
+ 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"
+ - "Producer"
+ - "Consumer"
+ description: "Zone kind, one of “Native”, “Master”, “Slave”, “Producer”, “Consumer”"
+ rrsets:
+ type: array
+ items:
+ $ref: "#/components/schemas/RRSet"
+ description: "RRSets in this zone (for zones/{zone_id} endpoint only; omitted during GET on the .../zones list endpoint)"
+ serial:
+ type: integer
+ description: "The SOA serial number"
+ notified_serial:
+ type: integer
+ description: "The SOA serial notifications have been sent out for"
+ edited_serial:
+ type: integer
+ description: "The SOA serial as seen in query responses. Calculated using the SOA-EDIT metadata, default-soa-edit and default-soa-edit-signed settings"
+ masters:
+ type: array
+ items:
+ type: string
+ description: "List of IP addresses configured as a primary 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"
+ catalog:
+ type: string
+ description: "The catalog this zone is a member of"
+ 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 secondary zones."
+ master_tsig_key_ids:
+ type: array
+ items:
+ type: string
+ description: "The id of the TSIG keys used for primary operation in this zone"
+ externalDocs:
+ url: "https://doc.powerdns.com/authoritative/tsig.html#provisioning-outbound-axfr-access"
+ slave_tsig_key_ids:
+ type: array
+ items:
+ type: string
+ description: "The id of the TSIG keys used for secondary operation in this zone"
+ externalDocs:
+ url: "https://doc.powerdns.com/authoritative/tsig.html#provisioning-signed-notification-and-axfr-requests"
+
+ Zones:
+ $id: Zones
+ type: array
+ items:
+ $ref: "#/components/schemas/Zone"
+
+ RRSet:
+ $id: RRSet
+ title: RRSet
+ type: object
+ 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 one of DELETE, EXTEND, PRUNE or REPLACE. EXTEND and PRUNE are available since versions 4.9.12 and 5.0.2. With DELETE, all existing RRs matching name and type will be deleted, including all comments. With EXTEND, only a single record shall be present, and it will be added to the RRSet if not already present. With PRUNE, only a single record shall be present, and it will be deleted from the RRSet if present. 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, and must contain only one element when changetype is set to EXTEND or PRUNE. An empty list results in deletion of all records (and comments)."
+ items:
+ $ref: "#/components/schemas/Record"
+ comments:
+ type: array
+ description: "List of Comment. Must be empty when changetype is set to DELETE, EXTEND or PRUNE. An empty list results in deletion of all comments. modified_at is optional and defaults to the current server time."
+ items:
+ $ref: "#/components/schemas/Comment"
+
+ Record:
+ $id: Record
+ title: Record
+ type: object
+ description: The RREntry object represents a single record.
+ required:
+ - content
+ properties:
+ content:
+ type: string
+ description: "The content of this record"
+ disabled:
+ type: boolean
+ description: "Whether or not this record is disabled. When unset, the record is not disabled"
+ modified_at:
+ type: integer
+ description: "Timestamp of the last change to the record"
+
+ Comment:
+ $id: Comment
+ title: Comment
+ type: object
+ 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:
+ $id: TSIGKey
+ title: TSIGKey
+ type: object
+ description: A TSIG key that can be used to authenticate NOTIFY, AXFR, and DNSUPDATE queries.
+ 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
+
+ Autoprimary:
+ $id: Autoprimary
+ title: Autoprimary server
+ type: object
+ description: An autoprimary server that can provision new domains.
+ properties:
+ ip:
+ type: string
+ description: "IP address of the autoprimary server"
+ nameserver:
+ type: string
+ description: "DNS name of the autoprimary server"
+ account:
+ type: string
+ description: "Account name for the autoprimary server"
+
+ ConfigSetting:
+ $id: ConfigSetting
+ title: ConfigSetting
+ type: object
+ 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"
+
+ SimpleStatisticItem:
+ $id: SimpleStatisticItem
+ title: SimpleStatisticItem
+ type: object
+ properties:
+ name:
+ type: string
+ description: "Item name"
+ value:
+ type: string
+ description: "Item value"
+
+ StatisticItem:
+ $id: StatisticItem
+ title: StatisticItem
+ type: object
+ properties:
+ name:
+ type: string
+ description: "Item name"
+ type:
+ type: string
+ description: 'set to "StatisticItem"'
+ value:
+ type: string
+ description: "Item value"
+
+ MapStatisticItem:
+ $id: MapStatisticItem
+ title: MapStatisticItem
+ type: object
+ properties:
+ name:
+ type: string
+ description: "Item name"
+ type:
+ type: string
+ description: 'Set to "MapStatisticItem"'
+ value:
+ type: array
+ description: "Named values"
+ items:
+ $ref: "#/components/schemas/SimpleStatisticItem"
+
+ RingStatisticItem:
+ $id: RingStatisticItem
+ title: RingStatisticItem
+ type: object
+ properties:
+ name:
+ type: string
+ description: "Item name"
+ type:
+ type: string
+ description: 'Set to "RingStatisticItem"'
+ size:
+ type: integer
+ description: "Ring size"
+ value:
+ type: array
+ description: "Named values"
+ items:
+ $ref: "#/components/schemas/SimpleStatisticItem"
+
+ SearchResultZone:
+ $id: SearchResultZone
+ title: SearchResultZone
+ type: object
+ properties:
+ name:
+ type: string
+ object_type:
+ type: string
+ description: 'set to "zone"'
+ zone_id:
+ type: string
+
+ SearchResultRecord:
+ $id: SearchResultRecord
+ title: SearchResultRecord
+ type: object
+ 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:
+ $id: SearchResultComment
+ title: SearchResultComment
+ type: object
+ properties:
+ content:
+ type: string
+ name:
+ type: string
+ object_type:
+ type: string
+ description: 'set to "comment"'
+ zone_id:
+ type: string
+ zone:
+ type: string
+
+ SearchResult:
+ $id: SearchResult
+ anyOf:
+ - $ref: "#/components/schemas/SearchResultZone"
+ - $ref: "#/components/schemas/SearchResultRecord"
+ - $ref: "#/components/schemas/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:
+ $id: SearchResults
+ type: array
+ items:
+ $ref: "#/components/schemas/SearchResult"
+
+ Metadata:
+ $id: Metadata
+ title: Metadata
+ type: object
+ 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:
+ $id: Cryptokey
+ title: Cryptokey
+ type: object
+ description: "Describes a DNSSEC cryptographic key"
+ properties:
+ type:
+ type: string
+ description: 'set to "Cryptokey"'
+ id:
+ type: integer
+ 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"
+ published:
+ type: boolean
+ description: "Whether or not the DNSKEY record is published in the zone"
+ 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"
+ cds:
+ type: array
+ items:
+ type: string
+ description: "An array of DS records for this key, filtered by CDS publication settings"
+ 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:
+ $id: Error
+ title: Error
+ type: object
+ 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:
+ $id: CacheFlushResult
+ title: CacheFlushResult
+ type: object
+ 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"'
+
+ View:
+ $id: View
+ title: View
+ type: object
+ properties:
+ zones:
+ type: array
+ items:
+ type: string
+ description: "An array of zone names"
+
+ Views:
+ $id: Views
+ title: Views
+ type: object
+ properties:
+ views:
+ type: array
+ items:
+ type: string
+ description: "An array of view names"
+
+ Network:
+ $id: Network
+ title: Network
+ type: object
+ properties:
+ network:
+ type: string
+ description: "Network specification in human-readable form base address/prefix length"
+ view:
+ type: string
+ description: "The name of the view"
+
+ Networks:
+ $id: Networks
+ title: Networks
+ type: object
+ properties:
+ networks:
+ type: array
+ items:
+ $ref: "#/components/schemas/Network"
+
+ Result:
+ $id: Result
+ title: An operational result
+ type: object
+ properties:
+ result:
+ type: string
+ securitySchemes:
+ APIKeyHeader:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ responses: &commonErrors
+ "400":
+ description: The supplied request was not valid
+ content:
+ application/json:
schema:
- $ref: Error
- "404":
- description: Requested item was not found
+ $ref: "#/components/schemas/Error"
+ "404":
+ description: Requested item was not found
+ content:
+ application/json:
schema:
- $ref: Error
- "422":
- description: The input to the operation was not valid
+ $ref: "#/components/schemas/Error"
+ "422":
+ description: The input to the operation was not valid
+ content:
+ application/json:
schema:
- $ref: Error
- "500":
- description: Internal server error
+ $ref: "#/components/schemas/Error"
+ "500":
+ description: Internal server error
+ content:
+ application/json:
schema:
- $ref: Error
+ $ref: "#/components/schemas/Error"
+paths:
"/servers":
get:
- summary: List all servers
+ description: List all servers
operationId: listServers
tags:
- servers
responses:
"200":
description: An array of servers
- schema:
- type: array
- items:
- $ref: Server
- <<: *commonErrors
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Servers"
+ "400":
+ $ref: "#/components/responses/400"
+ "404":
+ $ref: "#/components/responses/404"
+ "422":
+ $ref: "#/components/responses/422"
+ "500":
+ $ref: "#/components/responses/500"
"/servers/{server_id}":
get:
- summary: List a server
+ description: List a server
operationId: listServer
tags:
- servers
responses:
"200":
description: An server
- schema:
- $ref: Server
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Server"
<<: *commonErrors
"/servers/{server_id}/cache/flush":
put:
- summary: Flush a cache-entry by name
+ description: Flush a cache-entry by name
operationId: cacheFlushByName
tags:
- servers
responses:
"200":
description: Flush successful
- schema:
- $ref: CacheFlushResult
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/CacheFlushResult"
<<: *commonErrors
"/servers/{server_id}/zones":
get:
- summary: List all Zones in a server
+ description: List all Zones in a server
operationId: listZones
tags:
- zones
required: false
schema:
type: boolean
- default: true
+ default: true
description: "“true” (default) or “false”, whether to include the “dnssec” and “edited_serial” fields in the Zone objects. Setting this to ”false” will make the query a lot faster."
responses:
"200":
description: An array of Zones
- schema:
- type: array
- items:
- $ref: Zone
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Zones"
<<: *commonErrors
post:
- summary: Creates a new domain, returns the Zone on creation.
+ description: Creates a new domain, returns the Zone on creation.
operationId: createZone
tags:
- zones
description: "“true” (default) or “false”, whether to include the “rrsets” in the response Zone object."
schema:
type: boolean
- default: true
- - name: zone_struct
- description: The zone struct to patch with
- required: true
- in: body
- schema:
- $ref: Zone
+ default: true
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Zone"
responses:
"201":
description: A zone
- schema:
- $ref: Zone
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Zone"
<<: *commonErrors
"/servers/{server_id}/zones/{zone_id}":
get:
- summary: zone managed by a server
+ description: zone managed by a server
operationId: listZone
tags:
- zones
description: "“true” (default) or “false”, whether to include the “rrsets” in the response Zone object."
schema:
type: boolean
- default: true
+ default: true
- name: rrset_name
in: query
description: Limit output to RRsets for this name.
description: "“true” (default) or “false”, whether to include disabled RRsets in the response."
schema:
type: boolean
+ default: true
responses:
"200":
description: A Zone
- schema:
- $ref: Zone
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Zone"
<<: *commonErrors
delete:
- summary: Deletes this zone, all attached metadata and rrsets.
+ description: Deletes this zone, all attached metadata and rrsets.
operationId: deleteZone
tags:
- zones
description: "Returns 204 No Content on success."
<<: *commonErrors
patch:
- summary: "Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success."
+ description: "Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success."
operationId: patchZone
tags:
- zones
parameters:
- <<: *server_id
- <<: *zone_id
- - name: zone_struct
- description: The zone struct to patch with
- required: true
- in: body
- schema:
- $ref: Zone
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Zone"
responses:
"204":
description: "Returns 204 No Content on success."
parameters:
- <<: *server_id
- <<: *zone_id
- - name: zone_struct
- description: The zone struct to patch with
- required: true
- in: body
- schema:
- $ref: Zone
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Zone"
responses:
"204":
description: "Returns 204 No Content on success."
"/servers/{server_id}/zones/{zone_id}/export":
get:
- summary: "Returns the zone in AXFR format."
+ description: "Returns the zone in AXFR format."
operationId: axfrExportZone
tags:
- zones
responses:
"200":
description: OK
- schema:
- type: string
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Result"
+ text/plain:
+ schema:
+ type: string
<<: *commonErrors
"/servers/{server_id}/zones/{zone_id}/rectify":
responses:
"200":
description: OK
- schema:
- type: string
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Result"
<<: *commonErrors
"/servers/{server_id}/config":
get:
- summary: "Returns all ConfigSettings for a single server"
+ description: "Returns all ConfigSettings for a single server"
operationId: getConfig
tags:
- config
responses:
"200":
description: List of config values
- schema:
- type: array
- items:
- $ref: ConfigSetting
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/ConfigSetting"
<<: *commonErrors
"/servers/{server_id}/config/{config_setting_name}":
in: path
required: true
description: The name of the setting to retrieve
- type: string
+ schema:
+ type: string
responses:
"200":
description: List of config values
- schema:
- $ref: ConfigSetting
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ConfigSetting"
<<: *commonErrors
"/servers/{server_id}/statistics":
required: false
schema:
type: boolean
- default: true
+ default: true
description: "“true” (default) or “false”, whether to include the Ring items, which can contain thousands of log messages or queried domains. Setting this to ”false” may make the response a lot smaller."
responses:
"200":
description: List of Statistic Items
- schema:
- type: array
- items:
- oneOf:
- - $ref: StatisticItem
- - $ref: MapStatisticItem
- - $ref: RingStatisticItem
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ oneOf:
+ - $ref: "#/components/schemas/StatisticItem"
+ - $ref: "#/components/schemas/MapStatisticItem"
+ - $ref: "#/components/schemas/RingStatisticItem"
"422":
description: "Returned when a non-existing statistic name has been requested. Contains an error message"
<<: *commonErrors
responses:
"200":
description: Returns a JSON array with results
- schema:
- $ref: SearchResults
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SearchResults"
<<: *commonErrors
"/servers/{server_id}/zones/{zone_id}/metadata":
get:
- summary: "Get all the Metadata associated with the zone."
+ description: "Get all the Metadata associated with the zone."
operationId: listMetadata
tags:
- zonemetadata
responses:
"200":
description: List of Metadata objects
- schema:
- type: array
- items:
- $ref: Metadata
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/Metadata"
<<: *commonErrors
post:
summary: "Creates a set of metadata entries"
parameters:
- <<: *server_id
- <<: *zone_id
- - name: metadata
- description: Metadata object with list of values to create
- required: true
- in: body
- schema:
- $ref: Metadata
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Metadata"
responses:
"204":
description: OK
"/servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}":
get:
- summary: "Get the content of a single kind of domain metadata as a Metadata object."
+ description: "Get the content of a single kind of domain metadata as a Metadata object."
operationId: getMetadata
tags:
- zonemetadata
responses:
"200":
description: Metadata object with list of values
- schema:
- $ref: Metadata
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Metadata"
<<: *commonErrors
put:
summary: "Replace the content of a single kind of domain metadata."
- <<: *server_id
- <<: *zone_id
- <<: *metadata_kind
- - name: metadata
- description: metadata to add/create
- required: true
- in: body
- schema:
- $ref: Metadata
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Metadata"
responses:
"200":
description: Metadata object with list of values
- schema:
- $ref: Metadata
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Metadata"
<<: *commonErrors
delete:
- summary: "Delete all items of a single kind of domain metadata."
+ description: "Delete all items of a single kind of domain metadata."
operationId: deleteMetadata
tags:
- zonemetadata
"/servers/{server_id}/zones/{zone_id}/cryptokeys":
get:
- summary: "Get all CryptoKeys for a zone, except the privatekey"
+ description: "Get all CryptoKeys for a zone, except the privatekey"
operationId: listCryptokeys
tags:
- zonecryptokey
responses:
"200":
description: List of Cryptokey objects
- schema:
- type: array
- items:
- $ref: Cryptokey
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/Cryptokey"
<<: *commonErrors
post:
summary: "Creates a Cryptokey"
parameters:
- <<: *server_id
- <<: *zone_id
- - name: cryptokey
- description: Add a Cryptokey
- required: true
- in: body
- schema:
- $ref: Cryptokey
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Cryptokey"
responses:
"201":
description: Created
- schema:
- $ref: Cryptokey
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Cryptokey"
<<: *commonErrors
"/servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}":
get:
- summary: "Returns all data about the CryptoKey, including the privatekey."
+ description: "Returns all data about the CryptoKey, including the privatekey."
operationId: getCryptokey
tags:
- zonecryptokey
responses:
"200":
description: Cryptokey
- schema:
- $ref: Cryptokey
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Cryptokey"
<<: *commonErrors
put:
- summary: "This method (de)activates a key from zone_name specified by cryptokey_id"
+ description: "This method (de)activates a key from zone_name specified by cryptokey_id"
operationId: modifyCryptokey
tags:
- zonecryptokey
- <<: *server_id
- <<: *zone_id
- <<: *cryptokey_id
- - name: cryptokey
- description: the Cryptokey
- required: true
- in: body
- schema:
- $ref: Cryptokey
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Cryptokey"
responses:
"204":
description: OK
<<: *commonErrors
delete:
- summary: "This method deletes a key specified by cryptokey_id."
+ description: "This method deletes a key specified by cryptokey_id."
operationId: deleteCryptokey
tags:
- zonecryptokey
parameters:
- <<: *server_id
get:
- summary: "Get all TSIGKeys on the server, except the actual key"
+ description: "Get all TSIGKeys on the server, except the actual key"
operationId: listTSIGKeys
tags:
- tsigkey
responses:
"200":
description: List of TSIGKey objects
- schema:
- type: array
- items:
- $ref: TSIGKey
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/TSIGKey"
<<: *commonErrors
post:
summary: "Add a TSIG key"
operationId: createTSIGKey
tags:
- tsigkey
- parameters:
- - name: tsigkey
- description: The TSIGKey to add
- required: true
- in: body
- schema:
- $ref: TSIGKey
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/TSIGKey"
responses:
"201":
description: Created
- schema:
- $ref: TSIGKey
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TSIGKey"
"409":
description: An item with this name already exists
- schema:
- $ref: Error
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
<<: *commonErrors
"/servers/{server_id}/tsigkeys/{tsigkey_id}":
schema:
type: string
get:
- summary: "Get a specific TSIGKeys on the server, including the actual key"
+ description: "Get a specific TSIGKeys on the server, including the actual key"
operationId: getTSIGKey
tags:
- tsigkey
responses:
"200":
description: OK.
- schema:
- $ref: TSIGKey
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TSIGKey"
<<: *commonErrors
put:
description: |
operationId: putTSIGKey
tags:
- tsigkey
- parameters:
- - name: tsigkey
- description: A (possibly stripped down) TSIGKey object with the new values
- schema:
- $ref: TSIGKey
- in: body
- required: true
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/TSIGKey"
responses:
"200":
description: OK. TSIGKey is changed.
- schema:
- $ref: TSIGKey
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/TSIGKey"
"409":
description: An item with this name already exists
- schema:
- $ref: Error
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
<<: *commonErrors
delete:
- summary: "Delete the TSIGKey with tsigkey_id"
+ description: "Delete the TSIGKey with tsigkey_id"
operationId: deleteTSIGKey
tags:
- tsigkey
parameters:
- <<: *server_id
get:
- summary: "Get a list of autoprimaries"
+ description: "Get a list of autoprimaries"
operationId: getAutoprimaries
tags:
- autoprimary
responses:
"200":
description: OK.
- schema:
- $ref: Autoprimary
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Autoprimary"
<<: *commonErrors
post:
- summary: "Add an autoprimary"
- description: "This methods add a new autoprimary server."
+ description: "This method add a new autoprimary server."
operationId: createAutoprimary
tags:
- autoprimary
- parameters:
- - name: autoprimary
- description: autoprimary entry to add
- required: true
- in: body
- schema:
- $ref: Autoprimary
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ schema:
+ $ref: "#/components/schemas/Autoprimary"
responses:
"201":
description: Created
schema:
type: string
delete:
- summary: "Delete the autoprimary entry"
+ description: "Delete the autoprimary entry"
operationId: deleteAutoprimary
tags:
- autoprimary
parameters:
- <<: *server_id
get:
- summary: List all views in a server
+ description: List all views in a server
operationId: listViews
tags:
- views
responses:
"200":
description: An array of view names
- schema:
- $ref: Views
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Views"
<<: *commonErrors
"/servers/{server_id}/views/{view}":
required: true
description: The name of the view to retrieve
get:
- summary: List the contents of a given view
+ description: List the contents of a given view
operationId: listView
tags:
- views
responses:
"200":
description: An array of zone names
- schema:
- $ref: View
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/View"
<<: *commonErrors
post:
- summary: Adds a zone to a given view, creating it if needed
+ description: Adds a zone to a given view, creating it if needed
operationId: addToView
tags:
- views
in: path
required: true
description: The name of the view to update
- - name: name
- description: The zone to add to the view
- required: true
- in: body
- schema:
- type: string
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ description: The zone to add to the view
+ type: string
responses:
"204":
description: "Returns 204 No Content on success."
"/servers/{server_id}/views/{view}/{id}":
delete:
- summary: Removes the given zone from the given view
+ description: Removes the given zone from the given view
operationId: deleteFromView
tags:
- views
"/servers/{server_id}/networks":
get:
- summary: List all registered networks and views in a server
+ description: List all registered networks and views in a server
operationId: listNetworks
tags:
- networks
responses:
"200":
description: An array of networks
- schema:
- $ref: Networks
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Networks"
<<: *commonErrors
"/servers/{server_id}/networks/{ip}/{prefixlen}":
get:
- summary: Return the view associated to the given network
+ description: Return the view associated to the given network
operationId: getNetwork
tags:
- networks
description: The length of the network prefix
responses:
"200":
- description: A network
- schema:
- $ref: Network
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Network"
<<: *commonErrors
+
put:
- summary: Sets the view associated to the given network
+ description: Sets the view associated to the given network
operationId: setNetwork
tags:
- networks
in: path
required: true
description: The length of the network prefix
- - name: view
- required: true
- description: The name of the view to use for this network
- in: body
- schema:
- type: string
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - view
+ properties:
+ view:
+ description: The name of the view to use for this network
+ type: string
responses:
"204":
description: "Returns 204 No Content on success."
<<: *commonErrors
-
-definitions:
- Server:
- $id: Server
- type: object
- 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:
- $id: Servers
- type: array
- items:
- $ref: Server
-
- Zone:
- $id: Zone
- title: Zone
- description: This represents an authoritative DNS Zone.
- type: object
- 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"
- - "Producer"
- - "Consumer"
- description: "Zone kind, one of “Native”, “Master”, “Slave”, “Producer”, “Consumer”"
- rrsets:
- type: array
- items:
- $ref: RRSet
- description: "RRSets in this zone (for zones/{zone_id} endpoint only; omitted during GET on the .../zones list endpoint)"
- serial:
- type: integer
- description: "The SOA serial number"
- notified_serial:
- type: integer
- description: "The SOA serial notifications have been sent out for"
- edited_serial:
- type: integer
- description: "The SOA serial as seen in query responses. Calculated using the SOA-EDIT metadata, default-soa-edit and default-soa-edit-signed settings"
- masters:
- type: array
- items:
- type: string
- description: "List of IP addresses configured as a primary 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"
- catalog:
- type: string
- description: "The catalog this zone is a member of"
- 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 secondary zones."
- master_tsig_key_ids:
- type: array
- items:
- type: string
- description: "The id of the TSIG keys used for primary operation in this zone"
- externalDocs:
- url: "https://doc.powerdns.com/authoritative/tsig.html#provisioning-outbound-axfr-access"
- slave_tsig_key_ids:
- type: array
- items:
- type: string
- description: "The id of the TSIG keys used for secondary operation in this zone"
- externalDocs:
- url: "https://doc.powerdns.com/authoritative/tsig.html#provisioning-signed-notification-and-axfr-requests"
-
- Zones:
- $id: Zones
- type: array
- items:
- $ref: Zone
-
- RRSet:
- $id: RRSet
- title: RRSet
- type: object
- 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 one of DELETE, EXTEND, PRUNE or REPLACE. EXTEND and PRUNE are available since versions 4.9.12 and 5.0.2. With DELETE, all existing RRs matching name and type will be deleted, including all comments. With EXTEND, only a single record shall be present, and it will be added to the RRSet if not already present. With PRUNE, only a single record shall be present, and it will be deleted from the RRSet if present. 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, and must contain only one element when changetype is set to EXTEND or PRUNE. An empty list results in deletion of all records (and comments)."
- items:
- $ref: Record
- comments:
- type: array
- description: "List of Comment. Must be empty when changetype is set to DELETE, EXTEND or PRUNE. An empty list results in deletion of all comments. modified_at is optional and defaults to the current server time."
- items:
- $ref: Comment
-
- Record:
- $id: Record
- title: Record
- type: object
- description: The RREntry object represents a single record.
- required:
- - content
- properties:
- content:
- type: string
- description: "The content of this record"
- disabled:
- type: boolean
- description: "Whether or not this record is disabled. When unset, the record is not disabled"
- modified_at:
- type: integer
- description: "Timestamp of the last change to the record"
-
- Comment:
- $id: Comment
- title: Comment
- type: object
- 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:
- $id: TSIGKey
- title: TSIGKey
- type: object
- description: A TSIG key that can be used to authenticate NOTIFY, AXFR, and DNSUPDATE queries.
- 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
-
- Autoprimary:
- $id: Autoprimary
- title: Autoprimary server
- type: object
- description: An autoprimary server that can provision new domains.
- properties:
- ip:
- type: string
- description: "IP address of the autoprimary server"
- nameserver:
- type: string
- description: "DNS name of the autoprimary server"
- account:
- type: string
- description: "Account name for the autoprimary server"
-
- ConfigSetting:
- $id: ConfigSetting
- title: ConfigSetting
- type: object
- 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"
-
- SimpleStatisticItem:
- $id: SimpleStatisticItem
- title: SimpleStatisticItem
- type: object
- properties:
- name:
- type: string
- description: "Item name"
- value:
- type: string
- description: "Item value"
-
- StatisticItem:
- $id: StatisticItem
- title: StatisticItem
- type: object
- properties:
- name:
- type: string
- description: "Item name"
- type:
- type: string
- description: 'set to "StatisticItem"'
- value:
- type: string
- description: "Item value"
-
- MapStatisticItem:
- $id: MapStatisticItem
- title: MapStatisticItem
- type: object
- properties:
- name:
- type: string
- description: "Item name"
- type:
- type: string
- description: 'Set to "MapStatisticItem"'
- value:
- type: array
- description: "Named values"
- items:
- $ref: SimpleStatisticItem
-
- RingStatisticItem:
- $id: RingStatisticItem
- title: RingStatisticItem
- type: object
- properties:
- name:
- type: string
- description: "Item name"
- type:
- type: string
- description: 'Set to "RingStatisticItem"'
- size:
- type: integer
- description: "Ring size"
- value:
- type: array
- description: "Named values"
- items:
- $ref: SimpleStatisticItem
-
- SearchResultZone:
- $id: SearchResultZone
- title: SearchResultZone
- type: object
- properties:
- name:
- type: string
- object_type:
- type: string
- description: 'set to "zone"'
- zone_id:
- type: string
-
- SearchResultRecord:
- $id: SearchResultRecord
- title: SearchResultRecord
- type: object
- 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:
- $id: SearchResultComment
- title: SearchResultComment
- type: object
- properties:
- content:
- type: string
- name:
- type: string
- object_type:
- type: string
- description: 'set to "comment"'
- zone_id:
- type: string
- zone:
- type: string
-
- SearchResult:
- $id: SearchResult
- anyOf:
- - $ref: SearchResultZone
- - $ref: SearchResultRecord
- - $ref: 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:
- $id: SearchResults
- type: array
- items:
- $ref: SearchResult
-
- Metadata:
- $id: Metadata
- title: Metadata
- type: object
- 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:
- $id: Cryptokey
- title: Cryptokey
- type: object
- description: "Describes a DNSSEC cryptographic key"
- properties:
- type:
- type: string
- description: 'set to "Cryptokey"'
- id:
- type: integer
- 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"
- published:
- type: boolean
- description: "Whether or not the DNSKEY record is published in the zone"
- 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"
- cds:
- type: array
- items:
- type: string
- description: "An array of DS records for this key, filtered by CDS publication settings"
- 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:
- $id: Error
- title: Error
- type: object
- 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:
- $id: CacheFlushResult
- title: CacheFlushResult
- type: object
- 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"'
-
- View:
- $id: View
- title: View
- type: object
- properties:
- zones:
- type: array
- items:
- type: string
- description: "An array of zone names"
-
- Views:
- $id: Views
- title: Views
- type: object
- properties:
- views:
- type: array
- items:
- type: string
- description: "An array of view names"
-
- Network:
- $id: Network
- title: Network
- type: object
- properties:
- network:
- type: string
- description: "Network specification in human-readable form base address/prefix length"
- view:
- type: string
- description: "The name of the view"
-
- Networks:
- $id: Networks
- title: Networks
- type: object
- properties:
- networks:
- type: array
- items:
- $ref: Network
projects / thirdparty / pdns.git / commitdiff
