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.'
 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         - name: statistic
 403           in: query
 404           required: false
 405           type: string
 406           description: |
 407             When set to the name of a specific statistic, only this value is returned.
 408             If no statistic with that name exists, the response has a 422 status and an error message.
 409
 410       responses:
 411         '200':
 412           description: List of Statistic Items
 413           schema:
 414             type: array
 415             items:
 416             - $ref: '#/definitions/StatisticItem'
 417             - $ref: '#/definitions/MapStatisticItem'
 418             - $ref: '#/definitions/RingStatisticItem'
 419         '422':
 420           description: 'Returned when a non-existing statistic name has been requested. Contains an error message'
 421
 422   '/servers/{server_id}/search-data':
 423     get:
 424       summary: 'Search the data inside PowerDNS'
 425       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.'
 426       operationId: searchData
 427       tags:
 428         - search
 429       parameters:
 430         - name: server_id
 431           in: path
 432           required: true
 433           description: The id of the server to retrieve
 434           type: string
 435         - name: q
 436           in: query
 437           required: true
 438           description: 'The string to search for'
 439           type: string
 440         - name: max
 441           in: query
 442           required: true
 443           description: 'Maximum number of entries to return'
 444           type: integer
 445         - name: object_type
 446           in: query
 447           required: false
 448           description: 'Type of data to search for, one of “all”, “zone”, “record”, “comment”'
 449           type: string
 450       responses:
 451         '200':
 452           description: Returns a JSON array with results
 453           schema:
 454             $ref: '#/definitions/SearchResults'
 455
 456   '/servers/{server_id}/zones/{zone_id}/metadata':
 457     get:
 458       summary: Get all the MetaData associated with the zone.
 459       operationId: listMetadata
 460       tags:
 461         - zonemetadata
 462       parameters:
 463         - name: server_id
 464           in: path
 465           required: true
 466           description: The id of the server to retrieve
 467           type: string
 468         - name: zone_id
 469           type: string
 470           in: path
 471           required: true
 472           description: The id of the zone to retrieve
 473       responses:
 474         '200':
 475           description: List of Metadata objects
 476           schema:
 477             type: array
 478             items:
 479               $ref: '#/definitions/Metadata'
 480     post:
 481       summary: 'Creates a set of metadata entries'
 482       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.'
 483       operationId: createMetadata
 484       tags:
 485         - zonemetadata
 486       parameters:
 487         - name: server_id
 488           in: path
 489           required: true
 490           description: The id of the server to retrieve
 491           type: string
 492         - name: zone_id
 493           type: string
 494           in: path
 495           required: true
 496         - name: metadata
 497           description: List of metadata to add/create
 498           required: true
 499           in: body
 500           schema:
 501             type: array
 502             items:
 503               $ref: '#/definitions/Metadata'
 504       responses:
 505         '204':
 506           description: OK
 507
 508   '/servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}':
 509     get:
 510       summary: Get the content of a single kind of domain metadata as a list of MetaData objects.
 511       operationId: getMetadata
 512       tags:
 513         - zonemetadata
 514       parameters:
 515         - name: server_id
 516           in: path
 517           required: true
 518           description: The id of the server to retrieve
 519           type: string
 520         - name: zone_id
 521           type: string
 522           in: path
 523           required: true
 524           description: The id of the zone to retrieve
 525         - name: metadata_kind
 526           type: string
 527           in: path
 528           required: true
 529           description: '???'
 530       responses:
 531         '200':
 532           description: List of Metadata objects
 533           schema:
 534             $ref: '#/definitions/Metadata'
 535     put:
 536       summary: 'Modify the content of a single kind of domain metadata.'
 537       operationId: modifyMetadata
 538       tags:
 539         - zonemetadata
 540       parameters:
 541         - name: server_id
 542           in: path
 543           required: true
 544           description: The id of the server to retrieve
 545           type: string
 546         - name: zone_id
 547           type: string
 548           in: path
 549           required: true
 550         - name: metadata_kind
 551           description: The kind of metadata
 552           required: true
 553           type: string
 554           in: path
 555         - name: metadata
 556           description: metadata to add/create
 557           required: true
 558           in: body
 559           schema:
 560             $ref: '#/definitions/Metadata'
 561       responses:
 562         '204':
 563           description: OK
 564     delete:
 565       summary: 'Delete all items of a single kind of domain metadata.'
 566       operationId: deleteMetadata
 567       tags:
 568         - zonemetadata
 569       parameters:
 570         - name: server_id
 571           in: path
 572           required: true
 573           description: The id of the server to retrieve
 574           type: string
 575         - name: zone_id
 576           type: string
 577           in: path
 578           required: true
 579           description: The id of the zone to retrieve
 580         - name: metadata_kind
 581           type: string
 582           in: path
 583           required: true
 584           description: '???'
 585       responses:
 586         '204':
 587           description: OK
 588
 589   '/servers/{server_id}/zones/{zone_id}/cryptokeys':
 590     get:
 591       summary: 'Get all CryptoKeys for a zone, except the privatekey'
 592       operationId: listCryptokeys
 593       tags:
 594         - zonecryptokey
 595       parameters:
 596         - name: server_id
 597           in: path
 598           required: true
 599           description: The id of the server to retrieve
 600           type: string
 601         - name: zone_id
 602           type: string
 603           in: path
 604           required: true
 605           description: The id of the zone to retrieve
 606       responses:
 607         '200':
 608           description: List of Cryptokey objects
 609           schema:
 610             type: array
 611             items:
 612               $ref: '#/definitions/Cryptokey'
 613     post:
 614       summary: 'Creates a Cryptokey'
 615       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.'
 616       operationId: createCryptokey
 617       tags:
 618         - zonecryptokey
 619       parameters:
 620         - name: server_id
 621           in: path
 622           required: true
 623           description: The id of the server to retrieve
 624           type: string
 625         - name: zone_id
 626           type: string
 627           in: path
 628           required: true
 629         - name: cryptokey
 630           description: Add a Cryptokey
 631           required: true
 632           in: body
 633           schema:
 634             $ref: '#/definitions/Cryptokey'
 635       responses:
 636         '201':
 637           description: Created
 638           schema:
 639             $ref: '#/definitions/Cryptokey'
 640
 641   '/servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}':
 642     get:
 643       summary: 'Returns all data about the CryptoKey, including the privatekey.'
 644       operationId: getCryptokey
 645       tags:
 646         - zonecryptokey
 647       parameters:
 648         - name: server_id
 649           in: path
 650           required: true
 651           description: The id of the server to retrieve
 652           type: string
 653         - name: zone_id
 654           type: string
 655           in: path
 656           required: true
 657           description: The id of the zone to retrieve
 658         - name: cryptokey_id
 659           type: string
 660           in: path
 661           required: true
 662           description: 'The id value of the CryptoKey'
 663       responses:
 664         '200':
 665           description: Cryptokey
 666           schema:
 667             $ref: '#/definitions/Cryptokey'
 668     put:
 669       summary: 'This method (de)activates a key from zone_name specified by cryptokey_id'
 670       operationId: modifyCryptokey
 671       tags:
 672         - zonecryptokey
 673       parameters:
 674         - name: server_id
 675           in: path
 676           required: true
 677           description: The id of the server to retrieve
 678           type: string
 679         - name: zone_id
 680           type: string
 681           in: path
 682           required: true
 683         - name: cryptokey_id
 684           description: Cryptokey to manipulate
 685           required: true
 686           in: path
 687           type: string
 688         - name: cryptokey
 689           description: the Cryptokey
 690           required: true
 691           in: body
 692           schema:
 693             $ref: '#/definitions/Cryptokey'
 694       responses:
 695         '204':
 696           description: OK
 697         '422':
 698           description: 'Returned when something is wrong with the content of the request. Contains an error message'
 699     delete:
 700       summary: 'This method deletes a key specified by cryptokey_id.'
 701       operationId: deleteCryptokey
 702       tags:
 703         - zonecryptokey
 704       parameters:
 705         - name: server_id
 706           in: path
 707           required: true
 708           description: The id of the server to retrieve
 709           type: string
 710         - name: zone_id
 711           type: string
 712           in: path
 713           required: true
 714           description: The id of the zone to retrieve
 715         - name: cryptokey_id
 716           type: string
 717           in: path
 718           required: true
 719           description: 'The id value of the Cryptokey'
 720       responses:
 721         '204':
 722           description: OK
 723         '422':
 724           description: 'Returned when something is wrong with the content of the request. Contains an error message'
 725
 726   '/servers/{server_id}/tsigkeys':
 727     parameters:
 728       - name: server_id
 729         in: path
 730         required: true
 731         description: 'The id of the server'
 732         type: string
 733     get:
 734       summary: 'Get all TSIGKeys on the server, except the actual key'
 735       operationId: listTSIGKeys
 736       tags:
 737         - tsigkey
 738       responses:
 739         '200':
 740           description: List of TSIGKey objects
 741           schema:
 742             type: array
 743             items:
 744               $ref: '#/definitions/TSIGKey'
 745         '500':
 746           description: 'Internal Server Error, keys could not be retrieved. Contains error message'
 747           schema:
 748             $ref: '#/definitions/Error'
 749     post:
 750       summary: 'Add a TSIG key'
 751       description: 'This methods add a new TSIGKey. The actual key can be generated by the server or be provided by the client'
 752       operationId: createTSIGKey
 753       tags:
 754         - tsigkey
 755       parameters:
 756         - name: tsigkey
 757           description: The TSIGKey to add
 758           required: true
 759           in: body
 760           schema:
 761             $ref: '#/definitions/TSIGKey'
 762       responses:
 763         '201':
 764           description: Created
 765           schema:
 766             $ref: '#/definitions/TSIGKey'
 767         '409':
 768           description: 'Conflict. A key with this name already exists'
 769           schema:
 770             $ref: '#/definitions/Error'
 771         '422':
 772           description: 'Unprocessable Entry, the TSIGKey provided has issues.'
 773           schema:
 774             $ref: '#/definitions/Error'
 775         '500':
 776           description: 'Internal Server Error. There was a problem creating the key'
 777           schema:
 778             $ref: '#/definitions/Error'
 779
 780   '/servers/{server_id}/tsigkeys/{tsigkey_id}':
 781     parameters:
 782       - name: server_id
 783         in: path
 784         required: true
 785         description: 'The id of the server to retrieve the key from'
 786         type: string
 787       - name: tsigkey_id
 788         in: path
 789         required: true
 790         description: 'The id of the TSIGkey. Should match the "id" field in the TSIGKey object'
 791         type: string
 792     get:
 793       summary: 'Get a specific TSIGKeys on the server, including the actual key'
 794       operationId: getTSIGKey
 795       tags:
 796         - tsigkey
 797       responses:
 798         '200':
 799           description: OK.
 800           schema:
 801             $ref: '#/definitions/TSIGKey'
 802         '404':
 803           description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
 804           schema:
 805             $ref: '#/definitions/Error'
 806         '500':
 807           description: 'Internal Server Error, keys could not be retrieved. Contains error message'
 808           schema:
 809             $ref: '#/definitions/Error'
 810     put:
 811       description: |
 812         The TSIGKey at tsigkey_id can be changed in multiple ways:
 813          * Changing the Name, this will remove the key with tsigkey_id after adding.
 814          * Changing the Algorithm
 815          * Changing the Key
 816         Only the relevant fields have to be provided in the request body.
 817       operationId: putTSIGKey
 818       tags:
 819         - tsigkey
 820       parameters:
 821         - name: tsigkey
 822           description: A (possibly stripped down) TSIGKey object with the new values
 823           schema:
 824             $ref: '#/definitions/TSIGKey'
 825           in: body
 826           required: true
 827       responses:
 828         '200':
 829           description: OK. TSIGKey is changed.
 830           schema:
 831             $ref: '#/definitions/TSIGKey'
 832         '404':
 833           description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
 834           schema:
 835             $ref: '#/definitions/Error'
 836         '500':
 837           description: 'Internal Server Error. Contains error message'
 838           schema:
 839             $ref: '#/definitions/Error'
 840     delete:
 841       summary: 'Delete the TSIGKey with tsigkey_id'
 842       operationId: deleteTSIGKey
 843       tags:
 844         - tsigkey
 845       responses:
 846         '204':
 847           description: 'OK, key was deleted'
 848         '404':
 849           description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist'
 850           schema:
 851             $ref: '#/definitions/Error'
 852         '500':
 853           description: 'Internal Server Error. Contains error message'
 854           schema:
 855             $ref: '#/definitions/Error'
 856
 857 definitions:
 858   Server:
 859     title: Server
 860     properties:
 861       type:
 862         type: string
 863         description: 'Set to “Server”'
 864       id:
 865         type: string
 866         description: 'The id of the server, “localhost”'
 867       daemon_type:
 868         type: string
 869         description: '“recursor” for the PowerDNS Recursor and “authoritative” for the Authoritative Server'
 870       version:
 871         type: string
 872         description: 'The version of the server software'
 873       url:
 874         type: string
 875         description: 'The API endpoint for this server'
 876       config_url:
 877         type: string
 878         description: 'The API endpoint for this server’s configuration'
 879       zones_url:
 880         type: string
 881         description: 'The API endpoint for this server’s zones'
 882
 883   Servers:
 884     type: array
 885     items:
 886       $ref: '#/definitions/Server'
 887
 888   Zone:
 889     title: Zone
 890     description: This represents an authoritative DNS Zone.
 891     properties:
 892       id:
 893         type: string
 894         description: 'Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs.'
 895       name:
 896         type: string
 897         description: 'Name of the zone (e.g. “example.com.”) MUST have a trailing dot'
 898       type:
 899         type: string
 900         description: 'Set to “Zone”'
 901       url:
 902         type: string
 903         description: 'API endpoint for this zone'
 904       kind:
 905         type: string
 906         enum:
 907           - 'Native'
 908           - 'Master'
 909           - 'Slave'
 910         description: 'Zone kind, one of “Native”, “Master”, “Slave”'
 911       rrsets:
 912         type: array
 913         items:
 914           $ref: '#/definitions/RRSet'
 915         description: 'RRSets in this zone'
 916       serial:
 917         type: integer
 918         description: 'The SOA serial number'
 919       notified_serial:
 920         type: integer
 921         description: 'The SOA serial notifications have been sent out for'
 922       masters:
 923         type: array
 924         items:
 925           type: string
 926         description: ' List of IP addresses configured as a master for this zone (“Slave” type zones only)'
 927       dnssec:
 928         type: boolean
 929         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)'
 930       nsec3param:
 931         type: string
 932         description: 'The NSEC3PARAM record'
 933       nsec3narrow:
 934         type: boolean
 935         description: 'Whether or not the zone uses NSEC3 narrow'
 936       presigned:
 937         type: boolean
 938         description: 'Whether or not the zone is pre-signed'
 939       soa_edit:
 940         type: string
 941         description: 'The SOA-EDIT metadata item'
 942       soa_edit_api:
 943         type: string
 944         description: 'The SOA-EDIT-API metadata item'
 945       api_rectify:
 946         type: boolean
 947         description: ' Whether or not the zone will be rectified on data changes via the API'
 948       zone:
 949         type: string
 950         description: 'MAY contain a BIND-style zone file when creating a zone'
 951       account:
 952         type: string
 953         description: 'MAY be set. Its value is defined by local policy'
 954       nameservers:
 955         type: array
 956         items:
 957           type: string
 958         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.'
 959       master_tsig_key_ids:
 960         type: array
 961         items:
 962           type: string
 963         description: 'The id of the TSIG keys used for master operation in this zone'
 964         externalDocs:
 965           url: 'https://doc.powerdns.com/authoritative/tsig.html#provisioning-outbound-axfr-access'
 966       slave_tsig_key_ids:
 967         type: array
 968         items:
 969           type: string
 970         description: 'The id of the TSIG keys used for slave operation in this zone'
 971         externalDocs:
 972           url: 'https://doc.powerdns.com/authoritative/tsig.html#provisioning-signed-notification-and-axfr-requests'
 973
 974   Zones:
 975     type: array
 976     items:
 977       $ref: '#/definitions/Zone'
 978
 979   RRSet:
 980     title: RRSet
 981     description: This represents a Resource Record Set (all records with the same name and type).
 982     required:
 983       - name
 984       - type
 985       - ttl
 986       - changetype
 987       - records
 988     properties:
 989       name:
 990         type: string
 991         description: 'Name for record set (e.g. “www.powerdns.com.”)'
 992       type:
 993         type: string
 994         description: 'Type of this record (e.g. “A”, “PTR”, “MX”)'
 995       ttl:
 996         type: integer
 997         description: 'DNS TTL of the records, in seconds. MUST NOT be included when changetype is set to “DELETE”.'
 998       changetype:
 999         type: string
