Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An Etherpad Lite client library for Ruby
Latest commit 726acd6 @jhollinger Merge pull request #9 from coderhs/master
Changed example syntax from Ruby hash style 1.8 to 1.9


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 Nobody likes you, Ruby 1.8. Now go away.

Basic usage

require 'etherpad-lite'

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

# 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

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
    # 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(9001,'/srv/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(9001,'/srv/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: ""}

Low-level client

There is an optional low-level client, which is a paper-thin wrapper around Etherpad Lite's HTTP JSON API. In the examples above, the low-level client is accessible from the high-level interface:

client = ether.client
client.getText(padID: '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 = EtherpadLite.client('', 'api key', 1.1)
client.setText(padID: 'my first etherpad lite pad', text: "lots of new text and stuff")

The methods and parameters exactly match the HTTP API. For a full list of them, see


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.