About

Travis CI Status Gem Version Documentation License

This is a Ruby wrapper for 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:

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

  1. Run gem install terminal.com --development or put gem 'terminal.com' into your Gemfile and run bundle. The development option installs coderay, so you get syntax highlighting for JSON on console when using the command-line client.

  2. Get your user_token and access_token from your settings.

API

API docs: Latest release | Git HEAD

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 page.
  • All the optional arguments are specified as keyword arguments (options).

Example

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::[email protected]: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

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 the library do can be done through the command-line client. There are two ways how you can use it: with your credentials saved in ~/.terminal.com.json or without it.

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 page.
  • All the optional arguments are specified as keyword arguments.

Keyword Arguments

  • Booleans: --featured or --no-featured.
  • Strings: --tag=ruby.
  • Integers --ram=256.

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.

terminal.com [user_token] [access_token] list_terminals

Note that at the point you have to provide both user_token and access_token regardless of whether the API endpoint actually needs it. This will be fixed in near future!

With Configuration

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.

terminal.com list_terminals

How to Save Your Credentials

Run terminal.com configure and follow the instructions.

Development

Architecture of the Test Suite

The tests don't run against Terminal.com every single time. This is because:

  • 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 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