MAAS

Merge ~jsseidel/maas:jsseidel-subnets-api-annotations into maas:master

  1. Git
  2. lp:~jsseidel/maas
  3. jsseidel-subnets-api-annotations
  4. Merge into master
Proposed by Spencer Seidel
Status: Merged
Approved by: Newell Jensen
Approved revision: 44701ad3211ef6c2ea852e687e87529acc58d13b
Merge reported by: MAAS Lander
Merged at revision: not available
Proposed branch: ~jsseidel/maas:jsseidel-subnets-api-annotations
Merge into: maas:master
Diff against target: 1186 lines (+946/-133)
2 files modified
src/maasserver/api/examples/subnets.json (+716/-0)
src/maasserver/api/subnets.py (+230/-133)
Reviewer Review Type Date Requested Status
Newell Jensen (community) Approve
MAAS Lander unittests Pending
Review via email: mp+359653@code.launchpad.net

Commit message

Added API annotations with examples.

To post a comment you must log in.
Revision history for this message
Newell Jensen (newell-jensen) wrote :

Looks good.

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/src/maasserver/api/examples/subnets.json b/src/maasserver/api/examples/subnets.json
2new file mode 100644
3index 0000000..028f2a5
4--- /dev/null
5+++ b/src/maasserver/api/examples/subnets.json
6@@ -0,0 +1,716 @@
7+{
8+ "subnets-read": [
9+ {
10+ "name": "name-rLI3eq",
11+ "vlan": {
12+ "vid": 0,
13+ "mtu": 1500,
14+ "dhcp_on": false,
15+ "external_dhcp": null,
16+ "relay_vlan": null,
17+ "secondary_rack": "76y7pg",
18+ "fabric_id": 0,
19+ "space": "management",
20+ "fabric": "fabric-0",
21+ "id": 5001,
22+ "name": "untagged",
23+ "primary_rack": "7xtf67",
24+ "resource_uri": "/MAAS/api/2.0/vlans/5001/"
25+ },
26+ "cidr": "172.16.1.0/24",
27+ "rdns_mode": 2,
28+ "gateway_ip": "172.16.1.1",
29+ "dns_servers": [
30+ "fd89:8724:81f1:5512:557f:99c3:6967:8d63"
31+ ],
32+ "allow_dns": true,
33+ "allow_proxy": true,
34+ "active_discovery": false,
35+ "managed": true,
36+ "space": "management",
37+ "id": 1,
38+ "resource_uri": "/MAAS/api/2.0/subnets/1/"
39+ },
40+ {
41+ "name": "name-v5djzQ",
42+ "vlan": {
43+ "vid": 0,
44+ "mtu": 1500,
45+ "dhcp_on": false,
46+ "external_dhcp": null,
47+ "relay_vlan": null,
48+ "secondary_rack": "76y7pg",
49+ "fabric_id": 1,
50+ "space": "management",
51+ "fabric": "fabric-1",
52+ "id": 5003,
53+ "name": "untagged",
54+ "primary_rack": "7xtf67",
55+ "resource_uri": "/MAAS/api/2.0/vlans/5003/"
56+ },
57+ "cidr": "172.16.2.0/24",
58+ "rdns_mode": 2,
59+ "gateway_ip": "172.16.2.1",
60+ "dns_servers": [
61+ "fcb0:c682:8c15:817d:7d80:2713:e225:5624",
62+ "fd66:86c9:6a50:27cd:de13:3f1c:40d1:8aac",
63+ "120.129.237.29"
64+ ],
65+ "allow_dns": true,
66+ "allow_proxy": true,
67+ "active_discovery": false,
68+ "managed": true,
69+ "space": "management",
70+ "id": 2,
71+ "resource_uri": "/MAAS/api/2.0/subnets/2/"
72+ },
73+ {
74+ "name": "name-zznp45",
75+ "vlan": {
76+ "vid": 10,
77+ "mtu": 1500,
78+ "dhcp_on": false,
79+ "external_dhcp": null,
80+ "relay_vlan": null,
81+ "secondary_rack": "76y7pg",
82+ "fabric_id": 0,
83+ "space": "internal",
84+ "fabric": "fabric-0",
85+ "id": 5002,
86+ "name": "10",
87+ "primary_rack": "7xtf67",
88+ "resource_uri": "/MAAS/api/2.0/vlans/5002/"
89+ },
90+ "cidr": "172.16.3.0/24",
91+ "rdns_mode": 2,
92+ "gateway_ip": "172.16.3.1",
93+ "dns_servers": [
94+ "fd98:8601:90d0:c8c:dd2e:ba51:fa5a:dcfa",
95+ "11.209.150.208",
96+ "fde6:f9ef:3ee9:c5de:2a66:1582:cc83:abaf"
97+ ],
98+ "allow_dns": true,
99+ "allow_proxy": true,
100+ "active_discovery": false,
101+ "managed": true,
102+ "space": "internal",
103+ "id": 3,
104+ "resource_uri": "/MAAS/api/2.0/subnets/3/"
105+ },
106+ {
107+ "name": "name-c2ULe1",
108+ "vlan": {
109+ "vid": 10,
110+ "mtu": 1500,
111+ "dhcp_on": false,
112+ "external_dhcp": null,
113+ "relay_vlan": null,
114+ "secondary_rack": "76y7pg",
115+ "fabric_id": 0,
116+ "space": "internal",
117+ "fabric": "fabric-0",
118+ "id": 5002,
119+ "name": "10",
120+ "primary_rack": "7xtf67",
121+ "resource_uri": "/MAAS/api/2.0/vlans/5002/"
122+ },
123+ "cidr": "172.16.4.0/24",
124+ "rdns_mode": 2,
125+ "gateway_ip": "172.16.4.1",
126+ "dns_servers": [
127+ "fd08:fef7:5c1f:a2e6:3d8e:6c3b:89f9:80cb",
128+ "fc67:ad6a:88fe:9192:62f9:e882:8bcc:339e",
129+ "255.59.162.158"
130+ ],
131+ "allow_dns": true,
132+ "allow_proxy": true,
133+ "active_discovery": false,
134+ "managed": true,
135+ "space": "internal",
136+ "id": 4,
137+ "resource_uri": "/MAAS/api/2.0/subnets/4/"
138+ },
139+ {
140+ "name": "name-m3vYqT",
141+ "vlan": {
142+ "vid": 42,
143+ "mtu": 1500,
144+ "dhcp_on": false,
145+ "external_dhcp": null,
146+ "relay_vlan": null,
147+ "secondary_rack": null,
148+ "fabric_id": 1,
149+ "space": "ipv6-testbed",
150+ "fabric": "fabric-1",
151+ "id": 5004,
152+ "name": "42",
153+ "primary_rack": null,
154+ "resource_uri": "/MAAS/api/2.0/vlans/5004/"
155+ },
156+ "cidr": "2001:db8:42::/64",
157+ "rdns_mode": 2,
158+ "gateway_ip": null,
159+ "dns_servers": [
160+ "fd15:6cb0:a55c:235f:e78f:ba4f:2eb4:6b3",
161+ "fcc5:8b5e:c55b:90e0:8be:6b87:eb5:f4c7"
162+ ],
163+ "allow_dns": true,
164+ "allow_proxy": true,
165+ "active_discovery": false,
166+ "managed": true,
167+ "space": "ipv6-testbed",
168+ "id": 5,
169+ "resource_uri": "/MAAS/api/2.0/subnets/5/"
170+ },
171+ {
172+ "name": "192.168.122.0/24",
173+ "vlan": {
174+ "vid": 0,
175+ "mtu": 1500,
176+ "dhcp_on": false,
177+ "external_dhcp": null,
178+ "relay_vlan": null,
179+ "secondary_rack": "76y7pg",
180+ "fabric_id": 0,
181+ "space": "management",
182+ "fabric": "fabric-0",
183+ "id": 5001,
184+ "name": "untagged",
185+ "primary_rack": "7xtf67",
186+ "resource_uri": "/MAAS/api/2.0/vlans/5001/"
187+ },
188+ "cidr": "192.168.122.0/24",
189+ "rdns_mode": 2,
190+ "gateway_ip": "192.168.122.1",
191+ "dns_servers": [],
192+ "allow_dns": true,
193+ "allow_proxy": true,
194+ "active_discovery": false,
195+ "managed": true,
196+ "space": "management",
197+ "id": 6,
198+ "resource_uri": "/MAAS/api/2.0/subnets/6/"
199+ },
200+ {
201+ "name": "172.16.99.0/24",
202+ "vlan": {
203+ "vid": 0,
204+ "mtu": 1500,
205+ "dhcp_on": false,
206+ "external_dhcp": null,
207+ "relay_vlan": null,
208+ "secondary_rack": "76y7pg",
209+ "fabric_id": 0,
210+ "space": "management",
211+ "fabric": "fabric-0",
212+ "id": 5001,
213+ "name": "untagged",
214+ "primary_rack": "7xtf67",
215+ "resource_uri": "/MAAS/api/2.0/vlans/5001/"
216+ },
217+ "cidr": "172.16.99.0/24",
218+ "rdns_mode": 2,
219+ "gateway_ip": null,
220+ "dns_servers": [],
221+ "allow_dns": true,
222+ "allow_proxy": true,
223+ "active_discovery": false,
224+ "managed": true,
225+ "space": "management",
226+ "id": 7,
227+ "resource_uri": "/MAAS/api/2.0/subnets/7/"
228+ }
229+ ],
230+ "subnets-create": {
231+ "name": "172.16.5.0/24",
232+ "vlan": {
233+ "vid": 0,
234+ "mtu": 1500,
235+ "dhcp_on": false,
236+ "external_dhcp": null,
237+ "relay_vlan": null,
238+ "secondary_rack": "76y7pg",
239+ "fabric_id": 0,
240+ "space": "management",
241+ "fabric": "fabric-0",
242+ "id": 5001,
243+ "name": "untagged",
244+ "primary_rack": "7xtf67",
245+ "resource_uri": "/MAAS/api/2.0/vlans/5001/"
246+ },
247+ "cidr": "172.16.5.0/24",
248+ "rdns_mode": 2,
249+ "gateway_ip": "",
250+ "dns_servers": [],
251+ "allow_dns": true,
252+ "allow_proxy": true,
253+ "active_discovery": false,
254+ "managed": true,
255+ "space": "management",
256+ "id": 9,
257+ "resource_uri": "/MAAS/api/2.0/subnets/9/"
258+ },
259+ "subnets-read-by-id": {
260+ "name": "172.16.5.0/24",
261+ "vlan": {
262+ "vid": 0,
263+ "mtu": 1500,
264+ "dhcp_on": false,
265+ "external_dhcp": null,
266+ "relay_vlan": null,
267+ "fabric_id": 0,
268+ "secondary_rack": "76y7pg",
269+ "id": 5001,
270+ "fabric": "fabric-0",
271+ "name": "untagged",
272+ "space": "management",
273+ "primary_rack": "7xtf67",
274+ "resource_uri": "/MAAS/api/2.0/vlans/5001/"
275+ },
276+ "cidr": "172.16.5.0/24",
277+ "rdns_mode": 2,
278+ "gateway_ip": null,
279+ "dns_servers": [],
280+ "allow_dns": true,
281+ "allow_proxy": true,
282+ "active_discovery": false,
283+ "managed": true,
284+ "id": 9,
285+ "space": "management",
286+ "resource_uri": "/MAAS/api/2.0/subnets/9/"
287+ },
288+ "subnets-update": {
289+ "name": "172.16.5.0/24",
290+ "vlan": {
291+ "vid": 0,
292+ "mtu": 1500,
293+ "dhcp_on": false,
294+ "external_dhcp": null,
295+ "relay_vlan": null,
296+ "primary_rack": "7xtf67",
297+ "secondary_rack": "76y7pg",
298+ "id": 5001,
299+ "fabric": "fabric-0",
300+ "fabric_id": 0,
301+ "name": "untagged",
302+ "space": "management",
303+ "resource_uri": "/MAAS/api/2.0/vlans/5001/"
304+ },
305+ "cidr": "172.16.5.0/24",
306+ "rdns_mode": 2,
307+ "gateway_ip": "",
308+ "dns_servers": [],
309+ "allow_dns": true,
310+ "allow_proxy": true,
311+ "active_discovery": false,
312+ "managed": true,
313+ "id": 9,
314+ "space": "management",
315+ "resource_uri": "/MAAS/api/2.0/subnets/9/"
316+ },
317+ "subnets-reserved-ips": [
318+ {
319+ "start": "172.16.2.1",
320+ "end": "172.16.2.1",
321+ "num_addresses": 1,
322+ "purpose": [
323+ "gateway-ip"
324+ ]
325+ },
326+ {
327+ "start": "172.16.2.3",
328+ "end": "172.16.2.4",
329+ "num_addresses": 2,
330+ "purpose": [
331+ "assigned-ip"
332+ ]
333+ },
334+ {
335+ "start": "172.16.2.11",
336+ "end": "172.16.2.11",
337+ "num_addresses": 1,
338+ "purpose": [
339+ "assigned-ip"
340+ ]
341+ },
342+ {
343+ "start": "172.16.2.26",
344+ "end": "172.16.2.26",
345+ "num_addresses": 1,
346+ "purpose": [
347+ "assigned-ip"
348+ ]
349+ },
350+ {
351+ "start": "172.16.2.62",
352+ "end": "172.16.2.63",
353+ "num_addresses": 2,
354+ "purpose": [
355+ "assigned-ip"
356+ ]
357+ },
358+ {
359+ "start": "172.16.2.101",
360+ "end": "172.16.2.101",
361+ "num_addresses": 1,
362+ "purpose": [
363+ "gateway-ip"
364+ ]
365+ },
366+ {
367+ "start": "172.16.2.109",
368+ "end": "172.16.2.109",
369+ "num_addresses": 1,
370+ "purpose": [
371+ "assigned-ip"
372+ ]
373+ },
374+ {
375+ "start": "172.16.2.111",
376+ "end": "172.16.2.111",
377+ "num_addresses": 1,
378+ "purpose": [
379+ "assigned-ip"
380+ ]
381+ },
382+ {
383+ "start": "172.16.2.116",
384+ "end": "172.16.2.116",
385+ "num_addresses": 1,
386+ "purpose": [
387+ "assigned-ip"
388+ ]
389+ },
390+ {
391+ "start": "172.16.2.134",
392+ "end": "172.16.2.134",
393+ "num_addresses": 1,
394+ "purpose": [
395+ "assigned-ip"
396+ ]
397+ },
398+ {
399+ "start": "172.16.2.174",
400+ "end": "172.16.2.174",
401+ "num_addresses": 1,
402+ "purpose": [
403+ "gateway-ip"
404+ ]
405+ },
406+ {
407+ "start": "172.16.2.206",
408+ "end": "172.16.2.206",
409+ "num_addresses": 1,
410+ "purpose": [
411+ "assigned-ip"
412+ ]
413+ },
414+ {
415+ "start": "172.16.2.235",
416+ "end": "172.16.2.235",
417+ "num_addresses": 1,
418+ "purpose": [
419+ "assigned-ip"
420+ ]
421+ },
422+ {
423+ "start": "172.16.2.237",
424+ "end": "172.16.2.237",
425+ "num_addresses": 1,
426+ "purpose": [
427+ "gateway-ip"
428+ ]
429+ },
430+ {
431+ "start": "172.16.2.252",
432+ "end": "172.16.2.252",
433+ "num_addresses": 1,
434+ "purpose": [
435+ "assigned-ip"
436+ ]
437+ }
438+ ],
439+ "subnets-unreserved-ips": [
440+ {
441+ "start": "172.16.2.2",
442+ "end": "172.16.2.2",
443+ "num_addresses": 1
444+ },
445+ {
446+ "start": "172.16.2.5",
447+ "end": "172.16.2.10",
448+ "num_addresses": 6
449+ },
450+ {
451+ "start": "172.16.2.12",
452+ "end": "172.16.2.25",
453+ "num_addresses": 14
454+ },
455+ {
456+ "start": "172.16.2.27",
457+ "end": "172.16.2.61",
458+ "num_addresses": 35
459+ },
460+ {
461+ "start": "172.16.2.64",
462+ "end": "172.16.2.100",
463+ "num_addresses": 37
464+ },
465+ {
466+ "start": "172.16.2.102",
467+ "end": "172.16.2.108",
468+ "num_addresses": 7
469+ },
470+ {
471+ "start": "172.16.2.110",
472+ "end": "172.16.2.110",
473+ "num_addresses": 1
474+ },
475+ {
476+ "start": "172.16.2.112",
477+ "end": "172.16.2.115",
478+ "num_addresses": 4
479+ },
480+ {
481+ "start": "172.16.2.117",
482+ "end": "172.16.2.133",
483+ "num_addresses": 17
484+ },
485+ {
486+ "start": "172.16.2.135",
487+ "end": "172.16.2.173",
488+ "num_addresses": 39
489+ },
490+ {
491+ "start": "172.16.2.175",
492+ "end": "172.16.2.205",
493+ "num_addresses": 31
494+ },
495+ {
496+ "start": "172.16.2.207",
497+ "end": "172.16.2.234",
498+ "num_addresses": 28
499+ },
500+ {
501+ "start": "172.16.2.236",
502+ "end": "172.16.2.236",
503+ "num_addresses": 1
504+ },
505+ {
506+ "start": "172.16.2.238",
507+ "end": "172.16.2.251",
508+ "num_addresses": 14
509+ },
510+ {
511+ "start": "172.16.2.253",
512+ "end": "172.16.2.254",
513+ "num_addresses": 2
514+ }
515+ ],
516+ "subnets-statistics": {
517+ "num_available": 232,
518+ "largest_available": 41,
519+ "num_unavailable": 22,
520+ "total_addresses": 254,
521+ "usage": 0.08661417322834646,
522+ "usage_string": "9%",
523+ "available_string": "91%",
524+ "first_address": "172.16.1.1",
525+ "last_address": "172.16.1.254",
526+ "ip_version": 4
527+ },
528+ "subnets-ip-addresses": [
529+ {
530+ "ip": "172.16.2.3",
531+ "alloc_type": 1,
532+ "created": "Tue, 27 Nov. 2018 18:06:19",
533+ "updated": "Tue, 27 Nov. 2018 18:06:19",
534+ "node_summary": {
535+ "system_id": "76y7pg",
536+ "node_type": 2,
537+ "fqdn": "happy-rack.maas",
538+ "hostname": "happy-rack",
539+ "is_container": false,
540+ "via": "eth2"
541+ }
542+ },
543+ {
544+ "ip": "172.16.2.4",
545+ "alloc_type": 1,
546+ "created": "Tue, 27 Nov. 2018 18:06:19",
547+ "updated": "Tue, 27 Nov. 2018 18:06:19",
548+ "node_summary": {
549+ "system_id": "nfkend",
550+ "node_type": 3,
551+ "fqdn": "happy-region.maas",
552+ "hostname": "happy-region",
553+ "is_container": false,
554+ "via": "eth2"
555+ }
556+ },
557+ {
558+ "ip": "172.16.2.11",
559+ "alloc_type": 1,
560+ "created": "Tue, 27 Nov. 2018 18:07:25",
561+ "updated": "Tue, 27 Nov. 2018 18:07:25",
562+ "node_summary": {
563+ "system_id": "dq3sda",
564+ "node_type": 0,
565+ "fqdn": "kind-dory.maas",
566+ "hostname": "kind-dory",
567+ "is_container": false,
568+ "via": "eth-xnY2lB"
569+ },
570+ "user": "user2"
571+ },
572+ {
573+ "ip": "172.16.2.26",
574+ "alloc_type": 1,
575+ "created": "Tue, 27 Nov. 2018 18:07:09",
576+ "updated": "Tue, 27 Nov. 2018 18:07:09",
577+ "node_summary": {
578+ "system_id": "seebkg",
579+ "node_type": 0,
580+ "fqdn": "grown-cougar.maas",
581+ "hostname": "grown-cougar",
582+ "is_container": false,
583+ "via": "eth-GZF5ig"
584+ },
585+ "user": "user2"
586+ },
587+ {
588+ "ip": "172.16.2.62",
589+ "alloc_type": 1,
590+ "created": "Tue, 27 Nov. 2018 18:07:24",
591+ "updated": "Tue, 27 Nov. 2018 18:07:24",
592+ "node_summary": {
593+ "system_id": "r7enqt",
594+ "node_type": 0,
595+ "fqdn": "nice-gannet.maas",
596+ "hostname": "nice-gannet",
597+ "is_container": false,
598+ "via": "eth-nlvMd2"
599+ },
600+ "user": "user1"
601+ },
602+ {
603+ "ip": "172.16.2.63",
604+ "alloc_type": 1,
605+ "created": "Tue, 27 Nov. 2018 18:06:29",
606+ "updated": "Tue, 27 Nov. 2018 18:06:29",
607+ "node_summary": {
608+ "system_id": "pme7wb",
609+ "node_type": 0,
610+ "fqdn": "solid-liger.sample",
611+ "hostname": "solid-liger",
612+ "is_container": false,
613+ "via": "eth-2VCthm"
614+ }
615+ },
616+ {
617+ "ip": "172.16.2.109",
618+ "alloc_type": 1,
619+ "created": "Tue, 27 Nov. 2018 18:07:25",
620+ "updated": "Tue, 27 Nov. 2018 18:07:25",
621+ "node_summary": {
622+ "system_id": "dq3sda",
623+ "node_type": 0,
624+ "fqdn": "kind-dory.maas",
625+ "hostname": "kind-dory",
626+ "is_container": false,
627+ "via": "eth-fS18k5"
628+ },
629+ "user": "user2"
630+ },
631+ {
632+ "ip": "172.16.2.111",
633+ "alloc_type": 1,
634+ "created": "Tue, 27 Nov. 2018 18:07:07",
635+ "updated": "Tue, 27 Nov. 2018 18:07:07",
636+ "node_summary": {
637+ "system_id": "ydpcwh",
638+ "node_type": 0,
639+ "fqdn": "game-owl.ubnt",
640+ "hostname": "game-owl",
641+ "is_container": false,
642+ "via": "eth-Cyk2jC"
643+ },
644+ "user": "user2"
645+ },
646+ {
647+ "ip": "172.16.2.116",
648+ "alloc_type": 1,
649+ "created": "Tue, 27 Nov. 2018 18:07:10",
650+ "updated": "Tue, 27 Nov. 2018 18:07:10",
651+ "node_summary": {
652+ "system_id": "seebkg",
653+ "node_type": 0,
654+ "fqdn": "grown-cougar.maas",
655+ "hostname": "grown-cougar",
656+ "is_container": false,
657+ "via": "eth-0nEEnB"
658+ },
659+ "user": "user2"
660+ },
661+ {
662+ "ip": "172.16.2.134",
663+ "alloc_type": 1,
664+ "created": "Tue, 27 Nov. 2018 18:07:24",
665+ "updated": "Tue, 27 Nov. 2018 18:07:24",
666+ "node_summary": {
667+ "system_id": "r7enqt",
668+ "node_type": 0,
669+ "fqdn": "nice-gannet.maas",
670+ "hostname": "nice-gannet",
671+ "is_container": false,
672+ "via": "eth-dMPw46"
673+ },
674+ "user": "user1"
675+ },
676+ {
677+ "ip": "172.16.2.206",
678+ "alloc_type": 1,
679+ "created": "Tue, 27 Nov. 2018 18:07:24",
680+ "updated": "Tue, 27 Nov. 2018 18:07:24",
681+ "node_summary": {
682+ "system_id": "r7enqt",
683+ "node_type": 0,
684+ "fqdn": "nice-gannet.maas",
685+ "hostname": "nice-gannet",
686+ "is_container": false,
687+ "via": "eth-6Wz9hw"
688+ },
689+ "user": "user1"
690+ },
691+ {
692+ "ip": "172.16.2.235",
693+ "alloc_type": 1,
694+ "created": "Tue, 27 Nov. 2018 18:07:29",
695+ "updated": "Tue, 27 Nov. 2018 18:07:29",
696+ "node_summary": {
697+ "system_id": "7ghwxs",
698+ "node_type": 0,
699+ "fqdn": "alert-lion.sample",
700+ "hostname": "alert-lion",
701+ "is_container": false,
702+ "via": "bond-wnZNKS"
703+ },
704+ "user": "user2"
705+ },
706+ {
707+ "ip": "172.16.2.252",
708+ "alloc_type": 1,
709+ "created": "Tue, 27 Nov. 2018 18:07:32",
710+ "updated": "Tue, 27 Nov. 2018 18:07:32",
711+ "node_summary": {
712+ "system_id": "dnq43f",
713+ "node_type": 0,
714+ "fqdn": "square-hornet.maas",
715+ "hostname": "square-hornet",
716+ "is_container": false,
717+ "via": "eth-3GCPHI"
718+ },
719+ "user": "user2"
720+ }
721+ ]
722+}
723diff --git a/src/maasserver/api/subnets.py b/src/maasserver/api/subnets.py
724index 2fb9225..d342415 100644
725--- a/src/maasserver/api/subnets.py
726+++ b/src/maasserver/api/subnets.py
727@@ -49,84 +49,85 @@ class SubnetsHandler(OperationsHandler):
728 return ('subnets_handler', [])
729
730 def read(self, request):
731- """List all subnets."""
732+ """@description-title List all subnets
733+ @description Get a list of all subnets.
734+
735+ @success (http-status-code) "server-success" 200
736+ @success (json) "success-json" A JSON object containing list of all
737+ known subnets.
738+ @success-example "success-json" [exkey=subnets-read] placeholder text
739+ """
740 return Subnet.objects.all()
741
742 @admin_method
743 def create(self, request):
744- """\
745- Create a subnet.
746-
747- Required parameters
748- -------------------
749+ """@description-title Create a subnet
750+ @description Creates a new subnet.
751
752- cidr
753- The network CIDR for this subnet.
754+ @param (string) "cidr" [required=true] The network CIDR for this
755+ subnet.
756+ @param-example "cidr"
757+ 192.168.1.1/24
758
759+ @param (string) "name" [required=false] The subnet's name.
760
761- Optional parameters
762- -------------------
763+ @param (string) "description" [required=false] The subnet's
764+ description.
765
766- name
767- Name of the subnet.
768+ @param (string) "vlan" [required=false] VLAN this subnet belongs to.
769+ Defaults to the default VLAN for the provided fabric or defaults to the
770+ default VLAN in the default fabric (if unspecified).
771
772- description
773- Description of the subnet.
774+ @param (string) "fabric" [required=false] Fabric for the subnet.
775+ Defaults to the fabric the provided VLAN belongs to, or defaults to the
776+ default fabric.
777
778- vlan
779- VLAN this subnet belongs to. Defaults to the default VLAN for the
780- provided fabric or defaults to the default VLAN in the default fabric
781- (if unspecified).
782+ @param (int) "vid" [required=false] VID of the VLAN this subnet belongs
783+ to. Only used when vlan is not provided. Picks the VLAN with this VID
784+ in the provided fabric or the default fabric if one is not given.
785
786- fabric
787- Fabric for the subnet. Defaults to the fabric the
788- provided VLAN belongs to, or defaults to the default fabric.
789+ @param (string) "space" [required=false] Space this subnet is in.
790+ Defaults to the default space.
791
792- vid
793- VID of the VLAN this subnet belongs to. Only used when vlan is
794- not provided. Picks the VLAN with this VID in the provided
795- fabric or the default fabric if one is not given.
796+ @param (string) "gateway_ip" [required=false] The gateway IP address
797+ for this subnet.
798
799- space
800- Space this subnet is in. Defaults to the default space.
801+ @param (int) "rdns_mode" [required=false,formatting=true] How reverse
802+ DNS is handled for this subnet. One of:
803
804- gateway_ip
805- The gateway IP address for this subnet.
806+ - ``0`` Disabled: No reverse zone is created.
807+ - ``1`` Enabled: Generate reverse zone.
808+ - ``2`` RFC2317: Extends '1' to create the necessary parent zone with
809+ the appropriate CNAME resource records for the network, if the the
810+ network is small enough to require the support described in RFC2317.
811
812- rdns_mode
813- How reverse DNS is handled for this subnet.
814- One of: 0 (Disabled), 1 (Enabled), or 2 (RFC2317). Disabled
815- means no reverse zone is created; Enabled means generate the
816- reverse zone; RFC2317 extends Enabled to create the necessary
817- parent zone with the appropriate CNAME resource records for the
818- network, if the network is small enough to require the support
819- described in RFC2317.
820+ @param (int) "allow_dns" [required=false] Configure MAAS DNS to allow
821+ DNS resolution from this subnet. '0' == False,'1' == True.
822
823- allow_dns
824- Configure MAAS DNS to allow DNS resolution from this subnet.
825+ @param (int) "allow_proxy" [required=false] Configure maas-proxy to
826+ allow requests from this subnet. '0' == False, '1' == True.
827
828- allow_proxy
829- Configure maas-proxy to allow requests from this
830- subnet.
831+ @param (string) "dns_servers" [required=false] Comma-seperated list of
832+ DNS servers for this subnet.
833
834- dns_servers
835- Comma-seperated list of DNS servers for this subnet.
836+ @param (int) "managed" [required=false,formatting=true] In MAAS 2.0+,
837+ all subnets are assumed to be managed by default.
838
839- managed
840- In MAAS 2.0+, all subnets are assumed to be managed by default.
841+ Only managed subnets allow DHCP to be enabled on their related dynamic
842+ ranges. (Thus, dynamic ranges become "informational only"; an
843+ indication that another DHCP server is currently handling them, or that
844+ MAAS will handle them when the subnet is enabled for management.)
845
846- Only managed subnets allow DHCP to be enabled on their related
847- dynamic ranges. (Thus, dynamic ranges become "informational
848- only"; an indication that another DHCP server is currently
849- handling them, or that MAAS will handle them when the subnet is
850- enabled for management.)
851+ Managed subnets do not allow IP allocation by default. The meaning of a
852+ "reserved" IP range is reversed for an unmanaged subnet. (That is, for
853+ managed subnets, "reserved" means "MAAS cannot allocate any IP address
854+ within this reserved block". For unmanaged subnets, "reserved" means
855+ "MAAS must allocate IP addresses only from reserved IP ranges."
856
857- Managed subnets do not allow IP allocation by default. The
858- meaning of a "reserved" IP range is reversed for an unmanaged
859- subnet. (That is, for managed subnets, "reserved" means "MAAS
860- cannot allocate any IP address within this reserved block". For
861- unmanaged subnets, "reserved" means "MAAS must allocate IP
862- addresses only from reserved IP ranges".
863+ @success (http-status-code) "server-success" 200
864+ @success (json) "success-json" A JSON object containing information
865+ about the new subnet.
866+ @success-example "success-json" [exkey=subnets-create] placeholder text
867 """
868 form = SubnetForm(data=request.data)
869 if form.is_valid():
870@@ -158,58 +159,100 @@ class SubnetHandler(OperationsHandler):
871 return subnet.space.get_name()
872
873 def read(self, request, id):
874- """\
875- Read subnet.
876+ """@description-title Get a subnet
877+ @description Get information about a subnet with the given ID.
878
879- Returns 404 if the subnet is not found.
880+ @param (int) "{id}" [required=true] A subnet ID.
881+
882+ @success (http-status-code) "server-success" 200
883+ @success (json) "success-json" A JSON object containing information
884+ about the subnet.
885+ @success-example "success-json" [exkey=subnets-read-by-id] placeholder
886+ text
887+
888+ @error (http-status-code) "404" 404
889+ @error (content) "not-found" The requested subnet is not found.
890+ @error-example "not-found"
891+ Not Found
892 """
893 return Subnet.objects.get_subnet_or_404(
894 id, request.user, NodePermission.view)
895
896 def update(self, request, id):
897- """\
898- Update the specified subnet.
899+ """@description-title Update a subnet
900+ @description Update a subnet with the given ID.
901+
902+ @param (int) "{id}" [required=true] A subnet ID.
903
904- Please see the documentation for the 'create' operation for detailed
905- descriptions of each parameter.
906+ @param (string) "cidr" [required=false] The network CIDR for this
907+ subnet.
908+ @param-example "cidr"
909+ 192.168.1.1/24
910
911- Optional parameters
912- -------------------
913+ @param (string) "name" [required=false] The subnet's name.
914
915- name
916- Name of the subnet.
917+ @param (string) "description" [required=false] The subnet's
918+ description.
919
920- description
921- Description of the subnet.
922+ @param (string) "vlan" [required=false] VLAN this subnet belongs to.
923+ Defaults to the default VLAN for the provided fabric or defaults to the
924+ default VLAN in the default fabric (if unspecified).
925
926- vlan
927- VLAN this subnet belongs to.
928+ @param (string) "fabric" [required=false] Fabric for the subnet.
929+ Defaults to the fabric the provided VLAN belongs to, or defaults to the
930+ default fabric.
931
932- space
933- Space this subnet is in.
934+ @param (int) "vid" [required=false] VID of the VLAN this subnet belongs
935+ to. Only used when vlan is not provided. Picks the VLAN with this VID
936+ in the provided fabric or the default fabric if one is not given.
937
938- cidr
939- The network CIDR for this subnet.
940+ @param (string) "space" [required=false] Space this subnet is in.
941+ Defaults to the default space.
942
943- gateway_ip
944- The gateway IP address for this subnet.
945+ @param (string) "gateway_ip" [required=false] The gateway IP address
946+ for this subnet.
947
948- rdns_mode
949- How reverse DNS is handled for this subnet.
950+ @param (int) "rdns_mode" [required=false,formatting=true] How reverse
951+ DNS is handled for this subnet. One of:
952
953- allow_dns
954- Configure MAAS DNS to allow DNS resolution from this subnet.
955+ - ``0`` Disabled: No reverse zone is created.
956+ - ``1`` Enabled: Generate reverse zone.
957+ - ``2`` RFC2317: Extends '1' to create the necessary parent zone with
958+ the appropriate CNAME resource records for the network, if the the
959+ network is small enough to require the support described in RFC2317.
960
961- allow_proxy
962- Configure maas-proxy to allow requests from this subnet.
963+ @param (int) "allow_dns" [required=false] Configure MAAS DNS to allow
964+ DNS resolution from this subnet. '0' == False,'1' == True.
965
966- dns_servers
967- Comma-seperated list of DNS servers for this subnet.
968+ @param (int) "allow_proxy" [required=false] Configure maas-proxy to
969+ allow requests from this subnet. '0' == False, '1' == True.
970
971- managed
972- If False, MAAS should not manage this subnet. (Default: True)
973+ @param (string) "dns_servers" [required=false] Comma-seperated list of
974+ DNS servers for this subnet.
975
976- Returns 404 if the subnet is not found.
977+ @param (int) "managed" [required=false,formatting=true] In MAAS 2.0+,
978+ all subnets are assumed to be managed by default.
979+
980+ Only managed subnets allow DHCP to be enabled on their related dynamic
981+ ranges. (Thus, dynamic ranges become "informational only"; an
982+ indication that another DHCP server is currently handling them, or that
983+ MAAS will handle them when the subnet is enabled for management.)
984+
985+ Managed subnets do not allow IP allocation by default. The meaning of a
986+ "reserved" IP range is reversed for an unmanaged subnet. (That is, for
987+ managed subnets, "reserved" means "MAAS cannot allocate any IP address
988+ within this reserved block". For unmanaged subnets, "reserved" means
989+ "MAAS must allocate IP addresses only from reserved IP ranges."
990+
991+ @success (http-status-code) "server-success" 200
992+ @success (json) "success-json" A JSON object containing information
993+ about the updated subnet.
994+ @success-example "success-json" [exkey=subnets-create] placeholder text
995+
996+ @error (http-status-code) "404" 404
997+ @error (content) "not-found" The requested subnet is not found.
998+ @error-example "not-found"
999+ Not Found
1000 """
1001 subnet = Subnet.objects.get_subnet_or_404(
1002 id, request.user, NodePermission.admin)
1003@@ -220,10 +263,17 @@ class SubnetHandler(OperationsHandler):
1004 raise MAASAPIValidationError(form.errors)
1005
1006 def delete(self, request, id):
1007- """\
1008- Delete subnet.
1009+ """@description-title Delete a subnet
1010+ @description Delete a subnet with the given ID.
1011+
1012+ @param (int) "{id}" [required=true] A subnet ID.
1013+
1014+ @success (http-status-code) "server-success" 204
1015
1016- Returns 404 if the subnet is not found.
1017+ @error (http-status-code) "404" 404
1018+ @error (content) "not-found" The requested subnet is not found.
1019+ @error-example "not-found"
1020+ Not Found
1021 """
1022 subnet = Subnet.objects.get_subnet_or_404(
1023 id, request.user, NodePermission.admin)
1024@@ -232,10 +282,21 @@ class SubnetHandler(OperationsHandler):
1025
1026 @operation(idempotent=True)
1027 def reserved_ip_ranges(self, request, id):
1028- """\
1029- Lists IP ranges currently reserved in the subnet.
1030+ """@description-title List reserved IP ranges
1031+ @description Lists IP ranges currently reserved in the subnet.
1032
1033- Returns 404 if the subnet is not found.
1034+ @param (int) "{id}" [required=true] A subnet ID.
1035+
1036+ @success (http-status-code) "server-success" 200
1037+ @success (json) "success-json" A JSON object containing a list of
1038+ reserved IP ranges.
1039+ @success-example "success-json" [exkey=subnets-reserved-ips]
1040+ placeholder text
1041+
1042+ @error (http-status-code) "404" 404
1043+ @error (content) "not-found" The requested subnet is not found.
1044+ @error-example "not-found"
1045+ Not Found
1046 """
1047 subnet = Subnet.objects.get_subnet_or_404(
1048 id, request.user, NodePermission.view)
1049@@ -243,10 +304,21 @@ class SubnetHandler(OperationsHandler):
1050
1051 @operation(idempotent=True)
1052 def unreserved_ip_ranges(self, request, id):
1053- """\
1054- Lists IP ranges currently unreserved in the subnet.
1055+ """@description-title List unreserved IP ranges
1056+ @description Lists IP ranges currently unreserved in the subnet.
1057+
1058+ @param (int) "{id}" [required=true] A subnet ID.
1059
1060- Returns 404 if the subnet is not found.
1061+ @success (http-status-code) "server-success" 200
1062+ @success (json) "success-json" A JSON object containing a list of
1063+ unreserved IP ranges.
1064+ @success-example "success-json" [exkey=subnets-unreserved-ips]
1065+ placeholder text
1066+
1067+ @error (http-status-code) "404" 404
1068+ @error (content) "not-found" The requested subnet is not found.
1069+ @error-example "not-found"
1070+ Not Found
1071 """
1072 subnet = Subnet.objects.get_subnet_or_404(
1073 id, request.user, NodePermission.view)
1074@@ -255,29 +327,44 @@ class SubnetHandler(OperationsHandler):
1075
1076 @operation(idempotent=True)
1077 def statistics(self, request, id):
1078- """\
1079- Returns statistics for the specified subnet, including:
1080-
1081- num_available: the number of available IP addresses
1082- largest_available: the largest number of contiguous free IP addresses
1083- num_unavailable: the number of unavailable IP addresses
1084- total_addresses: the sum of the available plus unavailable addresses
1085- usage: the (floating point) usage percentage of this subnet
1086- usage_string: the (formatted unicode) usage percentage of this subnet
1087- ranges: the specific IP ranges present in ths subnet (if specified)
1088-
1089- Optional parameters
1090- -------------------
1091-
1092- include_ranges
1093- If True, includes detailed information
1094- about the usage of this range.
1095-
1096- include_suggestions
1097- If True, includes the suggested gateway and dynamic range for this
1098- subnet, if it were to be configured.
1099-
1100- Returns 404 if the subnet is not found.
1101+ """@description-title Get subnet statistics
1102+ @description Returns statistics for the specified subnet, including:
1103+
1104+ - **num_available**: the number of available IP addresses
1105+ - **largest_available**: the largest number of contiguous free IP
1106+ addresses
1107+ - **num_unavailable**: the number of unavailable IP addresses
1108+ - **total_addresses**: the sum of the available plus unavailable
1109+ addresses
1110+ - **usage**: the (floating point) usage percentage of this subnet
1111+ - **usage_string**: the (formatted unicode) usage percentage of this
1112+ subnet
1113+ - **ranges**: the specific IP ranges present in ths subnet (if
1114+ specified)
1115+
1116+ Note: to supply additional optional parameters for this request, add
1117+ them to the request URI: e.g.
1118+ ``/subnets/1/?op=statistics&include_suggestions=1``
1119+
1120+ @param (int) "{id}" [required=true] A subnet ID.
1121+
1122+ @param (int) "include_ranges" [required=false] If '1', includes
1123+ detailed information about the usage of this range. '1' == True, '0' ==
1124+ False.
1125+
1126+ @param (int) "include_suggestions" [required=false] If '1', includes
1127+ the suggested gateway and dynamic range for this subnet, if it were to
1128+ be configured. '1' == True, '0' == False.
1129+
1130+ @success (http-status-code) "server-success" 200
1131+ @success (json) "success-json" A JSON object containing the statistics.
1132+ @success-example "success-json" [exkey=subnets-statistics]
1133+ placeholder text
1134+
1135+ @error (http-status-code) "404" 404
1136+ @error (content) "not-found" The requested subnet is not found.
1137+ @error-example "not-found"
1138+ Not Found
1139 """
1140 subnet = Subnet.objects.get_subnet_or_404(
1141 id, request.user, NodePermission.view)
1142@@ -294,22 +381,32 @@ class SubnetHandler(OperationsHandler):
1143
1144 @operation(idempotent=True)
1145 def ip_addresses(self, request, id):
1146- """\
1147- Returns a summary of IP addresses assigned to this subnet.
1148+ """@description-title Summary of IP addresses
1149+ @description Returns a summary of IP addresses assigned to this subnet.
1150+
1151+ @param (int) "{id}" [required=true] A subnet ID.
1152+
1153+ @param (int) "with_username" [required=false] If '0', suppresses the
1154+ display of usernames associated with each address. '1' == True, '0' ==
1155+ False. (Default: '1')
1156
1157- Optional parameters
1158- -------------------
1159+ @param (int) "with_summary" [required=false] If '0', suppresses the
1160+ display of nodes, BMCs, and and DNS records associated with each
1161+ address. '1' == True, '0' == False. (Default: True)
1162
1163- with_username
1164- If False, suppresses the display of usernames associated with each
1165- address. (Default: True)
1166+ @param (int) "with_node_summary" [required=false] Deprecated. Use
1167+ 'with_summary'.
1168
1169- with_summary
1170- If False, suppresses the display of nodes, BMCs, and and DNS records
1171- associated with each address. (Default: True)
1172+ @success (http-status-code) "server-success" 200
1173+ @success (json) "success-json" A JSON object containing a list of IP
1174+ addresses and information about each.
1175+ @success-example "success-json" [exkey=subnets-ip-addresses]
1176+ placeholder text
1177
1178- with_node_summary
1179- Deprecated form of with_summary.
1180+ @error (http-status-code) "404" 404
1181+ @error (content) "not-found" The requested subnet is not found.
1182+ @error-example "not-found"
1183+ Not Found
1184 """
1185 subnet = Subnet.objects.get_subnet_or_404(
1186 id, request.user, NodePermission.view)

Subscribers

People subscribed via source and target branches