1000         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.'
1001       records:
1002         type: array
1003         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).'
1004         items:
1005           $ref: '#/definitions/Record'
1006       comments:
1007         type: array
1008         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.'
1009         items:
1010           $ref: '#/definitions/Comment'
1011
1012   Record:
1013     title: Record
1014     description: The RREntry object represents a single record.
1015     required:
1016       - content
1017       - disabled # PatchZone endpoint complains if this is missing
1018     properties:
1019       content:
1020         type: string
1021         description: 'The content of this record'
1022       disabled:
1023         type: boolean
1024         description: 'Whether or not this record is disabled'
1025       set-ptr:
1026         type: boolean
1027         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.'
1028
1029   Comment:
1030     title: Comment
1031     description: A comment about an RRSet.
1032     properties:
1033       content:
1034         type: string
1035         description: 'The actual comment'
1036       account:
1037         type: string
1038         description: 'Name of an account that added the comment'
1039       modified_at:
1040         type: integer
1041         description: 'Timestamp of the last change to the comment'
1042
1043   TSIGKey:
1044     title: TSIGKey
1045     description: A TSIG key that can be used to authenticate NOTIFYs and AXFRs
1046     properties:
1047       name:
1048         type: string
1049         description: 'The name of the key'
1050       id:
1051         type: string
1052         description: 'The ID for this key, used in the TSIGkey URL endpoint.'
1053         readOnly: true
1054       algorithm:
1055         type: string
1056         description: 'The algorithm of the TSIG key'
1057       key:
1058         type: string
1059         description: 'The Base64 encoded secret key, empty when listing keys. MAY be empty when POSTing to have the server generate the key material'
1060       type:
1061         type: string
1062         description: 'Set to "TSIGKey"'
1063         readOnly: true
1064
1065   ConfigSetting:
1066     title: ConfigSetting
1067     properties:
1068       name:
1069         type: string
1070         description: 'set to "ConfigSetting"'
1071       type:
1072         type: string
1073         description: 'The name of this setting (e.g. ‘webserver-port’)'
1074       value:
1075         type: string
1076         description: 'The value of setting name'
1077
1078   SimpleStatisticItem:
1079     title: SimpleStatisticItem
1080     type: object
1081     properties:
1082       name:
1083           type: string
1084           description: 'Item name'
1085       value:
1086           type: string
1087           description: 'Item value'
1088
1089   StatisticItem:
1090     title: StatisticItem
1091     properties:
1092       name:
1093         type: string
1094         description: 'Item name'
1095       type:
1096         type: string
1097         description: 'set to "StatisticItem"'
1098       value:
1099         type: string
1100         description: 'Item value'
1101
1102   MapStatisticItem:
1103     title: MapStatisticItem
1104     properties:
1105       name:
1106         type: string
1107         description: 'Item name'
1108       type:
1109         type: string
1110         description: 'Set to "MapStatisticItem"'
1111       value:
1112         type: array
1113         description: 'Named values'
1114         items:
1115           $ref: '#/definitions/SimpleStatisticItem'
1116
1117   RingStatisticItem:
1118     title: RingStatisticItem
1119     properties:
1120       name:
1121         type: string
1122         description: 'Item name'
1123       type:
1124         type: string
1125         description: 'Set to "RingStatisticItem"'
1126       size:
1127         type: integer
1128         description: 'Ring size'
1129       value:
1130         type: array
1131         description: 'Named values'
1132         items:
1133           $ref: '#/definitions/SimpleStatisticItem'
1134
1135   SearchResultZone:
1136     title: SearchResultZone
1137     properties:
1138       name:
1139         type: string
1140       object_type:
1141         type: string
1142         description: 'set to "zone"'
1143       zone_id:
1144         type: string
1145
1146   SearchResultRecord:
1147     title: SearchResultRecord
1148     properties:
1149       content:
1150         type: string
1151       disabled:
1152         type: boolean
1153       name:
1154         type: string
1155       object_type:
1156         type: string
1157         description: 'set to "record"'
1158       zone_id:
1159         type: string
1160       zone:
1161         type: string
1162       type:
1163         type: string
1164       ttl:
1165         type: integer
1166
1167   SearchResultComment:
1168     title: SearchResultComment
1169     properties:
1170       content:
1171         type: string
1172       name:
1173         type: string
1174       object_type:
1175         type: string
1176         description: 'set to "comment"'
1177       zone_id:
1178         type: string
1179       zone:
1180         type: string
1181
1182 # FIXME: This is problematic at the moment, because swagger doesn't support this type of mixed response
1183 #  SearchResult:
1184 #    anyOf:
1185 #      - $ref: '#/definitions/SearchResultZone'
1186 #      - $ref: '#/definitions/SearchResultRecord'
1187 #      - $ref: '#/definitions/SearchResultComment'
1188
1189 # Since we can't do 'anyOf' at the moment, we create a 'superset object'
1190   SearchResult:
1191     title: SearchResult
1192     properties:
1193       content:
1194         type: string
1195       disabled:
1196         type: boolean
1197       name:
1198         type: string
1199       object_type:
1200         type: string
1201         description: 'set to one of "record, zone, comment"'
1202       zone_id:
1203         type: string
1204       zone:
1205         type: string
1206       type:
1207         type: string
1208       ttl:
1209         type: integer
1210
1211   SearchResults:
1212     type: array
1213     items:
1214       $ref: '#/definitions/SearchResult'
1215
1216   Metadata:
1217     title: Metadata
1218     description: Represents zone metadata
1219     properties:
1220       kind:
1221         type: string
1222         description: 'Name of the metadata'
1223       metadata:
1224         type: array
1225         items:
1226           type: string
1227         description: 'Array with all values for this metadata kind.'
1228
1229   Cryptokey:
1230     title: Cryptokey
1231     description: 'Describes a DNSSEC cryptographic key'
1232     properties:
1233       type:
1234         type: string
1235         description: 'set to "Cryptokey"'
1236       id:
1237         type: string
1238         description: 'The internal identifier, read only'
1239       keytype:
1240         type: string
1241         enum: [ksk, zsk, csk]
1242       active:
1243         type: boolean
1244         description: 'Whether or not the key is in active use'
1245       dnskey:
1246         type: string
1247         description: 'The DNSKEY record for this key'
1248       ds:
1249         type: array
1250         items:
1251           type: string
1252         description: 'An array of DS records for this key'
1253       privatekey:
1254         type: string
1255         description: 'The private key in ISC format'
1256       algorithm:
1257         type: string
1258         description: 'The name of the algorithm of the key, should be a mnemonic'
1259       bits:
1260         type: integer
1261         description: 'The size of the key'
1262
1263   Error:
1264     title: Error
1265     description: 'Returned when the server encounters an error. Either in client input or internally'
1266     properties:
1267       error:
1268         type: string
1269         description: 'A human readable error message'
1270       errors:
1271         type: array
1272         items:
1273           type: string
1274         description: 'Optional array of multiple errors encountered during processing'
1275     required:
1276       - error
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"'