An Etherpad Lite client library for Ruby
Switch branches/tags
Pull request Compare This branch is 73 commits behind jhollinger:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Etherpad Lite Ruby Client

etherpad-lite 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.

1 Installation

gem install etherpad-lite

2 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.revison_numbers.size
=> 2

# Iterate through each revision
pad.revisions.each do |pad_rev|
  puts pad_rev.rev
  puts pad_rev.text

Read the full docs at

3 Example use in Rails

For your view, I recommend the jQuery plugin at

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

  def group
    ether = EtherpadLite.connect(:local, 'api key')
    @app_group = YourAppGroup.find(params[:id])
    # Map your app's group to an EtherpadLite Group
    group ="my_app_group_#{}")
    # List all the pads in group
    @pads = group.pads

  def pad
    ether = EtherpadLite.connect(:local, 'api key')
    # Get the EtherpadLite Group by id
    @group = ether.get_group(params[:group_id])
    # Get the pad
    @pad = @group.pad(params[: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 => ""}

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

The PHP and Python clients are extremely thin wrappers around the HTTP API; their method names map directly to urls. The Ruby client offers a slightly higher level of abstration, with the goal of making Etherpad Lite integration in Ruby projects as simple, poweful, and dare I say fun, as possible. That said, there is nothing wrong with the thinly-wrapped API. So in the interests of being a good citizen, the Ruby client is written in two layers, one conforming to the other clients, and a higher-level “models” API riding on top of it.

In the examples above, the “standard” client can be accessed with

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

Or you can explicitly load only the standard client

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

5 License

Copyright 2011 Jordan Hollinger

Licensed under the Apache License

5 Credit

This Ruby client was inspired by TomNomNom's and devjones's PHP and Python clients, found at and