Revision c71a1a3d doc/rapi.rst

b/doc/rapi.rst
34 34
``bulk``
35 35
++++++++
36 36

  
37
Bulk-mode means that for the resources which usually return just a
38
list of child resources (e.g. ``/2/instances`` which returns just
39
instance names), the output will instead contain detailed data for all
40
these subresources. This is more efficient than query-ing the
41
sub-resources themselves.
37
Bulk-mode means that for the resources which usually return just a list
38
of child resources (e.g. ``/2/instances`` which returns just instance
39
names), the output will instead contain detailed data for all these
40
subresources. This is more efficient than query-ing the sub-resources
41
themselves.
42 42

  
43 43
``dry-run``
44 44
+++++++++++
......
47 47
integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
48 48
should not be executed, only the pre-execution checks will be done.
49 49

  
50
This is useful in trying to determine (without guarantees though, as
51
in the meantime the cluster state could have changed) if the operation
52
is likely to succeed or at least start executing.
50
This is useful in trying to determine (without guarantees though, as in
51
the meantime the cluster state could have changed) if the operation is
52
likely to succeed or at least start executing.
53 53

  
54 54
``force``
55 55
+++++++++++
......
60 60
Usage examples
61 61
--------------
62 62

  
63
You can access the API using your favorite programming language as
64
long as it supports network connections.
63
You can access the API using your favorite programming language as long
64
as it supports network connections.
65 65

  
66 66
Shell
67 67
+++++
......
80 80
Python
81 81
++++++
82 82

  
83
.. highlight: python
83
.. highlight:: python
84

  
85
::
84 86

  
85 87
  import urllib2
86 88
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
......
91 93
++++++++++
92 94

  
93 95
.. warning:: While it's possible to use JavaScript, it poses several
94
  potential problems, including browser blocking request due to
95
  non-standard ports or different domain names. Fetching the data on
96
  the webserver is easier.
96
   potential problems, including browser blocking request due to
97
   non-standard ports or different domain names. Fetching the data on
98
   the webserver is easier.
97 99

  
98 100
.. highlight:: javascript
99 101

  
......
230 232
      }
231 233
    ]
232 234

  
233
If the optional *bulk* argument is provided and set to a true value
234
(i.e ``?bulk=1``), the output contains detailed information about
235
instances as a list.
235
If the optional *bulk* argument is provided and set to a true value (i.e
236
``?bulk=1``), the output contains detailed information about instances
237
as a list.
236 238

  
237 239
Example::
238 240

  
......
271 273

  
272 274
If the optional *dry-run* argument is provided and set to a positive
273 275
integer valu (e.g. ``?dry-run=1``), the job will not be actually
274
executed, only the pre-execution checks will be done. Query-ing the
275
job result will return, in both dry-run and normal case, the list of
276
nodes selected for the instance.
276
executed, only the pre-execution checks will be done. Query-ing the job
277
result will return, in both dry-run and normal case, the list of nodes
278
selected for the instance.
277 279

  
278 280
Returns: a job ID that can be used later for polling.
279 281

  
......
423 425

  
424 426
Delete a tag.
425 427

  
426
In order to delete a set of tags, the DELETE request should be
427
addressed to URI like::
428
In order to delete a set of tags, the DELETE request should be addressed
429
to URI like::
428 430

  
429 431
    /tags?tag=[tag]&tag=[tag]
430 432

  
......
464 466

  
465 467
- id: job ID as a number
466 468
- status: current job status as a string
467
- ops: involved OpCodes as a list of dictionaries for each
468
  opcodes in the job
469
- ops: involved OpCodes as a list of dictionaries for each opcodes in
470
  the job
469 471
- opstatus: OpCodes status as a list
470 472
- opresult: OpCodes results as a list of lists
471 473

  
......
499 501
      }
500 502
    ]
501 503

  
502
If the optional 'bulk' argument is provided and set to 'true' value
503
(i.e '?bulk=1'), the output contains detailed information about nodes
504
as a list.
504
If the optional 'bulk' argument is provided and set to 'true' value (i.e
505
'?bulk=1'), the output contains detailed information about nodes as a
506
list.
505 507

  
506 508
Example::
507 509

  
......
662 664

  
663 665
Deletes tags.
664 666

  
665
In order to delete a set of tags, the DELETE request should be
666
addressed to URI like::
667
In order to delete a set of tags, the DELETE request should be addressed
668
to URI like::
667 669

  
668 670
    /tags?tag=[tag]&tag=[tag]
669 671

  
......
683 685
Return a list of all OSes.
684 686

  
685 687
Can return error 500 in case of a problem. Since this is a costly
686
operation for Ganeti 2.0, it is not recommended to execute it too
687
often.
688
operation for Ganeti 2.0, it is not recommended to execute it too often.
688 689

  
689 690
Example::
690 691

  
......
722 723

  
723 724
Deletes tags.
724 725

  
725
In order to delete a set of tags, the DELETE request should be
726
addressed to URI like::
726
In order to delete a set of tags, the DELETE request should be addressed
727
to URI like::
727 728

  
728 729
    /tags?tag=[tag]&tag=[tag]
729 730

  
......
735 736

  
736 737
The version resource.
737 738

  
738
This resource should be used to determine the remote API version and
739
to adapt clients accordingly.
739
This resource should be used to determine the remote API version and to
740
adapt clients accordingly.
740 741

  
741 742
It supports the following commands: ``GET``.
742 743

  
743 744
``GET``
744 745
~~~~~~~
745 746

  
746
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
747
2.0 returns ``2``.
747
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
748
returns ``2``.
748 749

  
749 750
.. vim: set textwidth=72 :
751
.. Local Variables:
752
.. mode: rst
753
.. fill-column: 72
754
.. End:

Also available in: Unified diff