docs/http-api/swagger/authoritative-api-swagger.yaml

   1 swagger: '2.0'
   2 info:
   3   version: "0.0.13"
   4   title: PowerDNS Authoritative HTTP API
   5   license:
   6     name: MIT
   7 host: localhost:8081
   8 basePath: /api/v1
   9 schemes:
  10   - http
  11 consumes:
  12   - application/json
  13 produces:
  14   - application/json
  15 securityDefinitions:
  16   # X-API-Key: abcdef12345
  17   APIKeyHeader:
  18     type: apiKey
  19     in: header
  20     name: X-API-Key
  21 security:
  22   - APIKeyHeader: []
  23
  24 # Overall TODOS:
  25 # TODO: Return types are not consistent across documentation
  26 #       We need to look at the code and figure out the default HTTP response
  27 #       codes and adjust docs accordingly.
  28 paths:
  29   '/servers':
  30     get:
  31       summary: List all servers
  32       operationId: listServers
  33       tags:
  34         - servers
  35       responses:
  36         '200':
  37           description: An array of servers
  38           schema:
  39             type: array
  40             items:
  41               $ref: '#/definitions/Server'
  42
  43   '/servers/{server_id}':
  44     get:
  45       summary: List a server
  46       operationId: listServer
  47       tags:
  48         - servers
  49       parameters:
  50         - name: server_id
  51           in: path
  52           required: true
  53           description: The id of the server to retrieve
  54           type: string
  55       responses:
  56         '200':
  57           description: An server
  58           schema:
  59             $ref: '#/definitions/Server'
  60
  61   '/servers/{server_id}/cache/flush':
  62     put:
  63       summary: Flush a cache-entry by name
  64       operationId: cacheFlushByName
  65       tags:
  66         - servers
  67       parameters:
  68         - name: server_id
  69           in: path
  70           required: true
  71           description: The id of the server to retrieve
  72           type: string
  73         - name: domain
  74           in: query
  75           required: true
  76           description: The domain name to flush from the cache
  77           type: string
  78       responses:
  79         '200':
  80           description: Flush successful
  81           schema:
  82             $ref: '#/definitions/CacheFlushResult'
  83
  84   '/servers/{server_id}/zones':
  85     get:
  86       summary: List all Zones in a server
  87       operationId: listZones
  88       tags:
  89         - zones
  90       parameters:
  91         - name: server_id
  92           in: path
  93           required: true
  94           description: The id of the server to retrieve
  95           type: string
  96         - name: zone
  97           in: query
  98           required: false
  99           type: string
 100           description: |
 101             When set to the name of a zone, only this zone is returned.
 102             If no zone with that name exists, the response is an empty array.
 103             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.
 104       responses:
 105         '200':
 106           description: An array of Zones
 107           schema:
 108             type: array
 109             items:
 110               $ref: '#/definitions/Zone'
 111     post:
 112       summary: Creates a new domain, returns the Zone on creation.
 113       operationId: createZone
 114       tags:
 115         - zones
 116       parameters:
 117         - name: server_id
 118           in: path
 119           required: true
 120           description: The id of the server to retrieve
 121           type: string
 122         - name: rrsets
 123           in: query
 124           description: '“true” (default) or “false”, whether to include the “rrsets” in the response Zone object.'
 125           type: boolean
 126           default: true
 127         - name: zone_struct
 128           description: The zone struct to patch with
 129           required: true
 130           in: body
 131           schema:
 132             $ref: '#/definitions/Zone'
 133       responses:
 134         '201':
 135           description: A zone
 136           schema:
 137               $ref: '#/definitions/Zone'
 138
 139   '/servers/{server_id}/zones/{zone_id}':
 140     get:
 141       summary: zone managed by a server
 142       operationId: listZone
 143       tags:
 144         - zones
 145       parameters:
 146         - name: server_id
 147           in: path
 148           required: true
 149           description: The id of the server to retrieve
 150           type: string
 151         - name: zone_id
 152           type: string
 153           in: path
 154           required: true
 155           description: The id of the zone to retrieve
 156       responses:
 157         '200':
 158           description: A Zone
 159           schema:
 160             $ref: '#/definitions/Zone'
 161     delete:
 162       summary: Deletes this zone, all attached metadata and rrsets.
 163       operationId: deleteZone
 164       tags:
 165         - zones
 166       parameters:
 167         - name: server_id
 168           in: path
 169           required: true
 170           description: The id of the server to retrieve
 171           type: string
 172         - name: zone_id
 173           type: string
 174           in: path
 175           required: true
 176           description: The id of the zone to retrieve
 177       responses:
 178         '204':
 179           description: 'Returns 204 No Content on success.'
 180     patch:
 181       summary: 'Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success.'
 182       operationId: patchZone
 183       tags:
 184         - zones
 185       parameters:
 186         - name: server_id
 187           in: path
 188           required: true
 189           description: The id of the server to retrieve
 190           type: string
 191         - name: zone_id
 192           type: string
 193           in: path
 194           required: true
 195         - name: zone_struct
 196           description: The zone struct to patch with
 197           required: true
 198           in: body
 199           schema:
 200             $ref: '#/definitions/Zone'
 201       responses:
 202         '204':
 203           description: 'Returns 204 No Content on success.'
 204
 205     put:
 206       summary: Modifies basic zone data (metadata).
 207       description: 'Allowed fields in client body: all except id, url and name. Returns 204 No Content on success.'
 208       operationId: putZone
 209       tags:
 210         - zones
 211       parameters:
 212         - name: server_id
 213           in: path
 214           required: true
 215           description: The id of the server to retrieve
 216           type: string
 217         - name: zone_id
 218           type: string
 219           in: path
 220           required: true
 221         - name: zone_struct
 222           description: The zone struct to patch with
 223           required: true
 224           in: body
 225           schema:
 226             $ref: '#/definitions/Zone'
 227       responses:
 228         '204':
 229           description: 'Returns 204 No Content on success.'
 230
 231   '/servers/{server_id}/zones/{zone_id}/notify':
 232     put:
 233       summary: Send a DNS NOTIFY to all slaves.
 234       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.'
 235       operationId: notifyZone
 236       tags:
 237         - zones
 238       parameters:
 239         - name: server_id
 240           in: path
 241           required: true
 242           description: The id of the server to retrieve
 243           type: string
 244         - name: zone_id
 245           type: string
 246           in: path
 247           required: true
 248           description: The id of the zone to retrieve
 249       responses:
 250         '200':
 251           description: OK
 252
 253   '/servers/{server_id}/zones/{zone_id}/axfr-retrieve':
 254     put:
 255       summary: Retrieve slave zone from its master.
 256       description: 'Fails when zone kind is not Slave, or slave is disabled in the configuration. Clients MUST NOT send a body.'
 257       operationId: axfrRetrieveZone
 258       tags:
 259         - zones
 260       parameters:
 261         - name: server_id
 262           in: path
 263           required: true
 264           description: The id of the server to retrieve
 265           type: string
 266         - name: zone_id
 267           type: string
 268           in: path
 269           required: true
 270           description: The id of the zone to retrieve
 271       responses:
 272         '200':
 273           description: OK
 274
 275   '/servers/{server_id}/zones/{zone_id}/export':
 276     get:
 277       summary: 'Returns the zone in AXFR format.'
 278       operationId: axfrExportZone
 279       tags:
 280         - zones
 281       parameters:
 282         - name: server_id
 283           in: path
 284           required: true
 285           description: The id of the server to retrieve
 286           type: string
 287         - name: zone_id
 288           type: string
 289           in: path
 290           required: true
 291           description: The id of the zone to retrieve
 292       responses:
 293         '200':
 294           description: OK
 295           schema:
 296             type: string
 297
 298   '/servers/{server_id}/zones/{zone_id}/check':
 299     get:
 300       summary: 'Verify zone contents/configuration.'
 301       operationId: checkZone
 302       tags:
 303         - zones
 304       parameters:
 305         - name: server_id
 306           in: path
 307           required: true
 308           description: The id of the server to retrieve
 309           type: string
 310         - name: zone_id
 311           type: string
 312           in: path
 313           required: true
 314           description: The id of the zone to retrieve
 315       responses:
 316         '200':
 317           description: OK
 318           schema:
 319             type: string
 320
 321   '/servers/{server_id}/zones/{zone_id}/rectify':
 322     put:
 323       summary: 'Rectify the zone data.'
 324       description: 'This does not take into account the API-RECTIFY metadata. Fails on slave zones and zones that do not have DNSSEC.'
 325       operationId: rectifyZone
 326       tags:
 327         - zones
 328       parameters:
 329         - name: server_id
 330           in: path
 331           required: true
 332           description: The id of the server to retrieve
 333           type: string
 334         - name: zone_id
 335           type: string
 336           in: path
 337           required: true
 338           description: The id of the zone to retrieve
 339       responses:
 340         '200':
 341           description: OK
 342           schema:
 343             type: string
 344
 345   '/servers/{server_id}/config':
 346     get:
 347       summary: 'Returns all ConfigSettings for a single server'
 348       operationId: getConfig
 349       tags:
 350         - config
 351       parameters:
 352         - name: server_id
 353           in: path
 354           required: true
 355           description: The id of the server to retrieve
 356           type: string
 357       responses:
 358         '200':
 359           description: List of config values
 360           schema:
 361             type: array
 362             items:
 363               $ref: '#/definitions/ConfigSetting'
 364
 365   '/servers/{server_id}/config/{config_setting_name}':
 366     get:
 367       summary: 'Returns a specific ConfigSetting for a single server'
 368       description: 'NOT IMPLEMENTED'
 369       operationId: getConfigSetting
 370       tags:
 371         - config
 372       parameters:
 373         - name: server_id
 374           in: path
 375           required: true
 376           description: The id of the server to retrieve
 377           type: string
 378         - name: config_setting_name
 379           in: path
 380           required: true
 381           description: The name of the setting to retrieve
 382           type: string
 383       responses:
 384         '200':
 385           description: List of config values
 386           schema:
 387             $ref: '#/definitions/ConfigSetting'
 388
 389   '/servers/{server_id}/statistics':
 390     get:
 391       summary: 'Query statistics.'
 392       description: 'Query PowerDNS internal statistics. Returns a list of BaseStatisticItem derived elements.'
 393       operationId: getStats
 394       tags:
 395         - stats
 396       parameters:
 397         - name: server_id
 398           in: path
 399           required: true
 400           description: The id of the server to retrieve
 401           type: string
 402       responses:
 403         '200':
 404           description: List of Statistic Items
 405           schema:
 406             type: array
 407             items:
 408             # these can be commented because the swagger code generator fails on them
 409             # and replaced with
 410             # type: string
 411             # or something like that
 412             - $ref: '#/definitions/StatisticItem'
 413             - $ref: '#/definitions/MapStatisticItem'
 414             - $ref: '#/definitions/RingStatisticItem'
 415
 416   '/servers/{server_id}/search-data':
 417     get:
 418       summary: 'Search the data inside PowerDNS'
 419       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.'
 420       operationId: searchData
 421       tags:
 422         - search
 423       parameters:
 424         - name: server_id
 425           in: path
 426           required: true
 427           description: The id of the server to retrieve
 428           type: string
 429         - name: q
 430           in: query
 431           required: true
 432           description: 'The string to search for'
 433           type: string
 434         - name: max
 435           in: query
 436           required: true
 437           description: 'Maximum number of entries to return'
 438           type: integer
 439         - name: type
 440           in: query
 441           required: false
 442           description: 'Type of data to search for, one of “all”, “zone”, “record”, “comment”'
 443           type: string
 444       responses:
 445         '200':
 446           description: Returns a JSON array with results
 447           schema:
 448             $ref: '#/definitions/SearchResults'
 449
 450   '/servers/{server_id}/zones/{zone_id}/metadata':
 451     get:
 452       summary: Get all the MetaData associated with the zone.
 453       operationId: listMetadata
 454       tags:
 455         - zonemetadata
 456       parameters:
 457         - name: server_id
 458           in: path
 459           required: true
 460           description: The id of the server to retrieve
 461           type: string
 462         - name: zone_id
 463           type: string
 464           in: path
 465           required: true
 466           description: The id of the zone to retrieve
 467       responses:
 468         '200':
 469           description: List of Metadata objects
 470           schema:
 471             type: array
 472             items:
 473               $ref: '#/definitions/Metadata'
 474     post:
 475       summary: 'Creates a set of metadata entries'
 476       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.'
 477       operationId: createMetadata
 478       tags:
 479         - zonemetadata
 480       parameters:
 481         - name: server_id
 482           in: path
 483           required: true
 484           description: The id of the server to retrieve
 485           type: string
 486         - name: zone_id
 487           type: string
 488           in: path
 489           required: true
 490         - name: metadata
 491           description: List of metadata to add/create
 492           required: true
 493           in: body
 494           schema:
 495             type: array
 496             items:
 497               $ref: '#/definitions/Metadata'
 498       responses:
 499         '204':
 500           description: OK
 501
 502   '/servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}':
 503     get:
 504       summary: Get the content of a single kind of domain metadata as a list of MetaData objects.
 505       operationId: getMetadata
 506       tags:
 507         - zonemetadata
 508       parameters:
 509         - name: server_id
 510           in: path
 511           required: true
 512           description: The id of the server to retrieve
 513           type: string
 514         - name: zone_id
 515           type: string
 516           in: path
 517           required: true
 518           description: The id of the zone to retrieve
 519         - name: metadata_kind
 520           type: string
 521           in: path
 522           required: true
 523           description: '???'
 524       responses:
 525         '200':
 526           description: List of Metadata objects
 527           schema:
 528             $ref: '#/definitions/Metadata'
 529     put:
 530       summary: 'Modify the content of a single kind of domain metadata.'
 531       operationId: modifyMetadata
 532       tags:
 533         - zonemetadata
 534       parameters:
 535         - name: server_id
 536           in: path
 537           required: true
 538           description: The id of the server to retrieve
 539           type: string
 540         - name: zone_id
 541           type: string
 542           in: path
 543           required: true
 544         - name: metadata_kind
 545           description: The kind of metadata
 546           required: true
 547           type: string
 548           in: path
 549         - name: metadata
 550           description: metadata to add/create
 551           required: true
 552           in: body
 553           schema:
 554             $ref: '#/definitions/Metadata'
 555       responses:
 556         '204':
 557           description: OK
 558     delete:
 559       summary: 'Delete all items of a single kind of domain metadata.'
 560       operationId: deleteMetadata
 561       tags:
 562         - zonemetadata
 563       parameters:
 564         - name: server_id
 565           in: path
 566           required: true
 567           description: The id of the server to retrieve
 568           type: string
 569         - name: zone_id
 570           type: string
 571           in: path
 572           required: true
 573           description: The id of the zone to retrieve
 574         - name: metadata_kind
 575           type: string
 576           in: path
 577           required: true
 578           description: '???'
 579       responses:
 580         '204':
 581           description: OK
 582
 583   '/servers/{server_id}/zones/{zone_id}/cryptokeys':
 584     get:
 585       summary: 'Get all CryptoKeys for a zone, except the privatekey'
 586       operationId: listCryptokeys
 587       tags:
 588         - zonecryptokey
 589       parameters:
 590         - name: server_id
 591           in: path
 592           required: true
 593           description: The id of the server to retrieve
 594           type: string
 595         - name: zone_id
 596           type: string
 597           in: path
 598           required: true
 599           description: The id of the zone to retrieve
 600       responses:
 601         '200':
 602           description: List of Cryptokey objects
 603           schema:
 604             type: array
 605             items:
 606               $ref: '#/definitions/Cryptokey'
 607     post:
 608       summary: 'Creates a Cryptokey'
 609       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.'
 610       operationId: createCryptokey
 611       tags:
 612         - zonecryptokey
 613       parameters:
 614         - name: server_id
 615           in: path
 616           required: true
 617           description: The id of the server to retrieve
 618           type: string
 619         - name: zone_id
 620           type: string
 621           in: path
 622           required: true
 623         - name: cryptokey
 624           description: Add a Cryptokey
 625           required: true
 626           in: body
 627           schema:
 628             $ref: '#/definitions/Cryptokey'
 629       responses:
 630         '201':
 631           description: Created
 632           schema:
 633             $ref: '#/definitions/Cryptokey'
 634
 635   '/servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}':
 636     get:
 637       summary: 'Returns all data about the CryptoKey, including the privatekey.'
 638       operationId: getCryptokey
 639       tags:
 640         - zonecryptokey
 641       parameters:
 642         - name: server_id
 643           in: path
 644           required: true
 645           description: The id of the server to retrieve
 646           type: string
 647         - name: zone_id
 648           type: string
 649           in: path
 650           required: true
 651           description: The id of the zone to retrieve
 652         - name: cryptokey_id
 653           type: string
 654           in: path
 655           required: true
 656           description: 'The id value of the CryptoKey'
 657       responses:
 658         '200':
 659           description: Cryptokey
 660           schema:
 661             $ref: '#/definitions/Cryptokey'
 662     put:
 663       summary: 'This method (de)activates a key from zone_name specified by cryptokey_id'
 664       operationId: modifyCryptokey
 665       tags:
 666         - zonecryptokey
 667       parameters:
 668         - name: server_id
 669           in: path
 670           required: true
 671           description: The id of the server to retrieve
 672           type: string
 673         - name: zone_id
 674           type: string
 675           in: path
 676           required: true
 677         - name: cryptokey_id
 678           description: Cryptokey to manipulate
 679           required: true
 680           in: path
 681           type: string
 682         - name: cryptokey
 683           description: the Cryptokey
 684           required: true
 685           in: body
 686           schema:
 687             $ref: '#/definitions/Cryptokey'
 688       responses:
 689         '204':
 690           description: OK
 691         '422':
 692           description: 'Returned when something is wrong with the content of the request. Contains an error message'
 693     delete:
 694       summary: 'This method deletes a key specified by cryptokey_id.'
 695       operationId: deleteCryptokey
 696       tags:
 697         - zonecryptokey
 698       parameters:
 699         - name: server_id
 700           in: path
 701           required: true
 702           description: The id of the server to retrieve
 703           type: string
 704         - name: zone_id
 705           type: string
 706           in: path
 707           required: true
 708           description: The id of the zone to retrieve
 709         - name: cryptokey_id
 710           type: string
 711           in: path
 712           required: true
 713           description: 'The id value of the Cryptokey'
 714       responses:
 715         '204':
 716           description: OK
 717         '422':
 718           description: 'Returned when something is wrong with the content of the request. Contains an error message'
 719
 720   '/servers/{server_id}/tsigkeys':
 721     parameters:
 722       - name: server_id
 723         in: path
 724         required: true
 725         description: 'The id of the server'
 726         type: string
 727     get:
 728       summary: 'Get all TSIGKeys on the server, except the actual key'
 729       operationId: listTSIGKeys
 730       tags:
 731         - tsigkey
 732       responses:
 733         '200':
 734           description: List of TSIGKey objects
 735           schema:
 736             type: array
 737             items:
 738               $ref: '#/definitions/TSIGKey'
 739         '500':
 740           description: 'Internal Server Error, keys could not be retrieved. Contains error message'
 741           schema:
 742             $ref: '#/definitions/Error'
 743     post:
 744       summary: 'Add a TSIG key'
 745       description: 'This methods add a new TSIGKey. The actual key can be generated by the server or be provided by the client'
 746       operationId: createTSIGKey
 747       tags:
 748         - tsigkey
 749       parameters:
 750         - name: tsigkey
 751           description: The TSIGKey to add
 752           required: true
 753           in: body
 754           schema:
 755             $ref: '#/definitions/TSIGKey'
 756       responses:
 757         '201':
 758           description: Created
 759           schema:
 760             $ref: '#/definitions/TSIGKey'
 761         '409':
 762           description: 'Conflict. A key with this name already exists'
 763           schema:
 764             $ref: '#/definitions/Error'
 765         '422':
 766           description: 'Unprocessable Entry, the TSIGKey provided has issues.'
 767           schema:
 768             $ref: '#/definitions/Error'
 769         '500':
 770           description: 'Internal Server Error. There was a problem creating the key'
 771           schema:
 772             $ref: '#/definitions/Error'
 773
 774   '/servers/{server_id}/tsigkeys/{tsigkey_id}':
 775     parameters:
 776       - name: server_id
 777         in: path
 778         required: true
 779         description: 'The id of the server to retrieve the key from'
 780         type: string
 781       - name: tsigkey_id
 782         in: path
 783         required: true
 784         description: 'The id of the TSIGkey. Should match the "id" field in the TSIGKey object'
 785         type: string
 786     get:
 787       summary: 'Get a specific TSIGKeys on the server, including the actual key'
 788       operationId: getTSIGKey
 789       tags:
 790         - tsigkey
 791       responses:
 792         '200':
 793           description: OK.
 794           schema:
 795             $ref: '#/definitions/TSIGKey'
 796         '404':
 797           description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
 798           schema:
 799             $ref: '#/definitions/Error'
 800         '500':
 801           description: 'Internal Server Error, keys could not be retrieved. Contains error message'
 802           schema:
 803             $ref: '#/definitions/Error'
 804     put:
 805       description: |
 806         The TSIGKey at tsigkey_id can be changed in multiple ways:
 807          * Changing the Name, this will remove the key with tsigkey_id after adding.
 808          * Changing the Algorithm
 809          * Changing the Key
 810         Only the relevant fields have to be provided in the request body.
 811       operationId: putTSIGKey
 812       tags:
 813         - tsigkey
 814       parameters:
 815         - name: tsigkey
 816           description: A (possibly stripped down) TSIGKey object with the new values
 817           properties:
 818             $ref: '#/definitions/TSIGKey'
 819           in: body
 820           required: true
 821       responses:
 822         '200':
 823           description: OK. TSIGKey is changed.
 824           schema:
 825             $ref: '#/definitions/TSIGKey'
 826         '404':
 827           description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
 828           schema:
 829             $ref: '#/definitions/Error'
 830         '500':
 831           description: 'Internal Server Error. Contains error message'
 832           schema:
 833             $ref: '#/definitions/Error'
 834     delete:
 835       summary: 'Delete the TSIGKey with tsigkey_id'
 836       operationId: deleteTSIGKey
 837       tags:
 838         - tsigkey
 839       responses:
 840         '204':
 841           description: 'OK, key was deleted'
 842         '404':
 843           description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
 844           schema:
 845             $ref: '#/definitions/Error'
 846         '500':
 847           description: 'Internal Server Error. Contains error message'
 848           schema:
 849             $ref: '#/definitions/Error'
 850
 851 definitions:
 852   Server:
 853     title: Server
 854     properties:
 855       type:
 856         type: string
 857         description: 'Set to “Server”'
 858       id:
 859         type: string
 860         description: 'The id of the server, “localhost”'
 861       daemon_type:
 862         type: string
 863         description: '“recursor” for the PowerDNS Recursor and “authoritative” for the Authoritative Server'
 864       version:
 865         type: string
 866         description: 'The version of the server software'
 867       url:
 868         type: string
 869         description: 'The API endpoint for this server'
 870       config_url:
 871         type: string
 872         description: 'The API endpoint for this server’s configuration'
 873       zones_url:
 874         type: string
 875         description: 'The API endpoint for this server’s zones'
 876
 877   Servers:
 878     type: array
 879     items:
 880       $ref: '#/definitions/Server'
 881
 882   Zone:
 883     title: Zone
 884     description: This represents an authoritative DNS Zone.
 885     properties:
 886       id:
 887         type: string
 888         description: 'Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs.'
 889       name:
 890         type: string
 891         description: 'Name of the zone (e.g. “example.com.”) MUST have a trailing dot'
 892       type:
 893         type: string
 894         description: 'Set to “Zone”'
 895       url:
 896         type: string
 897         description: 'API endpoint for this zone'
 898       kind:
 899         type: string
 900         enum:
 901           - 'Native'
 902           - 'Master'
 903           - 'Slave'
 904         description: 'Zone kind, one of “Native”, “Master”, “Slave”'
 905       rrsets:
 906         type: array
 907         items:
 908           $ref: '#/definitions/RRSet'
 909         description: 'RRSets in this zone'
 910       serial:
 911         type: integer
 912         description: 'The SOA serial number'
 913       notified_serial:
 914         type: integer
 915         description: 'The SOA serial notifications have been sent out for'
 916       masters:
 917         type: array
 918         items:
 919           type: string
 920         description: ' List of IP addresses configured as a master for this zone (“Slave” type zones only)'
 921       dnssec:
 922         type: boolean
 923         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)'
 924       nsec3param:
 925         type: string
 926         description: 'The NSEC3PARAM record'
 927       nsec3narrow:
 928         type: boolean
 929         description: 'Whether or not the zone uses NSEC3 narrow'
 930       presigned:
 931         type: boolean
 932         description: 'Whether or not the zone is pre-signed'
 933       soa_edit:
 934         type: string
 935         description: 'The SOA-EDIT metadata item'
 936       soa_edit_api:
 937         type: string
 938         description: 'The SOA-EDIT-API metadata item'
 939       api_rectify:
 940         type: boolean
 941         description: ' Whether or not the zone will be rectified on data changes via the API'
 942       zone:
 943         type: string
 944         description: 'MAY contain a BIND-style zone file when creating a zone'
 945       account:
 946         type: string
 947         description: 'MAY be set. Its value is defined by local policy'
 948       nameservers:
 949         type: array
 950         items:
 951           type: string
 952         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.'
 953       tsig_master_key_ids:
 954         type: array
 955         items:
 956           type: string
 957         description: 'The id of the TSIG keys used for master operation in this zone'
 958         externalDocs:
 959           url: 'https://doc.powerdns.com/authoritative/tsig.html#provisioning-outbound-axfr-access'
 960       tsig_slave_key_ids:
 961         type: array
 962         items:
 963           type: string
 964         description: 'The id of the TSIG keys used for slave operation in this zone'
 965         externalDocs:
 966           url: 'https://doc.powerdns.com/authoritative/tsig.html#provisioning-signed-notification-and-axfr-requests'
 967
 968   Zones:
 969     type: array
 970     items:
 971       $ref: '#/definitions/Zone'
 972
 973   RRSet:
 974     title: RRSet
 975     description: This represents a Resource Record Set (all records with the same name and type).
 976     required:
 977       - name
 978       - type
 979       - ttl
 980       - changetype
 981       - records
 982     properties:
 983       name:
 984         type: string
 985         description: 'Name for record set (e.g. “www.powerdns.com.”)'
 986       type:
 987         type: string
 988         description: 'Type of this record (e.g. “A”, “PTR”, “MX”)'
 989       ttl:
 990         type: integer
 991         description: 'DNS TTL of the records, in seconds. MUST NOT be included when changetype is set to “DELETE”.'
 992       changetype:
 993         type: string
 994         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.'
 995       records:
 996         type: array
 997         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).'
 998         items:
 999           $ref: '#/definitions/Record'
