Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
An Etherpad Lite client library for Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Etherpad Lite Ruby Client

The etherpad-lite Ruby Gem is a Ruby client for Etherpad Lite's HTTP JSON API. Etherpad Lite is a collaborative editor provided by the Etherpad Foundation.

See for information on how to install and configure your own Etherpad Lite instance, and read for an in-depth description of Etherpad Lite's HTTP API.


gem install etherpad-lite

NOTE Support for Ruby 1.8.x is deprecated and will be removed in future versions. Upgrade to Ruby 1.9.x and stop being an old fuddie-duddie. It's the IE6 of Ruby.

Basic usage

require 'etherpad-lite'

# Connect to your Etherpad Lite instance
ether = EtherpadLite.connect('', 'the api key')

# Get a Pad (or create one if it doesn't exist)
pad = ether.pad('my first etherpad lite pad')

puts pad.text
=> "Welcome to Etherpad Lite!\n\nThis pad text is synchronized as you type, so that everyone viewing..."

# Write your the changes to the Pad
pad.text = "What hath God wrought?"

# There are now 2 revisions!
puts pad.revision_numbers
=> [0, 1]

# Iterate through each revision
pad.revisions.each do |pad_rev|
  puts "Revision #{pad_rev.rev}:"
  puts pad_rev.text

Full docs are at

Advanced usage

The above example deals with public pads, accessible to anyone through the Web UI. There is another class of pads - group pads - which deal with groups, authors and sessions. Examples are documented in EtherpadLite::Group, EtherpadLite::Author, and EtherpadLite::Session.

Example use in Rails

For your view, I recommend the jQuery plugin at Also, I recommend reading the docs for EtherpadLite::Group first.

Add the following to your Gemfile

gem 'etherpad-lite'

On login, create a Hash in your session to store EtherpadLite API sessions:

session[:ep_sessions] = {}

Some example controller actions:

class EtherpadController < ApplicationController
  # /etherpad
  def index
    # The idea is that your users are probably members of some kind of groups.
    # These groups can be mapped to EtherpadLite Groups. List all the user's groups.
    @app_groups = current_user.groups

  # /etherpad/groups/:id
  def group
    ether = EtherpadLite.connect(:local,'/var/www/etherpad-lite/APIKEY.txt'))
    @app_group = YourAppGroup.find(params[:id])
    # Map your app's group to an EtherpadLite Group, and list all its pads
    group ="my_app_group_#{}")
    @pads = group.pads

  # /etherpad/pads/:ep_group_id/:ep_pad_name
  def pad
    ether = EtherpadLite.connect(:local,'/var/www/etherpad-lite/APIKEY.txt'))
    # Get the EtherpadLite Group and Pad by id
    @group = ether.get_group(params[:ep_group_id])
    @pad = @group.pad(params[:ep_pad_name])
    # Map the user to an EtherpadLite Author
    author ="my_app_user_#{}", :name =>
    # Get or create an hour-long session for this Author in this Group
    sess = session[:ep_sessions][] ? ether.get_session(session[:ep_sessions][]) : @group.create_session(author, 60)
    if sess.expired?
      sess = @group.create_session(author, 60)
    session[:ep_sessions][] =
    # Set the EtherpadLite session cookie. This will automatically be picked up by the jQuery plugin's iframe.
    cookies[:sessionID] = {:value =>, :domain => ""}

Why is the Ruby client so different from the others? What gives you the right?!?

Most of the EPL clients are extremely thin wrappers around the HTTP API. The Ruby client offers a slightly higher level of abstraction, with the goal of making it as simple, powerful, and dare I say fun, as possible. That said, there are times when a bare-bones client may be preferable. In a hopefully not misguided attempt to please everyone, the Ruby client is written in two layers:

  • A high-level “models” interface starting with EtherpadLite::Instance (above)

  • A low-level client matching the HTTP API (EtherpadLite::Client, below)

In the examples above, the low-level client is accessible from the high-level interface:

client = ether.client
client.getText('my first etherpad lite pad')
=> {:text => "What hath God wrought?"}

or you can explicitly load just the low-level client:

require 'etherpad-lite/client'
client ='', 'api key')

The methods available to the low-level client should precisely match the HTTP API. In general, it behaves identically to the other clients, particularly PHP's and Python's.


Testing this library is fairly simple. It requires:

  • A recent version of Rspec

  • A running copy of Etherpad Lite with a fresh db for each run of the tests (configure connection in spec/config.yml)

Bring up Etherpad Lite with:

rm var/dirty.db && bin/

Run the tests with

rspec spec


Copyright 2011 Jordan Hollinger

Licensed under the Apache License


This Ruby client was inspired by TomNomNom’s PHP client and devjones’s Python client.

Something went wrong with that request. Please try again.