Restfully is a general-purpose client library for RESTful APIs. It is written in Ruby. Its goal is to abstract the nitty-gritty details of exchanging HTTP requests between the user-agent and the server. It also discovers resources at runtime, which means should the API change and add a new functionality, the client will automatically discover it.
It works on simple concepts:
- All APIs are made of resources, and collections of resources.
- The media-type of a resource dictates the relationships between that resource and the other resources, and what it is possible to do with them.
Therefore, Restfully can work with any reasonably RESTful API provided that:
- The API returns semantically correct HTTP status codes;
- The API make use of
- The API returns a valid
Content-Typeheader in all responses;
- The API returns a
LocationHTTP header on 201 and 202 responses;
- The API returns links to other resources in all responses (the so-called HATEOAS constraint of REST).
If one of the API
Content-Type is not already supported by one of the
Restfully::MediaType objects (see
lib/restfully/media_type), then you just have to build it and register it with Restfully.
Documentation can be found at http://rubydoc.info/gems/restfully.
$ gem install restfully
If you require media-types that need an XML parser, you must also install the
$ gem install libxml-ruby
$ export RUBYOPT="-rubygems" $ restfully --uri URI [-u username] [-p password]
e.g., for the Grid'5000 API:
$ restfully --uri https://api.grid5000.fr/sid/grid5000 -u username -p password
If the connection was successful, you should get a prompt. You may enter:
ruby-1.8.7-p249 > pp root #<Resource:0x8108399c uri=https://api.grid5000.fr/sid/grid5000 RELATIONSHIPS environments, self, sites, version, versions PROPERTIES "uid"=>"grid5000" "type"=>"grid" "version"=>"da6abdd13e2e626f64502a648b784372eac790b1"> => nil
And then follow the links advertised under the
RELATIONSHIPS header to discover the other API resources. For instance, the
sites resource can be accessed as follows:
ruby-1.8.7-p249 > pp root.sites #<Collection:0x8106d55c uri=https://api.grid5000.fr/sid/grid5000/sites RELATIONSHIPS self, version, versions ITEMS (0..9)/9 #<Resource:0x81055a9c uri=https://api.grid5000.fr/sid/grid5000/sites/bordeaux> #<Resource:0x81040d54 uri=https://api.grid5000.fr/sid/grid5000/sites/grenoble> #<Resource:0x8102c070 uri=https://api.grid5000.fr/sid/grid5000/sites/lille> #<Resource:0x8101738c uri=https://api.grid5000.fr/sid/grid5000/sites/lyon> #<Resource:0x81002658 uri=https://api.grid5000.fr/sid/grid5000/sites/nancy> #<Resource:0x80fed924 uri=https://api.grid5000.fr/sid/grid5000/sites/orsay> #<Resource:0x80fd8bb4 uri=https://api.grid5000.fr/sid/grid5000/sites/rennes> #<Resource:0x80fc3dcc uri=https://api.grid5000.fr/sid/grid5000/sites/sophia> #<Resource:0x80faf070 uri=https://api.grid5000.fr/sid/grid5000/sites/toulouse>> => nil
Note that we're using
pp to pretty-print the output, but it's not required.
A Collection is a specific kind of Resource, and it has access to all the methods provided by the Ruby Enumerable module.
For ease of use and better security, you may prefer to use a configuration file to avoid re-entering the Restfully options every time:
$ echo ' uri: https://api.grid5000.fr/sid/grid5000 username: MYLOGIN password: MYPASSWORD ' > ~/.restfully/api.grid5000.fr.yml && chmod 600 ~/.restfully/api.grid5000.fr.yml
$ restfully -c ~/.restfully/api.grid5000.fr.yml
If you want to record the commands you enter in your interactive session, just
--record flag, and at the end of your session the commands you
entered will have been written into
SESSION_FILE (by default:
Note: depending on your Readline installation, you might see the following message: "Bond has detected EditLine and may not work with it. See the README's Limitations section". You can safely ignore it.
Restfully can replay a sequence of ruby expressions. Just pass the FILE (local
or HTTP URI) as argument to the
$ restfully -c ~/.restfully/my-config.yml path/to/file.rb $ restfully -c ~/.restfully/my-config.yml http://server.ltd/script.rb
Or via STDIN:
$ echo "pp root" | restfully -c ~/.restfully/config.yml
Don't hesitate to play with the
--replay option, which outputs the content of the FILE line by line, and the result of each expression.
By default, the program exits when the content of the FILE has been executed.
--shell flag to keep a shell open in the same Restfully session
after FILE has been executed. This is useful if you want to manipulate the
variables defined by the FILE.
Also, note that any
Restfully::Session.new(...) declaration in the code you
execute will have its configuration overridden with anything given on the
command line (either in a configuration file or as arguments). Therefore you
can easily execute scripts written by others, in your own context.
examples directory for examples.
rake spec; or
autotestin the project directory.
- we use Travis CI on every push:
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it. This is important so I don't break it in a future version unintentionally.
- Commit, do not mess with Rakefile, version, or history (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull).
- Send me a pull request.
Copyright (c) 2009-2012 Cyril Rohr, INRIA Rennes - Bretagne Atlantique.
See LICENSE for details (CeCILL-B, a BSD style license).