1000       comments:
1001         type: array
1002         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.'
1003         items:
1004           $ref: '#/definitions/Comment'
1005
1006   Record:
1007     title: Record
1008     description: The RREntry object represents a single record.
1009     required:
1010       - content
1011       - disabled # PatchZone endpoint complains if this is missing
1012     properties:
1013       content:
1014         type: string
1015         description: 'The content of this record'
1016       disabled:
1017         type: boolean
1018         description: 'Whether or not this record is disabled'
1019       set-ptr:
1020         type: boolean
1021         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.'
1022
1023   Comment:
1024     title: Comment
1025     description: A comment about an RRSet.
1026     properties:
1027       content:
1028         type: string
1029         description: 'The actual comment'
1030       account:
1031         type: string
1032         description: 'Name of an account that added the comment'
1033       modified_at:
1034         type: integer
1035         description: 'Timestamp of the last change to the comment'
1036
1037   TSIGKey:
1038     title: TSIGKey
1039     description: A TSIG key that can be used to authenticate NOTIFYs and AXFRs
1040     properties:
1041       name:
1042         type: string
1043         description: 'The name of the key'
1044       id:
1045         type: string
1046         description: 'The ID for this key, used in the TSIGkey URL endpoint.'
1047         readOnly: true
1048       algorithm:
1049         type: string
1050         description: 'The algorithm of the TSIG key'
1051       key:
1052         type: string
1053         description: 'The Base64 encoded secret key, empty when listing keys. MAY be empty when POSTing to have the server generate the key material'
1054       type:
1055         type: string
1056         description: 'Set to "TSIGKey"'
1057         readOnly: true
1058
1059   ConfigSetting:
1060     title: ConfigSetting
1061     properties:
1062       name:
1063         type: string
1064         description: 'set to "ConfigSetting"'
1065       type:
1066         type: string
1067         description: 'The name of this setting (e.g. ‘webserver-port’)'
1068       value:
1069         type: string
1070         description: 'The value of setting name'
1071
1072   BaseStatisticItem:
1073     title: BaseStatisticItem
1074     properties:
1075       name:
1076         type: string
1077         description: 'The name of this item (e.g. ‘uptime’)'
1078
1079   StatisticItem:
1080     title: StatisticItem
1081     allOf:
1082     - $ref: "#/definitions/BaseStatisticItem"
1083     - properties:
1084         type:
1085           enum: [StatisticItem]
1086           description: 'set to "StatisticItem"'
1087         value:
1088           type: string
1089           description: 'The value of item'
1090
1091   MapStatisticItem:
1092     title: MapStatisticItem
1093     allOf:
1094     - $ref: "#/definitions/BaseStatisticItem"
1095     - properties:
1096         type:
1097           enum: [MapStatisticItem]
1098           description: 'set to "MapStatisticItem"'
1099         value:
1100           type: array
1101           description: 'named statistic values'
1102           items:
1103             type: array
1104             properties:
1105               name:
1106                 type: string
1107                 description: 'item name'
1108               value:
1109                 type: string
1110                 description: 'item value'
1111
1112   RingStatisticItem:
1113     title: RingStatisticItem
1114     allOf:
1115     - $ref: "#/definitions/BaseStatisticItem"
1116     - properties:
1117         type:
1118           enum: [RingStatisticItem]
1119           description: 'set to "RingStatisticItem"'
1120         size:
1121           type: integer
1122           description: 'for RingStatisticItem objects, the size of the ring'
1123         value:
1124           type: array
1125           description: 'named ring statistic values'
1126           items:
1127             type: array
1128             properties:
1129               name:
1130                 type: string
1131                 description: 'item name'
1132               value:
1133                 type: string
1134                 description: 'item value'
1135
1136   SearchResultZone:
1137     title: SearchResultZone
1138     properties:
1139       name:
1140         type: string
1141       object_type:
1142         type: string
1143         description: 'set to "zone"'
1144       zone_id:
1145         type: string
1146
1147   SearchResultRecord:
1148     title: SearchResultRecord
1149     properties:
1150       content:
1151         type: string
1152       disabled:
1153         type: boolean
1154       name:
1155         type: string
1156       object_type:
1157         type: string
1158         description: 'set to "record"'
1159       zone_id:
1160         type: string
1161       zone:
1162         type: string
1163       type:
1164         type: string
1165       ttl:
1166         type: integer
1167
1168   SearchResultComment:
1169     title: SearchResultComment
1170     properties:
1171       content:
1172         type: string
1173       name:
1174         type: string
1175       object_type:
1176         type: string
1177         description: 'set to "comment"'
1178       zone_id:
1179         type: string
1180       zone:
1181         type: string
1182
1183 # FIXME: This is problematic at the moment, because swagger doesn't support this type of mixed response
1184 #  SearchResult:
1185 #    anyOf:
1186 #      - $ref: '#/definitions/SearchResultZone'
1187 #      - $ref: '#/definitions/SearchResultRecord'
1188 #      - $ref: '#/definitions/SearchResultComment'
1189
1190 # Since we can't do 'anyOf' at the moment, we create a 'superset object'
1191   SearchResult:
1192     title: SearchResult
1193     properties:
1194       content:
1195         type: string
1196       disabled:
1197         type: boolean
1198       name:
1199         type: string
1200       object_type:
1201         type: string
1202         description: 'set to one of "record, zone, comment"'
1203       zone_id:
1204         type: string
1205       zone:
1206         type: string
1207       type:
1208         type: string
1209       ttl:
1210         type: integer
1211
1212   SearchResults:
1213     type: array
1214     items:
1215       $ref: '#/definitions/SearchResult'
1216
1217   Metadata:
1218     title: Metadata
1219     description: Represents zone metadata
1220     properties:
1221       kind:
1222         type: string
1223         description: 'Name of the metadata'
1224       metadata:
1225         type: array
1226         items:
1227           type: string
1228         description: 'Array with all values for this metadata kind.'
1229
1230   Cryptokey:
1231     title: Cryptokey
1232     description: 'Describes a DNSSEC cryptographic key'
1233     properties:
1234       type:
1235         type: string
1236         description: 'set to "Cryptokey"'
1237       id:
1238         type: string
1239         description: 'The internal identifier, read only'
1240       keytype:
1241         type: string
1242         enum: [ksk, zsk, csk]
1243       active:
1244         type: boolean
1245         description: 'Whether or not the key is in active use'
1246       dnskey:
1247         type: string
1248         description: 'The DNSKEY record for this key'
1249       ds:
1250         type: array
1251         items:
1252           type: string
1253         description: 'An array of DS records for this key'
1254       privatekey:
1255         type: string
1256         description: 'The private key in ISC format'
1257       algorithm:
1258         type: string
1259         description: 'The name of the algorithm of the key, should be a mnemonic'
1260       bits:
1261         type: integer
1262         description: 'The size of the key'
1263
1264   Error:
1265     title: Error
1266     descripton: 'Returned when the server encounters an error. Either in client input or internally'
1267     properties:
1268       error:
1269         type: string
1270         description: 'A human readable error message'
1271         required: true
1272       errors:
1273         type: array
1274         items:
1275           type: string
1276         description: 'Optional array of multiple errors encountered during processing'
1277
1278   CacheFlushResult:
1279     title: CacheFlushResult
1280     description: 'The result of a cache-flush'
1281     properties:
1282       count:
1283         type: number
1284         description: 'Amount of entries flushed'
1285       result:
1286         type: string
1287         description: 'A message about the result like "Flushed cache"'