terminal.com 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d256dec7f902f6e53bebf75cedb4231ba0123e1b
-  data.tar.gz: 51cc71d632d28a9b840eaf67a7a353363e8f76fa
+  metadata.gz: 521390d3deda294db938d225e60be0f78a8d2be8
+  data.tar.gz: c63f9ecdb2493e5d48c62d9d357bdd5f7bf186c7
 SHA512:
-  metadata.gz: fb2b0d8e464a88d836015e20984aa000b8304f5dab8ae783a087324b90f19c49ff9a0b4d7a3a99cc50481e986b5b11a771763f73560ab0820915efa189e9f516
-  data.tar.gz: d06615df3b69e26cf1645ed40bc4081fb18a566c163b520b9142893b44459da3724096ce9daffdec6fef60c738f4e928a76b7780baa57f53265b8d62407aebf5
+  metadata.gz: 92ce68a65b841d4f2e1b5cd05550750bd041b4d751a9b96063af1ba991568b7b7fdc81ab359f0177ef25ca34774081173dca6eee58df2bdbb236dd04113b8375
+  data.tar.gz: 3b4bfffaef11a6628a86436085e923cac5937b5e2a71c29369edfc681fabfeb7baf87fcdf91902e5c968f7168b8bf9d761c356e59fe021891e81902fcdd1ffed

data/README.md

@@ -1,10 +1,19 @@
 # About
 
