View Javadoc
1   /*
2    * Copyright 2019-2020 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.bremersee.dccon.api;
18  
19  import io.swagger.v3.oas.annotations.Operation;
20  import io.swagger.v3.oas.annotations.Parameter;
21  import io.swagger.v3.oas.annotations.media.ArraySchema;
22  import io.swagger.v3.oas.annotations.media.Content;
23  import io.swagger.v3.oas.annotations.media.Schema;
24  import io.swagger.v3.oas.annotations.responses.ApiResponse;
25  import io.swagger.v3.oas.annotations.responses.ApiResponses;
26  import io.swagger.v3.oas.annotations.tags.Tag;
27  import java.util.List;
28  import javax.validation.Valid;
29  import org.bremersee.dccon.model.DhcpLease;
30  import org.bremersee.dccon.model.DnsNode;
31  import org.bremersee.dccon.model.DnsZone;
32  import org.bremersee.dccon.model.UnknownFilter;
33  import org.bremersee.exception.model.RestApiException;
34  import org.springframework.http.ResponseEntity;
35  import org.springframework.validation.annotation.Validated;
36  import org.springframework.web.bind.annotation.PathVariable;
37  import org.springframework.web.bind.annotation.RequestBody;
38  import org.springframework.web.bind.annotation.RequestMapping;
39  import org.springframework.web.bind.annotation.RequestMethod;
40  import org.springframework.web.bind.annotation.RequestParam;
41  
42  /**
43   * The name server management api.
44   *
45   * @author Christian Bremer
46   */
47  @Tag(name = "name-server-management-controller", description = "Name server management API.")
48  @Validated
49  public interface NameServerManagementApi {
50  
51    /**
52     * Query dns nodes.
53     *
54     * @param query the query, can be a host name, an IP or a MAC address
55     * @param unknownFilter the unknown filter
56     * @return found dns nodes
57     */
58    @Operation(
59        summary = "Simple dns query.",
60        operationId = "query",
61        tags = {"name-server-management-controller"})
62    @ApiResponses(value = {
63        @ApiResponse(
64            responseCode = "200",
65            description = "The found dns nodes.",
66            content = @Content(
67                array = @ArraySchema(
68                    schema = @Schema(implementation = DnsNode.class)))),
69        @ApiResponse(
70            responseCode = "400",
71            description = "Bad request.",
72            content = @Content(
73                schema = @Schema(
74                    implementation = RestApiException.class))),
75        @ApiResponse(
76            responseCode = "500",
77            description = "Fatal server error.",
78            content = @Content(
79                schema = @Schema(
80                    implementation = RestApiException.class)))
81    })
82    @RequestMapping(
83        value = "/api/dns",
84        produces = {"application/json"},
85        method = RequestMethod.GET)
86    ResponseEntity<List<DnsNode>> query(
87        @Parameter(description = "The query, can be a host name, an IP or a MAC address.")
88        @RequestParam(name = "q") String query,
89  
90        @Parameter(description = "The unknown filter.")
91        @RequestParam(name = "filter", defaultValue = "NO_UNKNOWN") UnknownFilter unknownFilter);
92  
93    /**
94     * Gets dhcp leases.
95     *
96     * @param all if {@code true}, expired leases will also be returned, otherwise only active
97     *     ones (default is {@code false})
98     * @param sort the sort order (default is {@link DhcpLease#SORT_ORDER_BEGIN_HOSTNAME})
99     * @return the dhcp leases
100    */
101   @Operation(
102       summary = "Get dhcp leases.",
103       operationId = "getDhcpLeases",
104       tags = {"name-server-management-controller"})
105   @ApiResponses(value = {
106       @ApiResponse(
107           responseCode = "200",
108           description = "A list with dhcp leases.",
109           content = @Content(
110               array = @ArraySchema(
111                   schema = @Schema(implementation = DhcpLease.class)))),
112       @ApiResponse(
113           responseCode = "400",
114           description = "Bad request.",
115           content = @Content(
116               schema = @Schema(
117                   implementation = RestApiException.class))),
118       @ApiResponse(
119           responseCode = "500",
120           description = "Fatal server error.",
121           content = @Content(
122               schema = @Schema(
123                   implementation = RestApiException.class)))
124   })
125   @RequestMapping(value = "/api/dns/dhcp-leases",
126       produces = {"application/json"},
127       method = RequestMethod.GET)
128   ResponseEntity<List<DhcpLease>> getDhcpLeases(
129       @Parameter(description = "'true' returns also expired leases, 'false' only active ones.")
130       @RequestParam(value = "all", defaultValue = "false") Boolean all,
131       @Parameter(description = "The sort order.")
132       @RequestParam(value = "sort",
133           defaultValue = DhcpLease.SORT_ORDER_BEGIN_HOSTNAME) String sort);
134 
135   /**
136    * Get dns zones.
137    *
138    * @return the dns zones
139    */
140   @Operation(
141       summary = "Get all dns zones.",
142       operationId = "getDnsZones",
143       tags = {"name-server-management-controller"})
144   @ApiResponses(value = {
145       @ApiResponse(
146           responseCode = "200",
147           description = "A list with dns zones.",
148           content = @Content(
149               array = @ArraySchema(
150                   schema = @Schema(implementation = DnsZone.class)))),
151       @ApiResponse(
152           responseCode = "400",
153           description = "Bad request.",
154           content = @Content(
155               schema = @Schema(
156                   implementation = RestApiException.class))),
157       @ApiResponse(
158           responseCode = "500",
159           description = "Fatal server error.",
160           content = @Content(
161               schema = @Schema(
162                   implementation = RestApiException.class)))
163   })
164   @RequestMapping(
165       value = "/api/dns/zones",
166       produces = {"application/json"},
167       method = RequestMethod.GET)
168   ResponseEntity<List<DnsZone>> getDnsZones();
169 
170   /**
171    * Add dns zone.
172    *
173    * @param request the request
174    * @return the added dns zone
175    */
176   @Operation(
177       summary = "Add dns zone.",
178       operationId = "addDnsZone",
179       tags = {"name-server-management-controller"})
180   @ApiResponses(value = {
181       @ApiResponse(
182           responseCode = "200",
183           description = "The zone was successfully added.",
184           content = @Content(
185               schema = @Schema(
186                   implementation = DnsZone.class))),
187       @ApiResponse(
188           responseCode = "400",
189           description = "Bad request.",
190           content = @Content(
191               schema = @Schema(
192                   implementation = RestApiException.class))),
193       @ApiResponse(
194           responseCode = "500",
195           description = "Fatal server error.",
196           content = @Content(
197               schema = @Schema(
198                   implementation = RestApiException.class)))
199   })
200   @RequestMapping(
201       value = "/api/dns/zones",
202       produces = {"application/json"},
203       consumes = {"application/json"},
204       method = RequestMethod.POST)
205   ResponseEntity<DnsZone> addDnsZone(
206       @Parameter(description = "The dns zone to add.", required = true)
207       @Valid @RequestBody DnsZone request);
208 
209   /**
210    * Delete dns zone.
211    *
212    * @param zoneName the zone name
213    * @return {@code true} if the dns zone was deleted, otherwise {@code false}
214    */
215   @Operation(
216       summary = "Delete dns zone.",
217       operationId = "deleteDnsZone",
218       tags = {"name-server-management-controller"})
219   @ApiResponses(value = {
220       @ApiResponse(
221           responseCode = "200",
222           description = "True if the dns zone was successfully deleted, otherwise false.",
223           content = @Content(
224               schema = @Schema(
225                   implementation = Boolean.class))),
226       @ApiResponse(
227           responseCode = "400",
228           description = "Bad request.",
229           content = @Content(
230               schema = @Schema(
231                   implementation = RestApiException.class))),
232       @ApiResponse(
233           responseCode = "500",
234           description = "Fatal server error.",
235           content = @Content(
236               schema = @Schema(
237                   implementation = RestApiException.class)))
238   })
239   @RequestMapping(
240       value = "/api/dns/zones/{zoneName}",
241       produces = {"application/json"},
242       method = RequestMethod.DELETE)
243   ResponseEntity<Boolean> deleteDnsZone(
244       @Parameter(description = "The dns zone name.", required = true)
245       @PathVariable(value = "zoneName") String zoneName);
246 
247 
248   /**
249    * Get dns nodes.
250    *
251    * @param zoneName the zone name
252    * @param unknownFilter the unknown filter
253    * @param query the query
254    * @return the dns nodes
255    */
256   @Operation(
257       summary = "Get all dns nodes of a zone.",
258       operationId = "getDnsNodes",
259       tags = {"name-server-management-controller"})
260   @ApiResponses(value = {
261       @ApiResponse(
262           responseCode = "200",
263           description = "A list with dns nodes.",
264           content = @Content(
265               array = @ArraySchema(
266                   schema = @Schema(implementation = DnsNode.class)))),
267       @ApiResponse(
268           responseCode = "400",
269           description = "Bad request.",
270           content = @Content(
271               schema = @Schema(
272                   implementation = RestApiException.class))),
273       @ApiResponse(
274           responseCode = "404",
275           description = "Not found.",
276           content = @Content(
277               schema = @Schema(
278                   implementation = RestApiException.class))),
279       @ApiResponse(
280           responseCode = "500",
281           description = "Fatal server error.",
282           content = @Content(
283               schema = @Schema(
284                   implementation = RestApiException.class)))
285   })
286   @RequestMapping(value = "/api/dns/zones/{zoneName}",
287       produces = {"application/json"},
288       method = RequestMethod.GET)
289   ResponseEntity<List<DnsNode>> getDnsNodes(
290       @Parameter(description = "The dns zone name.", required = true)
291       @PathVariable(value = "zoneName") String zoneName,
292 
293       @Parameter(description = "The unknown filter.")
294       @RequestParam(name = "filter", defaultValue = "NO_UNKNOWN") UnknownFilter unknownFilter,
295 
296       @Parameter(description = "A query.")
297       @RequestParam(name = "q", required = false) String query);
298 
299   /**
300    * Save dns node.
301    *
302    * @param zoneName the dns zone name
303    * @param dnsNode the dns node
304    * @return the saved dns node
305    */
306   @Operation(
307       summary = "Save dns node.",
308       operationId = "saveDnsNode",
309       tags = {"name-server-management-controller"})
310   @ApiResponses(value = {
311       @ApiResponse(
312           responseCode = "200",
313           description = "The dns node was successfully saved.",
314           content = @Content(
315               schema = @Schema(
316                   implementation = DnsNode.class))),
317       @ApiResponse(
318           responseCode = "204",
319           description = "The dns node was deleted due to no records."),
320       @ApiResponse(
321           responseCode = "400",
322           description = "Bad request.",
323           content = @Content(
324               schema = @Schema(
325                   implementation = RestApiException.class))),
326       @ApiResponse(
327           responseCode = "404",
328           description = "Not found.",
329           content = @Content(
330               schema = @Schema(
331                   implementation = RestApiException.class))),
332       @ApiResponse(
333           responseCode = "500",
334           description = "Fatal server error.",
335           content = @Content(
336               schema = @Schema(
337                   implementation = RestApiException.class)))
338   })
339   @RequestMapping(
340       value = "/api/dns/zones/{zoneName}",
341       produces = {"application/json"},
342       consumes = {"application/json"},
343       method = RequestMethod.POST)
344   ResponseEntity<DnsNode> saveDnsNode(
345       @Parameter(description = "The dns zone name.", required = true)
346       @PathVariable("zoneName") String zoneName,
347 
348       @Parameter(description = "The dns node to save.", required = true)
349       @Valid @RequestBody DnsNode dnsNode);
350 
351   /**
352    * Get dns node.
353    *
354    * @param zoneName the dns zone name
355    * @param nodeName the dns node name
356    * @param unknownFilter the unknown filter
357    * @return the dns node
358    */
359   @Operation(
360       summary = "Get dns node.",
361       operationId = "getDnsNode",
362       tags = {"name-server-management-controller"})
363   @ApiResponses(value = {
364       @ApiResponse(
365           responseCode = "200",
366           description = "The dns node.",
367           content = @Content(
368               schema = @Schema(
369                   implementation = DnsNode.class))),
370       @ApiResponse(
371           responseCode = "400",
372           description = "Bad request.",
373           content = @Content(
374               schema = @Schema(
375                   implementation = RestApiException.class))),
376       @ApiResponse(
377           responseCode = "404",
378           description = "Not found.",
379           content = @Content(
380               schema = @Schema(
381                   implementation = RestApiException.class))),
382       @ApiResponse(
383           responseCode = "500",
384           description = "Fatal server error.",
385           content = @Content(
386               schema = @Schema(
387                   implementation = RestApiException.class)))
388   })
389   @RequestMapping(
390       value = "/api/dns/zones/{zoneName}/{nodeName}",
391       produces = {"application/json"},
392       method = RequestMethod.GET)
393   ResponseEntity<DnsNode> getDnsNode(
394       @Parameter(description = "The dns zone name.", required = true)
395       @PathVariable("zoneName") String zoneName,
396 
397       @Parameter(description = "The dns node name.", required = true)
398       @PathVariable("nodeName") String nodeName,
399 
400       @Parameter(description = "The unknown filter.")
401       @RequestParam(name = "filter", defaultValue = "NO_UNKNOWN") UnknownFilter unknownFilter);
402 
403   /**
404    * Delete dns node.
405    *
406    * @param zoneName the dns zone name
407    * @param nodeName the dns node name
408    * @return {@code true} if the dns node was removed; {@code false} if dns node didn't exist
409    */
410   @Operation(
411       summary = "Delete dns node.",
412       operationId = "deleteDnsNode",
413       tags = {"name-server-management-controller"})
414   @ApiResponses(value = {
415       @ApiResponse(
416           responseCode = "200",
417           description = "True if the dns node was removed; false if dns node didn't exist.",
418           content = @Content(
419               schema = @Schema(
420                   implementation = Boolean.class))),
421       @ApiResponse(
422           responseCode = "400",
423           description = "Bad request.",
424           content = @Content(
425               schema = @Schema(
426                   implementation = RestApiException.class))),
427       @ApiResponse(
428           responseCode = "404",
429           description = "DNS zone not found.",
430           content = @Content(
431               schema = @Schema(
432                   implementation = RestApiException.class))),
433       @ApiResponse(
434           responseCode = "500",
435           description = "Fatal server error.",
436           content = @Content(
437               schema = @Schema(
438                   implementation = RestApiException.class)))
439   })
440   @RequestMapping(
441       value = "/api/dns/zones/{zoneName}/{nodeName}",
442       produces = {"application/json"},
443       method = RequestMethod.DELETE)
444   ResponseEntity<Boolean> deleteDnsNode(
445       @Parameter(description = "The dns zone name.", required = true)
446       @PathVariable("zoneName") String zoneName,
447 
448       @Parameter(description = "The dns node name.", required = true)
449       @PathVariable("nodeName") String nodeName);
450 
451   /**
452    * Delete all dns nodes.
453    *
454    * @param zoneName the zone name
455    * @param nodeNames the node names (if the list is empty, all dns nodes will be deleted)
456    * @return void response entity
457    */
458   @Operation(
459       summary = "Delete all dns nodes.",
460       operationId = "deleteAllDnsNodes",
461       tags = {"name-server-management-controller"})
462   @ApiResponses(value = {
463       @ApiResponse(
464           responseCode = "200",
465           description = "All dns nodes were deleted."),
466       @ApiResponse(
467           responseCode = "400",
468           description = "Bad request.",
469           content = @Content(
470               schema = @Schema(
471                   implementation = RestApiException.class))),
472       @ApiResponse(
473           responseCode = "404",
474           description = "DNS zone not found.",
475           content = @Content(
476               schema = @Schema(
477                   implementation = RestApiException.class))),
478       @ApiResponse(
479           responseCode = "500",
480           description = "Fatal server error.",
481           content = @Content(
482               schema = @Schema(
483                   implementation = RestApiException.class)))
484   })
485   @RequestMapping(
486       value = "/api/dns/zones/{zoneName}/nodes/all",
487       produces = {"application/json"},
488       method = RequestMethod.DELETE)
489   ResponseEntity<Void> deleteAllDnsNodes(
490       @Parameter(description = "The dns zone name.", required = true)
491       @PathVariable("zoneName") String zoneName,
492 
493       @Parameter(description = "The dns node names.")
494       @RequestParam(value = "nodeNames", required = false) List<String> nodeNames);
495 
496 }