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