-This is a Ruby wrapper for [Terminal.com](https://www.terminal.com) API.
+[![Travis CI Status](https://img.shields.io/travis/botanicus/terminal.com.svg)](https://travis-ci.org/botanicus/terminal.com)
+![Gem Version](https://badge.fury.io/rb/terminal.com.svg)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/terminal.com/frames)
+![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)
 
-At the moment all it does is to dump all the [Terminal.com API endpoints](https://www.terminal.com/api/docs) to `Terminal::API` module, from which you can call them pretty much the same way you'd do with curl, just from Ruby.
+This is a Ruby wrapper for [Terminal.com](https://www.terminal.com) API. It works on **Ruby 2 compatible implementations** (_including Rubinius and JRuby_). Ruby 1.8 or 1.9 are not supported. It contains:
 
-In the future there will be more object-oriented abstraction.
+- [Low-level API](#low-level-api) which is 1:1 mapping to Terminal.com endpoints.
+- [High-level object-oriented API](#high-level-terminalapi).
+- [Command-line client](#command-line-client).
+
+This library has **no external dependencies**. You can optionally use it with CodeRay to get syntax-highlighted responses in the command-line client, but the core doesn't depend on any 3rd party library.
+
+The library uses `net/http` for network communication. Writing an adapter for a different HTTP library is as simple as overriding `Terminal.call` method. In the future more HTTP libraries _might_ be supported.
 
 # Usage
 
@@ -12,16 +21,82 @@ In the future there will be more object-oriented abstraction.
 
 2. Get your `user_token` and `access_token` from [your settings](https://www.terminal.com/settings/api).
 
-![](docs/terminal-com-api-keys.png)
+![](https://raw.githubusercontent.com/botanicus/terminal.com/master/docs/terminal-com-api-keys.png)
+
+# API
+
+**API docs:** [Latest release](http://www.rubydoc.info/gems/terminal.com/frames) | [Git HEAD](http://www.rubydoc.info/github/botanicus/terminal.com/master)
+
+## Low-Level API
+
+Module methods exposed on the `Terminal` module are 1:1 mapping of the Terminal.com API. The mapping rules are simple:
+
+- All the required arguments are translated to positional arguments and comes in the same order as they are listed on the [Terminal.com API docs](https://www.terminal.com/api/docs) page.
+- All the optional arguments are specified as keyword arguments (options).
+
+### Example
+
+```ruby
+require 'terminal.com'
+
+# Let's search featured ruby-related snapshots.
+Terminal.list_public_snapshots(tag: 'ruby', featured: true)
+# {"snapshots" => [{"title" => "JRuby Stack (example included)", "body" => "JRuby is a 100% Java implementation of the Ruby programming language. This snapshot also includes a working example, its source code and the tools needed to develop JRuby applications.", ...
+
+# List your Terminals.
+Terminal.list_terminals(my_user_token, my_access_token)
+# {"terminals" => [{"cpu" => "2 (max)", "ram" => "256", "diskspace" => "10", "name" => "Coding Interview: John Doe Jr", ...
+
+# Let's start a small instance of the official Ubuntu 14.04 snapshot.
+snapshot_id = '987f8d702dc0a6e8158b48ccd3dec24f819a7ccb2756c396ef1fd7f5b34b7980'
+Terminal.start_snapshot(my_user_token, my_access_token, snapshot_id, cpu: 100, ram: 1600)
+# {"request_id":"1417456495137::james@101ideas.cz:create:207693::4e765da6-2cc0-4054-a0dc-00b47a004d79"}
+```
+
+## High-Level `Terminal::API`
+
+Class `Terminal::API` provides *abstraction for calls to the endpoints that requires authentication*. So instead of calling methods on `Terminal` every time with passing `user_token` and `access_token` as arguments, you can just instantiate `Terminal::API` and reuse your credentials.
+
+### Example
+
+```ruby
+require 'terminal.com/api'
+
+terminal_com = Terminal::API.new(my_user_token, my_access_token)
+
+# List your Terminals.
+terminal_com.list_terminals
+
+# Let's start a small instance of the official Ubuntu 14.04 snapshot.
+snapshot_id = '987f8d702dc0a6e8158b48ccd3dec24f819a7ccb2756c396ef1fd7f5b34b7980'
+terminal_com.start_snapshot(snapshot_id, instance: 'small')
+
+# Note that for calls that don't require authentication,
+# you still have to use methods on the Terminal module.
+Terminal.list_public_snapshots
+```
 
 # Command-Line Client
 
-Anything you can do from the library can be done through the CLI client. There are two ways how you can use it.
+Anything the library do can be done through the command-line client. There are two ways how you can use it: [with your credentials saved](#with-configuration) in `~/.terminal.com.json` or [without it](#without-configuration).
 
-![](docs/terminal-cli-client.png)
+Arguments are mapped exactly the same way as in the Ruby API:
+
+- All the required arguments are translated to positional arguments and comes in the same order as they are listed on the [Terminal.com API docs](https://www.terminal.com/api/docs) page.
+- All the optional arguments are specified as keyword arguments.
+
+## Keyword Arguments
+
+- Booleans: `--featured` or `--no-featured`.
+- Strings: `--tag=ruby`.
+- Integers `--ram=256`.
+
+![](https://raw.githubusercontent.com/botanicus/terminal.com/master/docs/terminal-cli-client.png)
 
 ## Without Configuration
 
+This is a command-line equivalent of the low-level API: you have to specify `user_token` and `access_token` every single time.
+
 ```bash
 terminal.com [user_token] [access_token] list_terminals
 ```
@@ -30,37 +105,51 @@ terminal.com [user_token] [access_token] list_terminals
 
 ## With Configuration
 
-Specifying the credentials every single time can be quite tedious. That's where `terminal.com configure` comes in handy:
-
-![](docs/terminal-com-configure.png)
+This is a command-line equivalent of the high-level API: your `user_token` and `access_token` are saved in `~/.terminal.com.json`, so you don't have to pass them in every single time.
 
 ```bash
-# One time only.
-terminal.com configure
-
-# Now you can simply do:
 terminal.com list_terminals
 ```
 
-## Options
+### How to Save Your Credentials
 
-```bash
-terminal.com list_public_snapshots --tag=ruby --featured
-```
+Run `terminal.com configure` and follow the instructions.
 
-# Example
+![](https://raw.githubusercontent.com/botanicus/terminal.com/master/docs/terminal-com-configure.png)
 
-```ruby
-require 'terminal.com'
+# Development
 
-# Let's search featured ruby-related snapshots.
-Terminal::API.list_public_snapshots(tag: 'ruby', featured: true)
-# {"snapshots" => [{"title" => "JRuby Stack (example included)", "body" => "JRuby is a 100% Java implementation of the Ruby programming language. This snapshot also includes a working example, its source code and the tools needed to develop JRuby applications.", ...
+## Architecture of the Test Suite
 
-# List your Terminals.
-my_user_token = '...'
-my_access_token = '...'
+The tests don't run against Terminal.com every single time. This is because:
 
-Terminal::API.list_terminals(my_user_token, my_access_token)
-# {"terminals" => [{"cpu" => "2 (max)", "ram" => "256", "diskspace" => "10", "name" => "Coding Interview: John Doe Jr", ...
-```
+- It would take a long time, starting all those Terminals, snapshotting them etc.
+- The setup would just take too long. For instance for testing `list_terminals`, we'd ideally have to delete all the Terminals, then create a few and then test the result.
+
+So this test suite doesn't test the live API. It test only the library itself through testing VCR-cached responses. Many tests will "break" if you delete the VCR files.
+
+Using VCR provides additional benefits:
+
+- You can see _exactly_ which request was fired and what was the exact response. No magic.
+
+## Running Tests
+
+Running `bundle exec rspec` will run either all the examples, or, if there is one or more example tagged with `:focus`, then it will run only those.
+
+_**Hint:** use `fit` or `fdescribe` to easily add focus to a given example or example group._
+
+## Documentation Server
+
+We are using [YARD](http://yardoc.org) for generating API documentation.
+
+If you want to preview the documentation, run  `yard server --reload`.
+
+## Releasing New Version
+
+_**TODO:** There should be some task for this._
+
+# Links
+
+- [Terminal.com API docs](https://www.terminal.com/api/docs)
+- [Latest release API docs](http://www.rubydoc.info/gems/terminal.com/frames)
+- [Git HEAD API docs](http://www.rubydoc.info/github/botanicus/terminal.com/master)

data/bin/terminal.com

@@ -12,9 +12,10 @@ def log(message)
 end
 
 def dbg(command, arguments, **options)
-  log "Terminal::API.#{command}(" +
+  log "Terminal.#{command}(" +
     ("#{arguments.inspect[1..-2]}" unless arguments.empty?).to_s +
-    (", #{options.inspect[1..-2]}" unless options.empty?).to_s +
+    (", " if ! arguments.empty? && ! options.empty?).to_s +
+    ("#{options.inspect[1..-2]}" unless options.empty?).to_s +
     ")\n"
 end
 
@@ -36,10 +37,10 @@ def api_call(command, arguments, options)
   # => [{}]
   if options
     dbg command, arguments, options
-    print_as_json Terminal::API.send(command, *arguments, **options)
+    print_as_json Terminal.send(command, *arguments, **options)
   else
     dbg command, arguments
-    print_as_json Terminal::API.send(command, *arguments)
+    print_as_json Terminal.send(command, *arguments)
   end
 end
 
@@ -127,13 +128,13 @@ if ARGV.empty?
 else
   command = ARGV.shift
 
-  unless Terminal::API.respond_to?(command)
+  unless Terminal.respond_to?(command)
     STDERR.puts("Invalid command '#{command}'.\n\n")
     abort usage
   end
 
   # Not every method requires authentication.
-  method_args = Terminal::API.method(command).parameters.map(&:last)
+  method_args = Terminal.method(command).parameters.map(&:last)
 
   if method_args.include?(:options)
     options = ARGV.reduce(Hash.new) do |buffer, argument|
@@ -156,5 +157,9 @@ else
   arguments << access_token if method_args.include?(:access_token)
   arguments.push(*ARGV)
 
-  api_call(command, arguments, options)
+  begin
+    api_call(command, arguments, options)
+  rescue Terminal::NetworkError
+    abort "It seems that you're offline."
+  end
 end

data/lib/terminal.com.rb

@@ -1,385 +1,1066 @@
+# This is the low-level version of Terminal.com API.
+# All it does is 1:1 mapping of Ruby methods to the API.
+#
+# Methods that require authentication have a more
+# user-friendly, object-oriented API in Terminal::API class.
+
 require 'net/http'
 require 'json'
+require 'time'
 
 module Terminal
-  VERSION = '0.0.1'
-
-  module API
-    extend self
-
-    API_VERSION = 'v0.1'
-    HEADERS = {'Content-Type' => 'application/json'}
-
-    ############################
-    # BROWSE SNAPSHOTS & USERS #
-    ############################
-
-    # https://www.terminal.com/api/docs#get-snapshot
-    def get_snapshot(snapshot_id)
-      call('/get_snapshot', snapshot_id: snapshot_id)
-    end
-
-    # https://www.terminal.com/api/docs#get-profile
-    def get_profile(username)
-      call('/get_profile', username: username)
-    end
-
-    # https://www.terminal.com/api/docs#list-public-snapshots
-    def list_public_snapshots(**options)
-      ensure_options_validity(options,
-        :username, :tag, :featured, :title, :page, :perPage, :sortby)
-
-      call('/list_public_snapshots', options)
-    end
-
-    # https://www.terminal.com/api/docs#count-public-snapshots
-    def count_public_snapshots(**options)
-      ensure_options_validity(options,
-        :username, :tag, :featured, :title)
-
-      call('/count_public_snapshots', options)
-    end
-
-    ###############################
-    # CREATE AND MANAGE TERMINALS #
-    ###############################
 
-    # https://www.terminal.com/api/docs#list-terminals
-    def list_terminals(user_token, access_token)
-      call('/list_terminals',
-        user_token: user_token, access_token: access_token)
-    end
-
-    # https://www.terminal.com/api/docs#get-terminal
-    def get_terminal(user_token, access_token, **options)
-      ensure_options_validity(options, :container_key, :subdomain)
-
-      options.merge!(user_token: user_token, access_token: access_token)
-
-      call('/get_terminal', options)
-    end
-
-    # https://www.terminal.com/api/docs#start-snapshot
-    def start_snapshot(user_token, access_token, snapshot_id, **options)
-      ensure_options_validity(options,
-        :cpu, :ram, :temporary, :name, :autopause, :startup_script, :custom_data)
-
-      options.merge!(user_token: user_token, access_token: access_token, snapshot_id: snapshot_id)
-
-      call('/start_snapshot', options)
+  # The gem version.
+  VERSION = '0.0.2'
+
+  # The Terminal.com API version.
+  API_VERSION = 'v0.1'
+
+  # The default headers for the requests.
+  HEADERS = {'Content-Type' => 'application/json'}
+
+  # Any network error that can potentially occur in Terminal.call
+  # should be encapsulated in this. See {Terminal.call} for implementation
+  # details.
+  #
+  # @api plugin
+  class NetworkError < StandardError
+    attr_reader :original_error
+
+    # @param original_error [Exception] The exception raised by an HTTP library.
+    # @see Terminal.call
+    def initialize(original_error)
+      @original_error = original_error
+      super <<-EOF
+Network error (#{original_error.class}): #{original_error.message}
+      EOF
     end
+  end
 
-    # https://www.terminal.com/api/docs#delete-terminal
-    def delete_terminal(user_token, access_token, container_key)
-      call('/delete_terminal',
-        user_token: user_token, access_token: access_token, container_key: container_key)
-    end
+  # @!group BROWSE SNAPSHOTS & USERS
+
+  # Get information on a snapshot.
+  #
+  # @param snapshot_id [String] Snapshot ID (the last part of the snapshot URL).
+  # @return [Hash] The response data parsed from JSON.
+  # @raise [Terminal::NetworkError] Any network-layer error.
+  #
+  # @example
+  #   Terminal.get_snapshot('987f8d702dc0a6e8158b48ccd3dec24f819a7ccb2756c396ef1fd7f5b34b7980')
+  #   # {"snapshot" => {"title" => "Official Ubuntu 14.04", "tags" => "ubuntu", "createdAt" => "2014-07-23T20:27:41.743Z", ...}}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#get-snapshot Terminal.com API docs
+  def self.get_snapshot(snapshot_id)
+    call('/get_snapshot', snapshot_id: snapshot_id)
+  end
 
-    # https://www.terminal.com/api/docs#restart-terminal
-    def restart_terminal(user_token, access_token, container_key)
-      call('/restart_terminal',
-        user_token: user_token, access_token: access_token, container_key: container_key)
-    end
+  # Get information on a user.
+  #
+  # @param username [String] Any valid username (i. e. `botanicus`).
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.get_profile('botanicus')
+  #   # {"user" => {"name" => "James C Russell", "url" => "https://twitter.com/botanicus", "location" => "London, UK", ...}}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#get-profile Terminal.com API docs
+  def self.get_profile(username)
+    call('/get_profile', username: username)
+  end
 
-    # https://www.terminal.com/api/docs#pause-terminal
-    def pause_terminal(user_token, access_token, container_key)
-      call('/pause_terminal',
-        user_token: user_token, access_token: access_token, container_key: container_key)
-    end
+  # Get a count of public snapshots, optionally filtered.
+  #
+  # @param options [Hash] Filtering options.
+  # @option options :username [String] Any valid username (i. e. `botanicus`).
+  # @option options :tag [String] Any tag (i. e. `ubuntu`).
+  # @option options :featured [true, false] Search only for featured (or non-featured).
+  # @option options :title [String] Title to be *matched* against the existing snapshots.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example Count of all the public snapshots.
+  #   Terminal.count_public_snapshots
+  #   # {"snapshot_count" => 474}
+  #
+  # @example Count of all the featured snapshots.
+  #   Terminal.count_public_snapshots(featured: true)
+  #   # {"snapshot_count" => 135}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#count-public-snapshots Terminal.com API docs
+  def self.count_public_snapshots(**options)
+    ensure_options_validity(options,
+      :username, :tag, :featured, :title)
+
+    call('/count_public_snapshots', options)
+  end
 
-    # https://www.terminal.com/api/docs#resume-terminal
-    def resume_terminal(user_token, access_token, container_key)
-      call('/resume_terminal',
-        user_token: user_token, access_token: access_token, container_key: container_key)
-    end
+  # Get a list of public snapshots, optionally filtered
+  # and/or paginated.
+  #
+  # @param options [Hash] Filtering and pagination options.
+  # @option options (see .count_public_snapshots)
+  # @option options :page [String] Use with `perPage` for pagination.
+  # @option options :perPage [String] Use with `page` for pagination.
+  # @option options :sortby [String] Either `popularity` or `date`.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example Return all the public snapshots.
+  #   Terminal.list_public_snapshots
+  #   # {"snapshots" => [{"title" => "Decision Tree", "tags" => "python,ipython", ...}, {...}]}
+  #
+  # @example Return all the featured snapshots from user botanicus.
+  #   Terminal.list_public_snapshots(username: 'botanicus', featured: true)
+  #
+  # @example Return the first page of the search results with 10 items per page, sorted by date.
+  #   Terminal.list_public_snapshots(tag: 'ubuntu', page: 1, perPage: 10, sortby: 'date')
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#list-public-snapshots Terminal.com API docs
+  def self.list_public_snapshots(**options)
+    ensure_options_validity(options,
+      :username, :tag, :featured, :title, :page, :perPage, :sortby)
+
+    call('/list_public_snapshots', options)
+  end
 
-    # https://www.terminal.com/api/docs#edit-terminal
-    def edit_terminal(user_token, access_token, container_key, **options)
-      ensure_options_validity(options,
-        :cpu, :ram, :diskspace, :name)
+  # @!endgroup
+  # @!group CREATE AND MANAGE TERMINALS
+
+  # Get a list of all Terminal instances owned by your account.
+  #
+  # @param user_token [String] Your user token.
+  # @param access_token [String] Your access token.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.list_terminals(user_token, access_token)
+  #   # {"terminals" => [{"name" => "Coding Interview: John Doe Jr", "ram" => "256", ...}, {...}]}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#list-terminals Terminal.com API docs
+  def self.list_terminals(user_token, access_token)
+    call('/list_terminals',
+      user_token: user_token, access_token: access_token)
+  end
 
-      options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)
+  # Get info about a Terminal instance of yours. You can
+  # specify either `container_key` or `subdomain`.
+  #
+  # @param (see .list_terminals)
+  # @param options [Hash] Provide either `container_key` or `subdomain`.
+  # @option options :container_key [String] A valid container key.
+  #   You can get it through {.list_terminals}.
+  # @option options :subdomain [String] Subdomain of your Terminal (i. e. `johndoe117`).
+  #   You can see it in the address bar when you're in the Terminal IDE or through {.list_terminals}.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example Get Terminal info with a container_key.
+  #   # Using get_terminal directly with list_terminals doesn't really
+  #   # make sense, since you get all the data in list_terminals, so there
+  #   # is no need to call get_terminal. This is just to show how you
+  #   # can get your container key. It works the same with a subdomain.
+  #   terminals = Terminal.list_terminals(user_token, access_token)
+  #   container_key = terminals['terminals'].first['container_key']
+  #
+  #   Terminal.get_terminal(user_token, access_token, container_key: container_key)
+  #   # {"terminal" => {"name" => "Coding Interview: John Doe Jr", "ram" => "256", ...}}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#get-terminal Terminal.com API docs
+  def self.get_terminal(user_token, access_token, **options)
+    ensure_options_validity(options, :container_key, :subdomain)
+
+    options.merge!(user_token: user_token, access_token: access_token)
+
+    call('/get_terminal', options)
+  end
 
-      call('/edit_terminal', options)
-    end
+  # Start a Terminal instance based on a snapshot.
+  #
+  # @param (see .list_terminals)
+  # @param snapshot_id (see .get_snapshot)
+  # @param options [Hash] Configuration of the new Terminal.
+  # @option options :cpu [String] How much CPU is required.
+  #   Has to be one of the available {https://www.terminal.com/faq#instanceTypes instance types}
+  #   and corresponding `:ram` option has to be provided.
+  # @option options :ram [String] How much RAM is required.
+  #   Has to be one of the available {https://www.terminal.com/faq#instanceTypes instance types}
+  #   and corresponding `:cpu` option has to be provided.
+  # @option options :temporary [String] If the Terminal is supposed to be temporary or not.
+  #   {https://www.terminal.com/faq#temporaryTerminals Temporary Terminals} are automatically
+  #   deleted on inactivity.
+  # @option options :name [String] Terminal name.
+  # @option options :autopause [String] Whether the Terminal should be {https://www.terminal.com/faq#idleSettings auto-paused on inactivity}.
+  #   This can be edited later using {.set_terminal_idle_settings}.
+  # @option options :startup_script [String] Shell script to be run once the Terminal is ready.
+  #   As of now it cannot contain newlines, so setting a different interpreter than `/bin/sh` is impossible.
+  # @option options :custom_data [String] Metadata of your Terminal. Anything you need. It will be accessible through {.get_terminal},
+  #   but not from within the Terminal itself.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  # @raise [ArgumentError] If either `ram` or `cpu` is specified. These options has to come together.
+  #
+  # @example
+  #   response = Terminal.start_snapshot(user_token, access_token, "57eff3574ac8d438224dc3aa1c6431a0dbac849a0c254e89be2e758d8113c234", name: "Test")
+  #   # {"request_id" => "1418068796272::james@101ideas.cz:create:234509::333c43ab-f6cc-41a3-8307-0fcc4ea3cfb5"}
+  #   Terminal.request_progress(response['request_id'])
+  #   # {"operation" => "create", "status" => "success", ... }
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#start-snapshot Terminal.com API docs
+  # @see https://www.terminal.com/faq#instanceTypes Terminal Instance types
+  # @see .edit_terminal
+  # @see .set_terminal_idle_settings
+  def self.start_snapshot(user_token, access_token, snapshot_id, **options)
+    ensure_both_cpu_and_ram_are_provided(options)
+    ensure_options_validity(options,
+      :cpu, :ram, :temporary, :name, :autopause, :startup_script, :custom_data)
+
+    options.merge!(user_token: user_token, access_token: access_token, snapshot_id: snapshot_id)
+
+    call('/start_snapshot', options)
+  end
 
-    ###############################
-    # CREATE AND MANAGE SNAPSHOTS #
-    ###############################
+  # Delete a Terminal instance.
+  #
+  # @param (see .list_terminals)
+  # @param container_key [String] A valid container key.
+  #   You can get it through {.list_terminals}.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#delete-terminal Terminal.com API docs
+  def self.delete_terminal(user_token, access_token, container_key)
+    call('/delete_terminal',
+      user_token: user_token, access_token: access_token, container_key: container_key)
+  end
 
-    # https://www.terminal.com/api/docs#list-snapshots
-    def list_snapshots(user_token, access_token, **options)
-      ensure_options_validity(options,
-        :username, :tag, :featured, :title, :page, :perPage)
+  # Reboot a Terminal instance.
+  #
+  # @param (see .delete_terminal)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#restart-terminal Terminal.com API docs
+  def self.restart_terminal(user_token, access_token, container_key)
+    call('/restart_terminal',
+      user_token: user_token, access_token: access_token, container_key: container_key)
+  end
 
-      options.merge!(user_token: user_token, access_token: access_token)
+  # Pause a Terminal instance. The instance will be offline
+  # and inaccessible, and you will not be charged as long as
+  # it remains paused.
+  #
+  # @param (see .delete_terminal)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#pause-terminal Terminal.com API docs
+  def self.pause_terminal(user_token, access_token, container_key)
+    call('/pause_terminal',
+      user_token: user_token, access_token: access_token, container_key: container_key)
+  end
 
-      call('/list_snapshots', options)
-    end
+  # Continue running a Terminal instance. The Terminal will
+  # continue being charged, and will keep running so long
+  # as you maintain a positive balance in your account.
+  #
+  # @param (see .delete_terminal)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#resume-terminal Terminal.com API docs
+  def self.resume_terminal(user_token, access_token, container_key)
+    call('/resume_terminal',
+      user_token: user_token, access_token: access_token, container_key: container_key)
+  end
 
-    # https://www.terminal.com/api/docs#count-snapshots
-    def count_snapshots(user_token, access_token, **options)
-      ensure_options_validity(options,
-        :username, :tag, :featured, :title)
+  # Edit the resources and/or name of a Terminal instance.
+  #
+  # @param (see .delete_terminal)
+  # @param options [Hash] New Terminal configuration.
+  # @option options :cpu [String] How much CPU is required.
+  #   Has to be one of the available {https://www.terminal.com/faq#instanceTypes instance types}
+  #   and corresponding `:ram` option has to be provided.
+  #   This option is required.
+  # @option options :ram [String] How much RAM is required.
+  #   Has to be one of the available {https://www.terminal.com/faq#instanceTypes instance types}
+  #   and corresponding `:cpu` option has to be provided.
+  #   This option is required.
+  # @option options :diskspace [String] How much diskspace is required.
+  #   If you want to set to more than 20 GB, you need 25 MB of ram per GB.
+  #   This option is required.
+  # @option options :name [String] Terminal name.
+  # @return (see .get_snapshot)
+  # @raise (see .start_snapshot)
+  #
+  # @example
+  #   Terminal.edit_terminal(user_token, access_token, "f9954bd3-5da1-4e17-a688-7791d87ceb6e", cpu: "50", ram: "800", diskspace: "10")
+  #   # {"status": "success", "request_id": "1418071005245::james@101ideas.cz:edit:234583::d86c5b44-f716-45d1-85d2-9968fdda15d6"}
+
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#edit-terminal Terminal.com API docs
+  # @see https://www.terminal.com/faq#instanceTypes Terminal Instance types
+  def self.edit_terminal(user_token, access_token, container_key, **options)
+    ensure_both_cpu_and_ram_are_provided(options)
+    ensure_options_present(options, :cpu, :ram, :diskspace)
+
+    ensure_options_validity(options,
+      :cpu, :ram, :diskspace, :name)
+
+    options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)
+
+    call('/edit_terminal', options)
+  end
 
-      options.merge!(user_token: user_token, access_token: access_token)
+  # @!endgroup
+  # @!group CREATE AND MANAGE SNAPSHOTS
+
+  # Get a list of snapshots owned by your account, optionally
+  # filtered by the owner's username, a tag, or the snapshot's
+  # featured status. You may use a combination of filters.
+  #
+  # @param (see .list_terminals)
+  # @param options [Hash] Filtering and pagination options.
+  # @option options (see .list_public_snapshots)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example Return all the snapshots owned by your account.
+  #   Terminal.list_snapshots(user_token, access_token)
+  #   # {"snapshots" => [{"title" => "Decision Tree", "tags" => "python,ipython", ...}, {...}]}
+  #
+  # @example Return all the featured snapshots owned by your account.
+  #   Terminal.list_snapshots(user_token, access_token, featured: true)
+  #
+  # @example Return the first page of the search results with 10 items per page, sorted by date.
+  #   Terminal.list_snapshots(user_token, access_token, tag: 'ubuntu', page: 1, perPage: 10, sortby: 'date')
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#list-snapshots Terminal.com API docs
+  def self.list_snapshots(user_token, access_token, **options)
+    ensure_options_validity(options,
+      :username, :tag, :featured, :title, :page, :perPage)
+
+    options.merge!(user_token: user_token, access_token: access_token)
+
+    call('/list_snapshots', options)
+  end
 
-      call('/count_snapshots', options)
-    end
+  # Get a count of snapshots owned by your account, optionally
+  # filtered by the owner's username, a tag, or the snapshot's
+  # featured status. You may use a combination of filters.
+  #
+  # @param (see .list_terminals)
+  # @param options [Hash] Filtering options.
+  # @option options (see .count_public_snapshots)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example Number of all the snapshots owned by your account.
+  #   Terminal.count_snapshots(user_token, access_token)
+  #   # {"snapshot_count" => 12}
+  #
+  # @example Number of all the featured snapshots owned by your account.
+  #   Terminal.count_public_snapshots(user_token, access_token, featured: true)
+  #   # {"snapshot_count" => 2}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#count-snapshots Terminal.com API docs
+  def self.count_snapshots(user_token, access_token, **options)
+    ensure_options_validity(options,
+      :username, :tag, :featured, :title)
+
+    options.merge!(user_token: user_token, access_token: access_token)
+
+    call('/count_snapshots', options)
+  end
 
-    # https://www.terminal.com/api/docs#delete-snapshot
-    def delete_snapshot(user_token, access_token, snapshot_id)
-      call('/delete_snapshot',
-        user_token: user_token,
-        access_token: access_token,
-        snapshot_id: snapshot_id)
-    end
+  # Delete a snapshot from your account. This cannot be undone.
+  #
+  # @param (see .list_terminals)
+  # @param snapshot_id (see .get_snapshot)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#delete-snapshot Terminal.com API docs
+  def self.delete_snapshot(user_token, access_token, snapshot_id)
+    call('/delete_snapshot',
+      user_token: user_token,
+      access_token: access_token,
+      snapshot_id: snapshot_id)
+  end
 
-    # https://www.terminal.com/api/docs#edit-snapshot
-    def edit_snapshot(user_token, access_token, snapshot_id, **options)
-      ensure_options_validity(options,
-        :body, :title, :readme, :tags, :public, :custom_data)
+  # Edit the metadata of a snapshot owned by your account.
+  #
+  # @param (see .delete_snapshots)
+  # @param options [Hash] New snapshot metadata.
+  # @option options :body [String] The snapshot description.
+  # @option options :title [String] The snapshot title.
+  # @option options :readme [String] The README.
+  # @option options :tags [String] Comma-separated list of tags (i. e. `ubuntu,ruby`).
+  # @option options :public [Boolean] Whether the snapshot will be accessible by other users.
+  # @option options :custom_data [String] Metadata of your Terminal. Anything you need.
+  #   It will be accessible through {.get_terminal}, but not from within the Terminal itself.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#edit-snapshot Terminal.com API docs
+  def self.edit_snapshot(user_token, access_token, snapshot_id, **options)
+    ensure_options_validity(options,
+      :body, :title, :readme, :tags, :public, :custom_data)
+
+    options.merge!(user_token: user_token, access_token: access_token, snapshot_id: snapshot_id)
+
+    call('/edit_snapshot', options)
+  end
 
-      options.merge!(user_token: user_token, access_token: access_token, snapshot_id: snapshot_id)
+  # Create a snapshot of a Terminal instance.
+  #
+  # @param (see .delete_terminal)
+  # @param options [Hash] Snapshot metadata.
+  # @option options (see .edit_snapshot)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#snapshot-terminal Terminal.com API docs
+  def self.snapshot_terminal(user_token, access_token, container_key, **options)
+    ensure_options_validity(options,
+      :body, :title, :readme, :tags, :public)
+
+    options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)
+
+    call('/snapshot_terminal', options)
+  end
 
-      call('/edit_snapshot', options)
-    end
+  # @!endgroup
+  # @!group MANAGE TERMINAL ACCESS
+
+  # Add to the list of your other Terminals who have access
+  # to one of your Terminal instances.
+  #
+  # Currently this feature doesn't have GUI, so don't be surprised
+  # if you haven't come across it yet.
+  #
+  # @param (see .delete_terminal)
+  # @param links [Array<Hash>] Links are hashes with keys `port` and `source`.
+  #   Port is any port number and source is any subdomain (i. e. `botanicus117`).
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   container_key = "1123587c-7aec-4b91-90c1-2de534033989"
+  #   link = {port: 3000, source: "botanicus117"}
+  #   Terminal.add_terminal_links(user_token, access_token, container_key, link)
+  #   # {"status":"success"}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#add-terminal-links Terminal.com API docs
+  def self.add_terminal_links(user_token, access_token, container_key, *links)
+    call('/add_terminal_links',
+      user_token: user_token,
+      access_token: access_token,
+      container_key: container_key,
+      links: links)
+  end
 
-    # https://www.terminal.com/api/docs#snapshot-terminal
-    def snapshot_terminal(user_token, access_token, container_key, **options)
-      ensure_options_validity(options,
-        :body, :title, :readme, :tags, :public)
+  # Remove from the list of Terminals who have access to one
+  # of your Terminal instances.
+  #
+  # @param (see .add_terminal_links)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#remove-terminal-links Terminal.com API docs
+  def self.remove_terminal_links(user_token, access_token, container_key, *links)
+    call('/remove_terminal_links',
+      user_token: user_token,
+      access_token: access_token,
+      container_key: container_key,
+      links: links)
+  end
 
-      options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)
+  # List users and emails with view or edit access to one
+  # of your Terminal instances.
+  #
+  # @param (see .delete_terminal)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.list_terminal_access(user_token, access_token, "268b0082-c96c-4c74-bf0a-a5d6d4c16b01")
+  #   # {"is_public_list" => ["80", "3000"],
+  #   #  "access_rules" => ["3000::*@cloudlabs.io", "*::james@101ideas.cz", "IDE::james@101ideas.cz", "IDE::terminal@cloudlabs.io"],
+  #   #  "links"=>["3000::botanicus117"]}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#list-terminal-access Terminal.com API docs
+  # @see https://www.terminal.com/faq#terminalAccess Terminal.com FAQ: Terminal access
+  def self.list_terminal_access(user_token, access_token, container_key)
+    call('/list_terminal_access',
+      user_token: user_token,
+      access_token: access_token,
+      container_key: container_key)
+  end
 
-      call('/snapshot_terminal', options)
-    end
+  # Edit the list of users and emails who have access to one
+  # of your Terminal instances.
+  #
+  # @param (see .delete_terminal)
+  # @param options [Hash] Access rules.
+  # @option options :is_public_list [Array] List of open ports.
+  #   Port `80` is open by default, you can add additional ports.
+  # @option options :access_rules [Array] Array of access rules.
+  #   An access rule is `<port>::<email>`. Port can be a port number,
+  #   `IDE` or an asterisk and email can contain asterisks.
+  #   **Examples:** `"3000::*@cloudlabs.io"`, `"*::james@101ideas.cz",
+  #   `"IDE::james@101ideas.cz"`.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#edit-terminal-access Terminal.com API docs
+  # @see https://www.terminal.com/faq#terminalAccess Terminal.com FAQ: Terminal access
+  # @see https://www.terminal.com/faq#openPorts Terminal.com FAQ: Opening additional ports
+  def self.edit_terminal_access(user_token, access_token, container_key, **options)
+    ensure_options_validity(options, :is_public_list, :access_rules)
+
+    options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)
+
+    call('/edit_terminal_access', options)
+  end
 
-    ##########################
-    # MANAGE TERMINAL ACCESS #
-    ##########################
-
-    # https://www.terminal.com/api/docs#add-terminal-links
-    def add_terminal_links(user_token, access_token, container_key, *links)
-      call('/add_terminal_links',
-        user_token: user_token,
-        access_token: access_token,
-        container_key: container_key,
-        links: links)
-    end
+  # @!endgroup
+  # @!group MANAGE TERMINAL DNS & DOMAINS
+
+  # Get a list of domains in your CNAME record pool. Domains
+  # returned by this call can be associated to your Terminal
+  # instances.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.get_cname_records(user_token, access_token)
+  #   # {"available" => ["101ideas.cz", "terminal.101ideas.cz"]], "assigned": []}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#get-cname-records Terminal.com API docs
+  # @see https://www.terminal.com/faq#cname Terminal.com FAQ: Using my own domains for my Terminals?
+  def self.get_cname_records(user_token, access_token)
+    call('/get_cname_records',
+      user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#remove-terminal-links
-    def remove_terminal_links(user_token, access_token, container_key, *links)
-      call('/remove_terminal_links',
-        user_token: user_token,
-        access_token: access_token,
-        container_key: container_key,
-        links: links)
-    end
+  # Add a domain or subdomain of Terminal.com to your CNAME
+  # record pool, making it available to be associated with
+  # one of your Terminal instances.
+  #
+  # @param (see .list_terminals)
+  # @param domain [String] A domain (i. e. `101ideas.cz`).
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#add-domain-to-pool Terminal.com API docs
+  # @see https://www.terminal.com/faq#cname Terminal.com FAQ: Using my own domains for my Terminals?
+  def self.add_domain_to_pool(user_token, access_token, domain)
+    call('/add_domain_to_pool',
+      user_token: user_token, access_token: access_token, domain: domain)
+  end
 
-    # https://www.terminal.com/api/docs#list-terminal-access
-    def list_terminal_access(user_token, access_token, container_key)
-      call('/list_terminal_access',
-        user_token: user_token,
-        access_token: access_token,
-        container_key: container_key)
-    end
+  # Remove a domain or subdomain of Terminal.com from your
+  # CNAME record pool.
+  #
+  # @param (see .add_domain_to_pool)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#remove-domain-from-pool Terminal.com API docs
+  # @see https://www.terminal.com/faq#cname Terminal.com FAQ: Using my own domains for my Terminals?
+  def self.remove_domain_from_pool(user_token, access_token, domain)
+    call('/remove_domain_from_pool',
+      user_token: user_token, access_token: access_token, domain: domain)
+  end
 
-    # https://www.terminal.com/api/docs#edit-terminal-access
-    def edit_terminal_access(user_token, access_token, container_key, **options)
-      ensure_options_validity(options, :is_public_list, :access_rules)
+  # Map a domain in your CNAME record pool to one of your
+  # Terminal instances, making it accessible via that domain.
+  #
+  # @param (see .add_domain_to_pool)
+  # @param subdomain [String] Subdomain of the Terminal you want the domain assigned to.
+  # @param port [String] Which port on the Terminal should it point to?
+  #   This will typically be either `80` if you're using Apache or Nginx
+  #   or any other number if you're using say Thin or Puma.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.add_cname_record(user_token, access_token, 'terminal.101ideas.cz', 'botanicus117', 3000)
+  #   # {"available" => [...], "assigned" => [{"domain" => "terminal.101ideas.cz", "subdomain" => "botanicus117", "port" => "3000"}]}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#add-cname-record Terminal.com API docs
+  # @see https://www.terminal.com/faq#cname Terminal.com FAQ: Using my own domains for my Terminals?
+  def self.add_cname_record(user_token, access_token, domain, subdomain, port)
+    call('/add_cname_record',
+      user_token: user_token,
+      access_token: access_token,
+      domain: domain,
+      subdomain: subdomain,
+      port: port)
+  end
 
-      options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)
+  # Remove a domain mapping to one of your Terminal instances.
+  # This will mean you can no longer access the Terminal instance
+  # from that domain.
+  #
+  # @param (see .add_domain_to_pool)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#remove-cname-record Terminal.com API docs
+  # @see https://www.terminal.com/faq#cname Terminal.com FAQ: Using my own domains for my Terminals?
+  def self.remove_cname_record(user_token, access_token, domain)
+    call('/remove_cname_record',
+      user_token: user_token,
+      access_token: access_token,
+      domain: domain)
+  end
 
-      call('/edit_terminal_access', options)
-    end
+  # @!endgroup
+  # @!group MANAGE TERMINAL IDLE SETTINGS
+
+  # Set the {https://www.terminal.com/faq#idleSettings idle settings} for your Terminal.
+  #
+  # @param (see .delete_terminal)
+  # @param action [String] Either `downgrade` or `pause`.
+  # @param triggers [Hash<Hash>] Keys can be `cpu_load` or `last_request`.
+  #   Keys of those can be `timeout` and `last_request`
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.set_terminal_idle_settings(user_token, access_token, 'b878c064-fc2b-4f14-81fa-ca10ac9385ff', 'pause', cpu_load: {timeout: 5600})
+  #   # {"success" => true}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#set-terminal-idle-settings Terminal.com API docs
+  # @see https://www.terminal.com/faq#idleSettings Terminal.com FAQ: Idle settings
+  def self.set_terminal_idle_settings(user_token, access_token, container_key, action, triggers)
+    call('/set_terminal_idle_settings',
+      user_token: user_token,
+      access_token: access_token,
+      container_key: container_key,
+      action: action,
+      triggers: triggers)
+  end
 
-    #################################
-    # MANAGE TERMINAL DNS & DOMAINS #
-    #################################
+  # Get the {https://www.terminal.com/faq#idleSettings idle settings} for your terminal.
+  #
+  # @param (see .delete_terminal)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   container_key = 'b878c064-fc2b-4f14-81fa-ca10ac9385ff'
+  #   Terminal.get_terminal_idle_settings(user_token, access_token, container_key)
+  #   # {"success": true,
+  #   #  "settings": {
+  #   #    "action": "pause",
+  #   #    "triggers": {
+  #   #      "cpu_load": {
+  #   #        "timeout": 3600,
+  #   #        "threshold": 10
+  #   #      },
+  #   #      "last_request": {
+  #   #        "timeout": 3600
+  #   #      }
+  #   #    }
+  #   #  }
+  #   # }
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#get-terminal-idle-settings Terminal.com API docs
+  # @see https://www.terminal.com/faq#idleSettings Terminal.com FAQ: Idle settings
+  def self.get_terminal_idle_settings(user_token, access_token, container_key)
+    call('/get_terminal_idle_settings',
+      user_token: user_token,
+      access_token: access_token,
+      container_key: container_key)
+  end
 
-    # https://www.terminal.com/api/docs#get-cname-records
-    def get_cname_records(user_token, access_token)
-      call('/get_cname_records',
-        user_token: user_token, access_token: access_token)
-    end
+  # @!endgroup
+  # @!group MANAGE USAGE & CREDITS
+
+  # Get a list of the types of Terminals that may be started,
+  # and the specifications for each type (CPU, RAM, and pricing).
+  #
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.instance_types
+  #   # {"instance_types" => {
+  #   #   "micro" => {"cpu" => "2 (max)", "ram" => 256, "price" => 0.006},
+  #   #   "mini" => {"cpu" => 50, "ram" => 800, "price" => 0.031},
+  #   #   "small" => {"cpu" => 100, "ram" => 1600, "price" => 0.062},
+  #   #   "medium" => {"cpu" => 200, "ram" => 3200, "price" => 0.124},
+  #   #   "xlarge" => {"cpu" => 400, "ram" => 6400, "price" => 0.248},
+  #   #   "2xlarge" => {"cpu" => 800, "ram" => 12800, "price" => 0.496},
+  #   #   "4xlarge" => {"cpu" => 1600, "ram" => 25600, "price" => 0.992},
+  #   #   "8xlarge" => {"cpu" => 3200, "ram" => 51200, "price" => 1.984}}}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#instance-types Terminal.com API docs
+  def self.instance_types
+    call('/instance_types', Hash.new)
+  end
 
-    # https://www.terminal.com/api/docs#add-domain-to-pool
-    def add_domain_to_pool(user_token, access_token, domain)
-      call('/add_domain_to_pool',
-        user_token: user_token, access_token: access_token, domain: domain)
-    end
+  # Get the hourly pricing for a Terminal instance of a given type.
+  # If a instance is stopped, price will be zero.
+  #
+  # @param instance_type [String] desc.
+  # @param status [String] Defaults to `running`. It doesn't make
+  #   sense to set it to anything else: pause instances are not billed.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.instance_price('micro')
+  #   # {"price" => 0.006, "units" => "dollars per hour"}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#instance-price Terminal.com API docs
+  def self.instance_price(instance_type, status = 'running')
+    call('/instance_price', instance_type: instance_type, status: status)
+  end
 
-    # https://www.terminal.com/api/docs#remove-domain-from-pool
-    def remove_domain_from_pool(user_token, access_token, domain)
-      call('/remove_domain_from_pool',
-        user_token: user_token, access_token: access_token, domain: domain)
-    end
+  # Get the current balance of your account.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.balance(user_token, access_token)
+  #   # {"balance" => 675.879}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#balance Terminal.com API docs
+  def self.balance(user_token, access_token)
+    call('/balance', user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#add-cname-record
-    def add_cname_record(user_token, access_token, domain, subdomain, port)
-      call('/add_cname_record',
-        user_token: user_token,
-        access_token: access_token,
-        domain: domain,
-        subdomain: subdomain,
-        port: port)
-    end
+  # Get a history of credits added to your account balance.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.balance_added(user_token, access_token)
+  #   # {"events" => [{"reason" => "Terminal.com sign up gift!", "amount" => 5, "time" => 1411652507924}], "total" => 5}
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#balance-added Terminal.com API docs
+  def self.balance_added(user_token, access_token)
+    call('/balance_added', user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#remove-cname-record
-    def remove_cname_record(user_token, access_token, domain)
-      call('/remove_cname_record',
-        user_token: user_token,
-        access_token: access_token,
-        domain: domain)
-    end
+  # Gift some of your credits to another user. Denominated in whole
+  # integer US cents ($0.01). You may only gift credits if you have
+  # previously purchased credits.
+  #
+  # @param (see .list_terminals)
+  # @param email [String] User email.
+  # @param cents [String] US cents.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#gift Terminal.com API docs
+  def self.gift(user_token, access_token, email, cents)
+    call('/gift',
+      user_token: user_token,
+      access_token: access_token,
+      email: email,
+      cents: cents)
+  end
 
-    #################################
-    # MANAGE TERMINAL IDLE SETTINGS #
-    #################################
-
-    # https://www.terminal.com/api/docs#set-terminal-idle-settings
-    def set_terminal_idle_settings(user_token, access_token, container_key, action, *triggers)
-      call('/set_terminal_idle_settings',
-        user_token: user_token,
-        access_token: access_token,
-        container_key: container_key,
-        action: action,
-        triggers: triggers)
-    end
+  # Get a history of charges to your account balance.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#burn-history Terminal.com API docs
+  def self.burn_history(user_token, access_token)
+    call('/burn_history', user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#get-terminal-idle-settings
-    def get_terminal_idle_settings(user_token, access_token, container_key)
-      call('/get_terminal_idle_settings',
-        user_token: user_token,
-        access_token: access_token,
-        container_key: container_key)
-    end
+  # Get a history of your Terminal usage.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#terminal-usage-history Terminal.com API docs
+  def self.terminal_usage_history(user_token, access_token)
+    call('/terminal_usage_history', user_token: user_token, access_token: access_token)
+  end
 
-    ##########################
-    # MANAGE USAGE & CREDITS #
-    ##########################
+  # Get a summary of current active charges being billed to your account.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#burn-state Terminal.com API docs
+  def self.burn_state(user_token, access_token)
+    call('/burn_state', user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#instance-types
-    def instance_types
-      call('/instance_types', Hash.new)
-    end
+  # Get a summary of the charges to your account, based on each
+  # Terminal instance that you have provisioned. Note that inactive
+  # and paused terminals do not incur charges.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#burn-estimates Terminal.com API docs
+  def self.burn_estimates(user_token, access_token)
+    call('/burn_estimates', user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#instance-price
-    def instance_price(instance_type, status = 'running')
-      call('/instance_price', instance_type: instance_type, status: status)
-    end
+  # @!endgroup
+  # @!group MANAGE SSH PUBLIC KEYS
+
+  # Add an SSH public key to a given Terminal's root user.
+  #
+  # @param (see .delete_terminal)
+  # @param publicKey [String] desc.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#add-authorized-key-to-terminal Terminal.com API docs
+  # @see https://www.terminal.com/faq#ssh Using SSH to connect to your Terminals
+  def self.add_authorized_key_to_terminal(user_token, access_token, container_key, publicKey)
+    call('/add_authorized_key_to_terminal',
+      user_token: user_token,
+      access_token: access_token,
+      container_key: container_key,
+      publicKey: publicKey)
+  end
 
-    # https://www.terminal.com/api/docs#balance
-    def balance(user_token, access_token)
-      call('/balance', user_token: user_token, access_token: access_token)
-    end
+  # Add an SSH public key to our SSH proxy.
+  #
+  # @param (see .list_terminals)
+  # @param name [String] desc.
+  # @param publicKey [String] desc.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#add-authorized-key-to-ssh-proxy Terminal.com API docs
+  # @see https://www.terminal.com/faq#ssh Using SSH to connect to your Terminals
+  def self.add_authorized_key_to_ssh_proxy(user_token, access_token, name, publicKey)
+    call('/add_authorized_key_to_ssh_proxy',
+      user_token: user_token,
+      access_token: access_token,
+      name: name,
+      publicKey: publicKey)
+  end
 
-    # https://www.terminal.com/api/docs#balance-added
-    def balance_added(user_token, access_token)
-      call('/balance_added', user_token: user_token, access_token: access_token)
-    end
+  # Delete an SSH public key from our SSH proxy.
+  #
+  # @param (see .list_terminals)
+  # @param name         [String] TODO.
+  # @param fingerprint  [String] TODO.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#del-authorized-key-from-ssh-proxy Terminal.com API docs
+  # @see https://www.terminal.com/faq#ssh Using SSH to connect to your Terminals
+  def self.del_authorized_key_from_ssh_proxy(user_token, access_token, name, fingerprint)
+    call('/del_authorized_key_from_ssh_proxy',
+      user_token: user_token,
+      access_token: access_token,
+      name: name,
+      fingerprint: fingerprint)
+  end
 
-    # https://www.terminal.com/api/docs#gift
-    def gift(user_token, access_token, email, cents)
-      call('/gift',
-        user_token: user_token,
-        access_token: access_token,
-        email: email,
-        cents: cents)
-    end
+  # List the SSH public key on our SSH proxy.
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#get-authorized-keys-from-ssh-proxy Terminal.com API docs
+  # @see https://www.terminal.com/faq#ssh Using SSH to connect to your Terminals
+  def self.get_authorized_keys_from_ssh_proxy(user_token, access_token)
+    call('/get_authorized_keys_from_ssh_proxy',
+      user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#burn-history
-    def burn_history(user_token, access_token)
-      call('/burn_history', user_token: user_token, access_token: access_token)
-    end
+  # @!endgroup
+  # @!group OTHER
+
+  # Get information about yourself!  If invalid access/user token
+  # provided, returns null (but not an error).
+  #
+  # @param (see .list_terminals)
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @example
+  #   Terminal.who_am_i(user_token, access_token)
+  #   # {
+  #   #   "user": {
+  #   #     "name": "James C Russell",
+  #   #     "username": "botanicus",
+  #   #     "url": "https://twitter.com/botanicus",
+  #   #     "company": "",
+  #   #     "location": "London, United Kingdom",
+  #   #     "balance": 675.879,
+  #   #     "email": "james@101ideas.cz",
+  #   #     "is_admin": false,
+  #   #     "profile_image": "//www.gravatar.com/avatar/74c419a50563fa9e5044820c2697ffd6.jpg?s=400&d=mm"
+  #   #   }
+  #   # }
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#who-am-i Terminal.com API docs
+  def self.who_am_i(user_token, access_token)
+    call('/who_am_i', user_token: user_token, access_token: access_token)
+  end
 
-    # https://www.terminal.com/api/docs#terminal-usage-history
-    def terminal_usage_history(user_token, access_token)
-      call('/terminal_usage_history', user_token: user_token, access_token: access_token)
-    end
+  # Get info and status of an API request.
+  #
+  # @param request_id [String] desc.
+  # @return (see .get_snapshot)
+  # @raise (see .get_snapshot)
+  #
+  # @since 0.0.1
+  # @see https://www.terminal.com/api/docs#request-progress Terminal.com API docs
+  def self.request_progress(request_id)
+    call('/request_progress', request_id: request_id)
+  end
 
-    # https://www.terminal.com/api/docs#burn-state
-    def burn_state(user_token, access_token)
-      call('/burn_state', user_token: user_token, access_token: access_token)
-    end
+  # @!endgroup
+  # @!group IMPLEMENTATION
 
-    # https://www.terminal.com/api/docs#burn-estimates
-    def burn_estimates(user_token, access_token)
-      call('/burn_estimates', user_token: user_token, access_token: access_token)
-    end
+  # @api private
+  def self.request
+    @request ||= Net::HTTP.new('api.terminal.com')
+  end
 
-    ##########################
-    # MANAGE SSH PUBLIC KEYS #
-    ##########################
-
-    # https://www.terminal.com/api/docs#add-authorized-key-to-terminal
-    def add_authorized_key_to_terminal(user_token, access_token, container_key, publicKey)
-      call('/add_authorized_key_to_terminal',
-        user_token: user_token,
-        access_token: access_token,
-        container_key: container_key,
-        publicKey: publicKey)
-    end
+  # Make the HTTP call, retrieve and parse the JSON response.
+  # Rewrite this method if you wish to use a different HTTP library.
+  #
+  # @raise [Terminal::NetworkError] Any network-layer error.
+  #   It's important that plugins make sure to wrap their potential
+  #   exceptions in Terminal::NetworkError for predictable behaviour.
+  #
+  # @api plugin
+  # @since 0.0.1
+  def self.call(path, data)
+    path = "/#{API_VERSION}#{path}"
+    json = data.to_json
+
+    curl_debug(path, data.to_json)
+
+    response = request.post(path, json, HEADERS)
+    status   = response.code.to_i
+
+    return parse_json(response.body) if status == 200
+
+    raise "Unexpected status #{status}: #{response.inspect}"
+  rescue SocketError => error
+    raise NetworkError.new(error)
+  end
 
-    # https://www.terminal.com/api/docs#add-authorized-key-to-ssh-proxy
-    def add_authorized_key_to_ssh_proxy(user_token, access_token, name, publicKey)
-      call('/add_authorized_key_to_ssh_proxy',
-        user_token: user_token,
-        access_token: access_token,
-        name: name,
-        publicKey: publicKey)
-    end
+  # @api private
+  def self.curl_debug(path, json)
+    return if ENV['DBG'].nil?
 
-    # https://www.terminal.com/api/docs#del-authorized-key-from-ssh-proxy
-    def del_authorized_key_from_ssh_proxy(user_token, access_token, name, fingerprint)
-      call('/del_authorized_key_from_ssh_proxy',
-        user_token: user_token,
-        access_token: access_token,
-        name: name,
-        fingerprint: fingerprint)
-    end
+    headers = HEADERS.reduce(Array.new) do |buffer, (key, value)|
+      buffer << "#{key}: #{value}"
+    end.join(' ')
 
-    # https://www.terminal.com/api/docs#get-authorized-keys-from-ssh-proxy
-    def get_authorized_keys_from_ssh_proxy(user_token, access_token)
-      call('/get_authorized_keys_from_ssh_proxy',
-        user_token: user_token, access_token: access_token)
-    end
+    STDERR.puts <<-EOF
+curl -L -X POST -H '#{headers}' -d '#{json}' https://api.terminal.com#{path}
+    EOF
+  end
 
-    #########
-    # OTHER #
-    #########
+  # @api private
+  def self.parse_json(json)
+    convert_timestamps_to_time(JSON.parse(json))
+  end
 
-    # https://www.terminal.com/api/docs#who-am-i
-    def who_am_i(user_token, access_token)
-      call('/who_am_i', user_token: user_token, access_token: access_token)
+  # We are ignoring timestamps in arrays since there are none in the API.
+  # Also, JSON document doesn't have to be an object, but in Terminal.com API,
+  # they all are.
+  # @api private
+  # TODO: Test it.
+  def self.convert_timestamps_to_time(hash)
+    hash.each do |key, value|
+      if value.is_a?(Hash)
+        convert_timestamps_to_time(value)
+      elsif value.is_a?(String) && value.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z$/)
+        hash[key] = Time.parse(value)
+      end
     end
+  end
 
-    # https://www.terminal.com/api/docs#request-progress
-    def request_progress(request_id)
-      call('/request_progress', request_id: request_id)
-    end
+  # @api private
+  def self.ensure_options_validity(options, *valid_keys)
+    unrecognised_options = (options.keys - valid_keys)
 
-    private
-    def request
-      @request ||= Net::HTTP.new('api.terminal.com')
+    unless unrecognised_options.empty?
+      raise ArgumentError.new("Unrecognised options: #{unrecognised_options.inspect[1..-2]}")
     end
+  end
 
-    def call(path, data)
-      path     = "/#{API_VERSION}#{path}"
-      response = request.post(path, data.to_json, HEADERS)
-      status   = response.code.to_i
-      return JSON.parse(response.body) if status == 200
-
-      raise "Unexpected status: #{response.inspect}"
+  # @api private
+  def self.ensure_both_cpu_and_ram_are_provided(options)
+    if (options[:cpu] && ! options[:ram]) || (options[:ram] && ! options[:cpu])
+      raise ArgumentError.new('You have to specify both cpu and ram of the corresponding instance type as described at https://www.terminal.com/faq#instanceTypes')
     end
+  end
 
-    def ensure_options_validity(options, *valid_keys)
-      unrecognised_options = (options.keys - valid_keys)
-
-      unless unrecognised_options.empty?
-        raise ArgumentError.new("Unrecognised options: #{unrecognised_options}")
+  def self.ensure_options_present(options, *required_keys)
+    required_keys.each do |key|
+      unless options.has_key?(key)
+        raise ArgumentError.new("Option #{key} is required, but is missing.")
       end
     end
   end
+
+  # @!endgroup
 end