README.rdoc in restfully-0.3.2 vs README.rdoc in restfully-0.4.0
- old
+ new
@@ -8,108 +8,98 @@
$ gem install restfully --source http://gemcutter.org
== Usage
=== Command line
$ export RUBYOPT="-rubygems"
- $ restfully base_uri [root_path] [-u username] [-p password]
+ $ restfully base_uri [-u username] [-p password]
e.g., for the Grid5000 API:
- $ restfully https://api.grid5000.fr/sid /grid5000 -u username -p password
+ $ restfully https://api.grid5000.fr/sid/grid5000 -u username -p password
-If the connection was successful, you should get a prompt. Call the +root+ function to see what are the available resources. <tt>@property</tt> means that you can call the +property+ method on the object. Other properties are available via the <tt>[]</tt> function.
-e.g.:
- irb(main):005:0> root
- => #<Restfully::Resource:0x8848de
- ------------ META ------------
- @uri: #<URI::Generic:0x11091a8 URL:/grid5000>
- @uid: "grid5000"
- @type: "grid"
- @environments: Restfully::Collection
- @sites: Restfully::Collection
- @version: Restfully::Resource
- @versions: Restfully::Collection
- ------------ PROPERTIES ------------
- "version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
-
- irb(main):006:0> root.uri
- => #<URI::Generic:0x11091a8 URL:/grid5000>
-
- irb(main):007:0> root.sites
- => #<Restfully::Collection:0x881f6c
- ------------ META ------------
- @uri: "/grid5000/sites"
- @offset: 0
- @total: 9
- @version: Restfully::Resource
- @versions: Restfully::Collection
- ------------ PROPERTIES ------------
- "version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8"
- ------------ ITEMS ------------
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource
- Restfully::Resource>
-
- irb(main):008:0> root.sites.by_uid('rennes').clusters.by_uid('paradent').nodes.by_uid('paradent-1').metrics.by_uid('mem_free', 'cpu_idle', 'bytes_in')
- => [#<Restfully::Resource:0x4259a
- ------------ META ------------
- @uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/mem_free"
- @uid: "mem_free"
- @type: "metric"
- @parent: Restfully::Resource
- @timeseries: Restfully::Resource
- ------------ PROPERTIES ------------
- "last_update" => -901639018
- "step" => 15
- "timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0x12444
- ------------ META ------------
- @uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/cpu_idle"
- @uid: "cpu_idle"
- @type: "metric"
- @parent: Restfully::Resource
- @timeseries: Restfully::Resource
- ------------ PROPERTIES ------------
- "last_update" => -901639018
- "step" => 15
- "timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0xe4c870
- ------------ META ------------
- @uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/bytes_in"
- @uid: "bytes_in"
- @type: "metric"
- @parent: Restfully::Resource
- @timeseries: Restfully::Resource
- ------------ PROPERTIES ------------
- "last_update" => -901639018
- "step" => 15
- "timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>]
-
- irb(main):009:0> root.version
- => #<Restfully::Resource:0x8facf0
- ------------ META ------------
- @uri: "/grid5000/versions/ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
- @uid: "ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
- @type: "version"
- @parent: Restfully::Resource
- ------------ PROPERTIES ------------
- "author" => "Cyril Constantin <>"
- "date" => "Fri, 11 Sep 2009 14:32:48 GMT"
- "message" => "[environments] update of environments on sites">
+If the connection was successful, you should get a prompt. You may enter
+ irb(main):001:0> pp root
-You may also prefer to use a configuration file to avoid entering the command line options:
+to get back a pretty-printed output of the root resource:
+#<Restfully::Resource:0x91f08c
+ @uri=#<URI::HTTP:0x123e30c URL:http://api.local/sid/grid5000>
+ LINKS
+ @environments=#<Restfully::Collection:0x917666>,
+ @sites=#<Restfully::Collection:0x9170d0>,
+ @version=#<Restfully::Resource:0x91852a>,
+ @versions=#<Restfully::Collection:0x917e68>
+ PROPERTIES
+ "uid"=>"grid5000",
+ "type"=>"grid",
+ "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
+
+You can see the LINKS and PROPERTIES headers that respectively indicate what links you can follow from there (by calling +root.link_name+) and what properties are available (by calling +root[property_name]+).
+
+Let's say you want to access the collection of +sites+, you would enter:
+ irb(main):002:0> pp root.sites
+
+and get back:
+ #<Restfully::Collection:0x9170d0
+ @uri=#<URI::HTTP:0x122e128 URL:http://api.local/sid/grid5000/sites>
+ LINKS
+ @version=#<Restfully::Resource:0x8f553e>,
+ @versions=#<Restfully::Collection:0x8f52be>
+ PROPERTIES
+ "total"=>9,
+ "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8",
+ "offset"=>0
+ ITEMS (0..9)/9
+ #<Restfully::Resource:0x9058bc uid="bordeaux">,
+ #<Restfully::Resource:0x903d0a uid="grenoble">,
+ #<Restfully::Resource:0x901cc6 uid="lille">,
+ #<Restfully::Resource:0x8fff0c uid="lyon">,
+ #<Restfully::Resource:0x8fe288 uid="nancy">,
+ #<Restfully::Resource:0x8fc4a6 uid="orsay">,
+ #<Restfully::Resource:0x8fa782 uid="rennes">,
+ #<Restfully::Resource:0x8f8bb2 uid="sophia">,
+ #<Restfully::Resource:0x8f6c9a uid="toulouse">>
+
+A Restfully::Collection is a special kind of Resource, which includes the Enumerable module, which means you can call all of its methods on the Restfully::Collection object. For example:
+ irb(main):003:0> pp root.sites.find{|s| s['uid'] == 'rennes'}
+ #<Restfully::Resource:0x8fa782
+ @uri=#<URI::HTTP:0x11f4e64 URL:http://api.local/sid/grid5000/sites/rennes>
+ LINKS
+ @environments=#<Restfully::Collection:0x8f9ab2>,
+ @parent=#<Restfully::Resource:0x8f981e>,
+ @deployments=#<Restfully::Collection:0x8f935a>,
+ @clusters=#<Restfully::Collection:0x8f9d46>,
+ @version=#<Restfully::Resource:0x8fa354>,
+ @versions=#<Restfully::Collection:0x8fa0b6>,
+ @status=#<Restfully::Collection:0x8f95ee>
+ PROPERTIES
+ "name"=>"Rennes",
+ "latitude"=>48.1,
+ "location"=>"Rennes, France",
+ "security_contact"=>"rennes-staff@lists.grid5000.fr",
+ "uid"=>"rennes",
+ "type"=>"site",
+ "user_support_contact"=>"rennes-staff@lists.grid5000.fr",
+ "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8",
+ "description"=>"",
+ "longitude"=>-1.6667,
+ "compilation_server"=>false,
+ "email_contact"=>"rennes-staff@lists.grid5000.fr",
+ "web"=>"http://www.irisa.fr",
+ "sys_admin_contact"=>"rennes-staff@lists.grid5000.fr">
+
+or:
+ irb(main):006:0> root.sites.map{|s| s['uid']}.grep(/re/)
+ => ["grenoble", "rennes"]
+
+
+To enter the command-line options, you may prefer to use a configuration file to avoid re-entering the options every time you use the client:
$ echo '
- base_uri: https://api.grid5000.fr/sid
- root_path: /grid5000
+ base_uri: https://api.grid5000.fr/sid/grid5000
username: MYLOGIN
password: MYPASSWORD
- ' > ~/somewhere/api.grid5000.fr.yml
+ ' > ~/.restfully/api.grid5000.fr.yml && chmod 600 ~/.restfully/api.grid5000.fr.yml
And then:
- $ restfully -c ~/somewhere/api.grid5000.fr.yml
+ $ restfully -c ~/.restfully/api.grid5000.fr.yml
=== As a library
See the +examples+ directory for examples.
== Note on Patches/Pull Requests