source: admin/WebConsole/rest/opengnsys-api.yml @ a51c727

918-git-images-111dconfigfileconfigure-oglivegit-imageslgromero-new-oglivemainmaint-cronmount-efivarfsmultivmmultivm-ogboot-installerogClonningEngineogboot-installer-jenkinsoglive-ipv6test-python-scriptsticket-301ticket-50ticket-50-oldticket-577ticket-585ticket-611ticket-612ticket-693ticket-700ubu24tplunification2use-local-agent-oglivevarios-instalacionwebconsole3
Last change on this file since a51c727 was 146d955, checked in by ramon <ramongomez@…>, 9 years ago

#708: Añadir algunos campos en rutas REST; docmentar ruta /ous/:ouid/groups y repasar definciones de seguridad y de campos requeridos.

git-svn-id: https://opengnsys.es/svn/branches/version1.1@5092 a21b9725-9963-47de-94b9-378ad31fedc9
  • Property mode set to 100644
File size: 28.5 KB
Line 
1swagger: '2.0'
2
3info:
4  version: "1.1.0"
5  title: OpenGnsys REST API definition
6  description: |
7    Information about the OpenGnsys REST API functions (including Server and
8    Repository Manager).
9  contact:
10    name: OpenGnsys Project
11    url: http://opengnsys.es/
12  license:
13    name: Creative Commons 4.0 International
14    url: http://creativecommons.org/licenses/by/4.0/
15basePath: /opengnsys/rest
16schemes:
17  - https
18consumes:
19  - application/json
20produces:
21  - application/json
22securityDefinitions:
23  apikey:
24    type: apiKey
25    name: Authorization
26    in: header
27# Paths description.
28paths:
29  /login:
30    post:
31      description: Check user login and returns his/her API key.
32      parameters:
33        - in: body
34          name: authdata
35          description: JSON authentication data
36          required: true
37          schema:
38            type: object
39            properties:
40              username:
41                type: string
42              password:
43                type: string
44                format: password
45      responses:
46        "200":
47          description: Successful login
48          schema:
49            type: object
50            properties:
51              userid:
52                type: integer
53                description: user identificator
54                format: int32
55              apikey:
56                description: API key to include in ``Authorization`` header
57                type: string
58        "400":
59          description: Missing parameters
60        "500":
61          description: Authentication error
62      tags:
63        - server
64        - user
65  /status:
66    get:
67      description: Gets OpenGnsys Server status information
68      responses:
69        "200":
70          description: Successful response
71          schema:
72            type: object
73            properties:
74              memInfo:
75                description: memory information
76                properties:
77                  total:
78                    description: total amount of memory
79                    type: integer
80                    format: int64
81                  used:
82                    description: amount of used memory
83                    type: integer
84                    format: int64
85                required: [ total, used ]
86              cpu:
87                description: CPU information
88                properties:
89                  model:
90                    description: processor model
91                    type: string
92                  usage:
93                    description: average of processor load
94                    type: number
95                    format: float
96                required: [ model, usage ]
97            required: [ memInfo, cpu ]
98      tags:
99        - server
100  /ous:
101    get:
102      description: Gets all `OU` objects.
103      responses:
104        "200":
105          description: Successful response
106          schema:
107            type: array
108            items:
109              type: object
110              properties:
111                id:
112                  type: integer
113                  description: Organization Unit identificator
114                  format: int32
115                  minimum: 1
116                name:
117                  type: string
118                  description: Organization Unit name
119              required: [ id, name ]
120      tags:
121        - server
122        - ou
123  /ous/{ouid}:
124    get:
125      description: Get an `OU` object.
126      parameters:
127        - name: ouid
128          in: path
129          description: Organization Unit identificator
130          required: true
131          type: integer
132      responses:
133        "200":
134          description: Successful response
135          schema:
136            type: object
137            properties:
138              id:
139                type: integer
140                description: OU identificator
141              name:
142                type: string
143                description: OU name
144              description:
145                type: string
146                description: OU description
147            required: [ id, name, description ]
148      security:
149        - apikey: []
150      tags:
151        - server
152        - ou
153  /ous/{ouid}/groups:
154    get:
155      description: Get all group of labs defined in an `OU` object.
156      parameters:
157        - name: ouid
158          in: path
159          description: Organization Unit identificator
160          required: true
161          type: integer
162      responses:
163        "200":
164          description: Successful response
165          schema:
166            type: array
167            items:
168              type: object
169              properties:
170                id:
171                  description: group identificator
172                  type: integer
173                  format: int32
174                name:
175                  description: group name
176                  type: string
177                type:
178                  description: group type
179                  type: integer
180                comments:
181                  description: extra comments
182                  type: string
183                parent:
184                  description: parent group
185                  type: object
186                  properties:
187                    id:
188                      description: parent group identificator
189                      type: integer
190                      format: int32
191              required: [ id, name, comments ]
192      security:
193        - apikey: []
194      tags:
195        - server
196        - ou
197  /ous/{ouid}/labs:
198    get:
199      description: Get all `lab` objects defined in an `OU`.
200      parameters:
201        - name: ouid
202          in: path
203          description: OU identificator
204          required: true
205          type: integer
206      responses:
207        "200":
208          description: Successful response
209          schema:
210            type: array
211            items:
212              type: object
213              properties:
214                id:
215                  type: integer
216                  description: laboratory identificator
217                  format: int32
218                name:
219                  type: string
220                  description: laboratory name
221                inremotepc:
222                  type: boolean
223                  description: laboratory usable in Remote PC Project flag
224                group:
225                  type: object
226                  properties:
227                    id:
228                      description: group identificator
229                      type: integer
230                      format: int32
231                ou:
232                  type: object
233                  properties:
234                    id:
235                      description: OU identificator
236                      type: integer
237                      format: int32
238              required: [ id, name; inremotepc, ou ]
239      security:
240        - apikey: []
241      tags:
242        - server
243        - lab
244  /ous/{ouid}/labs/{labid}:
245    get:
246      description: Get a `lab` object.
247      parameters:
248        - name: ouid
249          in: path
250          description: OU identificator
251          required: true
252          type: integer
253        - name: labid
254          in: path
255          description: laboratory identificator
256          required: true
257          type: integer
258      responses:
259        "200":
260          description: Successful response
261          schema:
262            type: object
263            properties:
264              id:
265                description: laboratory identificator
266                type: integer
267                format: int32
268              name:
269                description: laboratory name
270                type: string
271              location:
272                description: laboratory location
273                type: string
274              description:
275                description: laboratory description
276                type: string
277              inremotepc:
278                description: check if this lab can be included in Remote PC Project
279                type: boolean
280              capacity:
281                description: maximum number of people in the lab
282                type: integer
283                format: int32
284              defclients:
285                description: number of defined clients in the lab
286                type: integer
287                format: int32
288              projector:
289                description: check if this lab has a projector
290                type: boolean
291              board:
292                description: check if this lab has an electronic board
293                type: boolean
294              routerip:
295                description: lab router IP address
296                type: string
297              netmask:
298                description: network mask to use in the lab
299                type: string
300              ntp:
301                description: NTP server IP address
302                type: string
303              dns:
304                description: DNS server IP address
305                type: string
306              proxyurl:
307                description: Proxy server URL
308                type: string
309              mcastmode:
310                description: Multicast protocol mode (full-duplex, half-duplex).
311                type: string
312                enum: [ "full-duplex", "half-duplex" ]
313                default: "full-duplex"
314              mcastip:
315                description: Multicast IP address
316                type: string
317              mcastport:
318                description: Multicast port
319                type: integer
320                format: int32
321              mcastspeed:
322                description: Multicast speed (in Mbps)
323                type: integer
324                format: int32
325              p2pmode:
326                description: Bittorrent connection type ("peer", "leecher". "seeder").
327                type: string
328              p2ptime:
329                description: Bittorrent connection extra time (in s.)
330                type: integer
331                format: int32
332              image:
333                description: Lab's picture file
334                type: string
335            required: [ id, name, location, description, inremotepc, capacity, defclients, projector, board, routerip, netmask, modomul, mcastip, mcastport, mcastspeed, p2pmode, p2ptime, image ]
336      security:
337        - apikey: []
338      tags:
339        - server
340        - lab
341  /ous/{ouid}/labs/{labid}/clients:
342    get:
343      description: Get all `client` objects defined in an `lab`.
344      parameters:
345        - name: ouid
346          in: path
347          description: OU identificator
348          required: true
349          type: integer
350        - name: labid
351          in: path
352          description: Lab identificator
353          required: true
354          type: integer
355      responses:
356        "200":
357          description: Successful response
358          schema:
359            type: array
360            items:
361              type: object
362              properties:
363                id:
364                  description: client identificator
365                  type: integer
366                  format: int32
367                name:
368                  description: client name
369                  type: string
370                ip:
371                  description: client IP address
372                  type: string
373                mac:
374                  description: client MAC (Ethernet) address
375                  type: string
376                ou:
377                  type: object
378                  properties:
379                    id:
380                      type: integer
381                      format: int32
382                lab:
383                  type: object
384                  properties:
385                    id:
386                      type: integer
387                      format: int32
388              required: [ id, name, ip, mac, ou, lab ]
389      security:
390        - apikey: []
391      tags:
392        - server
393        - client
394  /ous/{ouid}/labs/{labid}/clients/{clientid}:
395    get:
396      description: Get a `client` object.
397      parameters:
398        - name: ouid
399          in: path
400          description: OU identificator
401          required: true
402          type: integer
403        - name: labid
404          in: path
405          description: Lab identificator
406          required: true
407          type: integer
408        - name: clientid
409          in: path
410          description: Client identificator
411          required: true
412          type: integer
413      responses:
414        "200":
415          description: Successful response
416          schema:
417            type: object
418            properties:
419              id:
420                description: client id
421                type: integer
422                format: int32
423              name:
424                description: client name
425                type: string
426              serialno:
427                description: client serial number
428                type: string
429              netiface:
430                description: main network interface
431                type: string
432              netdriver:
433                description: client MAC address (kernel module)
434                type: string
435              mac:
436                description: client MAC address
437                type: string
438              ip:
439                description: client IP address
440                type: string
441              netmask:
442                description: subnet mask address
443                type: string
444              routerip:
445                description: network router IP address
446                type: string
447              repo:
448                description: repository identification
449                type: object
450                properties:
451                  id:
452                    type: integer
453                    format: int32
454              validation:
455                description: boot validation flag
456                type: boolean
457              boottype:
458                description: boot template type
459                type: string
460              image:
461                description: client's picture file
462                type: string
463            required: [ id, name, serialno, netiface, netdriver, mac, ip, netmask, routerip, repo, validation, image ]
464      security:
465        - apikey: []
466      tags:
467        - server
468        - client
469  /ous/{ouid}/labs/{labid}/clients/{clientid}/hardware:
470    get:
471      description: Get the hardware definition of a `client` object.
472      parameters:
473        - name: ouid
474          in: path
475          description: OU identificator
476          required: true
477          type: integer
478        - name: labid
479          in: path
480          description: Lab identificator
481          required: true
482          type: integer
483        - name: clientid
484          in: path
485          description: Client identificator
486          required: true
487          type: integer
488      responses:
489        "200":
490          description: Successful response
491          schema:
492            type: object
493            properties:
494              id:
495                description: client id
496                type: integer
497                format: int32
498              name:
499                description: client name
500                type: string
501              hardware:
502                description: hardware components
503                type: array
504                items:
505                  type: object
506                  properties:
507                    type:
508                      description: hardware component type
509                      type: string
510                    description:
511                      description: hardware component description
512                      type: string
513                  required: [ type, description ]
514            required: [ id, name, hardware ]
515      security:
516        - apikey: []
517      tags:
518        - server
519        - client
520  /ous/{ouid}/labs/{labid}/clients/{clientid}/diskcfg:
521    get:
522      description: Get disks configuration of a `client`
523      parameters:
524        - name: ouid
525          in: path
526          description: OU identificator
527          required: true
528          type: integer
529        - name: labid
530          in: path
531          description: Lab identificator
532          required: true
533          type: integer
534        - name: clientid
535          in: path
536          description: Client identificator
537          required: true
538          type: integer
539      responses:
540        "200":
541          description: Successful response
542          schema:
543            type: object
544            properties:
545              id:
546                description: client id
547                type: integer
548                format: int32
549              name:
550                description: client name
551                type: string
552              diskcfg:
553                description: |
554                  array of disk configuration data, including general disk information and
555                  partition/filesystem information (if not specified in paratmeter
556                  description, it is only valid in partition configuration).
557                type: array
558                items:
559                  type: object
560                  properties:
561                    disk:
562                      description: disk number (only for disks configurations)
563                      type: integer
564                      format: int32
565                    parttable:
566                      description: partition table type (only for disks configurations)
567                      type: string
568                      enum: [ "MSDOS", "GPT", "LVM", "ZVOL" ]
569                    partition:
570                      description: partition number
571                      type: integer
572                      format: int32
573                      minimum: 1
574                    parttype:
575                      description: partition type
576                      type: string
577                    size:
578                      description: disk size (used in both, disk and partition configuration)
579                      type: integer
580                      format: int64
581                    filesystem:
582                      description: filesystem type
583                      type: string
584                    usage:
585                      description: data usage percentage in a formated filesystem
586                      type: integer
587                      format: int32
588                    os:
589                      description: installed operating system
590                      type: string
591                    image:
592                      description: restaured image data (if needed)
593                      type: object
594                      properties:
595                        id:
596                          type: integer
597                          format: int32
598                        deploydate:
599                          description: image restauration/deploying date
600                          type: string
601                          format: date-time
602                        updated:
603                          description: flag to check if the restaured image is updated
604                          type: boolean
605            required: [ id, name, diskcfg ]
606      security:
607        - apikey: []
608      tags:
609        - server
610        - client
611  /ous/{ouid}/labs/{labid}/clients/{clientid}/status:
612    get:
613      description: Get execution status of a `client`
614      parameters:
615        - name: ouid
616          in: path
617          description: OU identificator
618          required: true
619          type: integer
620        - name: labid
621          in: path
622          description: Lab identificator
623          required: true
624          type: integer
625        - name: clientid
626          in: path
627          description: Client identificator
628          required: true
629          type: integer
630      responses:
631        "200":
632          description: Successful response
633          schema:
634            type: object
635            properties:
636              id:
637                description: client id
638                type: integer
639                format: int32
640              ip:
641                description: client IP address
642                type: string
643              status:
644                description: execution status
645                type: string
646                enum: [ "nodata", "off", "ogclient", "busy", "linux", "windows", "unknown" ]
647              loggedin:
648                description: flag to check if an user is logged in
649                type: boolean
650      security:
651        - apikey: []
652      tags:
653        - server
654        - client
655  /ous/{ouid}/repos:
656    get:
657      description: Get all `repo` objects defined in an `OU`.
658      parameters:
659        - name: ouid
660          in: path
661          description: OU identificator
662          required: true
663          type: integer
664      responses:
665        "200":
666          description: Successful response
667          schema:
668            type: array
669            items:
670              type: object
671              properties:
672                id:
673                  type: integer
674                  format: int32
675                name:
676                  type: string
677                ou:
678                  type: object
679                  properties:
680                    id:
681                      type: integer
682                      format: int32
683      security:
684        - apikey: []
685      tags:
686        - server
687        - repo
688  /ous/{ouid}/repos/{repoid}:
689    get:
690      description: Get a `repo` object.
691      parameters:
692        - name: ouid
693          in: path
694          description: OU identificator
695          required: true
696          type: integer
697        - name: repoid
698          in: path
699          description: repository identificator
700          required: true
701          type: integer
702      responses:
703        "200":
704          description: Successful response
705          schema:
706            type: object
707            properties:
708              id:
709                description: repository id
710                type: integer
711                format: int32
712              name:
713                description: repository name
714                type: string
715              description:
716                description: repository description
717                type: string
718              ip:
719                description: repository IP address
720                type: string
721      security:
722        - apikey: []
723      tags:
724        - server
725        - repo
726  /ous/{ouid}/images:
727    get:
728      description: Get all `image` objects defined in an `OU`.
729      parameters:
730        - name: ouid
731          in: path
732          description: OU identificator
733          required: true
734          type: integer
735      responses:
736        "200":
737          description: Successful response
738          schema:
739            type: array
740            items:
741              type: object
742              properties:
743                id:
744                  type: integer
745                  format: int32
746                name:
747                  type: string
748                inremotepc:
749                  type: boolean
750                ou:
751                  type: object
752                  properties:
753                    id:
754                      type: integer
755                      format: int32
756      security:
757        - apikey: []
758      tags:
759        - server
760        - image
761  /ous/{ouid}/images/{imageid}:
762    get:
763      description: Get an `image` object.
764      parameters:
765        - name: ouid
766          in: path
767          description: OU identificator
768          required: true
769          type: integer
770        - name: imageid
771          in: path
772          description: image definition identificator
773          required: true
774          type: integer
775      responses:
776        "200":
777          description: Successful response
778          schema:
779            type: object
780            properties:
781              id:
782                description: image id
783                type: integer
784                format: int32
785              name:
786                description: image name
787                type: string
788              description:
789                description: image description
790                type: string
791              inremotepc:
792                description: image usable in Remote PC Project flag
793                type: boolean
794              type:
795                description: image type (``monolithic``, ``basic``, ``incremental``)
796                type: string
797              baseimg:
798                description: base image for an incremental image (if ``type`` is ``incremental``)
799                type: string
800              path:
801                description: image path (if ``type`` is ``incremental``)
802                type: string
803              repo:
804                description: repository identification
805                type: object
806                properties:
807                  id:
808                    type: integer
809                    format: int32
810              client:
811                description: model client's data
812                type: object
813                properties:
814                  id:
815                    description: model client's id.
816                    type: integer
817                    format: int32
818                  disk:
819                    description: source disk number
820                    type: integer
821                    format: int32
822                  partition:
823                    description: source partition number
824                    type: integer
825                    format: int32
826              creationdate:
827                description: image creation date
828                type: string
829                format: date-time
830              release:
831                description: image creation release
832                type: string
833      security:
834        - apikey: []
835      tags:
836        - server
837        - image
838  /ous/{ouid}/images/{imageid}/software:
839    get:
840      description: Get software inventory store into an `image`
841      parameters:
842        - name: ouid
843          in: path
844          description: OU identificator
845          required: true
846          type: integer
847        - name: imageid
848          in: path
849          description: image definition identificator
850          required: true
851          type: integer
852      responses:
853        "200":
854          description: Successful response
855          schema:
856            type: object
857            properties:
858              id:
859                description: image id
860                type: integer
861                format: int32
862              name:
863                description: image name
864                type: string
865              os:
866                description: installed operating system
867                type: string
868              software:
869                description: array of installed applications
870                type: array
871                items:
872                  type: object
873                  properties:
874                    application:
875                      description: application name and version
876                      type: string
877      security:
878        - apikey: []
879      tags:
880        - server
881        - image
882  #/ous/{ouid}/images/{imageid}/boot:
883  #/repository/images
884  #/repository/poweron
885  /ogagent/started:
886    post:
887      description: Process push notification when OGAgent is started
888      parameters:
889        - in: body
890          name: data
891          description: Operation data
892          required: true
893          schema:
894            type: object
895            properties:
896              ip:
897                type: string
898              mac:
899                type: string
900              ostype:
901                type: string
902              osversion:
903                type: string
904              secret:
905                type: string
906      responses:
907        "200":
908          description: Successful operation
909        "400":
910          description: An error has occurred
911      tags:
912        - server
913        - agent
914  /ogagent/stopped:
915    post:
916      description: Process push notification when OGAgent is stopped
917      parameters:
918        - in: body
919          name: data
920          description: Operation data
921          required: true
922          schema:
923            type: object
924            properties:
925              ip:
926                type: string
927              mac:
928                type: string
929              ostype:
930                type: string
931              osversion:
932                type: string
933      responses:
934        "200":
935          description: Successful operation
936        "400":
937          description: An error has occurred
938      tags:
939        - server
940        - agent
941  /ogagent/loggedin:
942    post:
943      description: Process push notification when an user logged in
944      parameters:
945        - in: body
946          name: data
947          description: Operation data
948          required: true
949          schema:
950            type: object
951            properties:
952              ip:
953                type: string
954              user:
955                type: string
956      responses:
957        "200":
958          description: Successful operation
959        "400":
960          description: An error has occurred
961      tags:
962        - server
963        - agent
964  /ogagent/loggedout:
965    post:
966      description: Process push notification when an user is logged in
967      parameters:
968        - in: body
969          name: data
970          description: Operation data
971          required: true
972          schema:
973            type: object
974            properties:
975              ip:
976                type: string
977              user:
978                type: string
979      responses:
980        "200":
981          description: Successful operation
982        "400":
983          description: An error has occurred
984      tags:
985        - server
986        - agent
Note: See TracBrowser for help on using the repository browser.