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