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

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 566e84f was 3551804, checked in by ramon <ramongomez@…>, 9 years ago

#708: Separar funciones y rutas REST comunes; nueva ruta /info con información de versión y servicios activos.

git-svn-id: https://opengnsys.es/svn/branches/version1.1@5096 a21b9725-9963-47de-94b9-378ad31fedc9

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