How to integrate Etherpad with your web application: step by step tutorial from pad creation to accessing pads using HTTP API

I have been spending some time on ways to track writing activities in Etherpad and I developed a web-application using Python’s Django framework that allows creation of pads, mapping of users, and tracking of writing activities. In this post, I am sharing step by step tutorial on how did I integrated Etherpad with my web application.

This post will offer tutorials on following things. If you are also doing something similar, it might be helpful for you.

  • Basics of Etherpad HTTP API with example
  • How to map the user between web application and Etherpad ?
  • How to create pads using HTTP API ?
  • How to allow access to Pads in Etherpad ?

Etherpad HTTP API

Etherpad’s HTTP API offers a range of functions to interact with Etherpad. You can access the details here. Let’s begin with a simple example using HTTP API to interact with Etherpad.

Lets say we want to create an author in Etherpad using HTTP API. Now, the first thing we need is the HTTP API key. You can find this key in the Etherpad installation directory with the name APIKEY.txt (as shown in below picture)

Etherpad directory

We will now write our first program to create an author using this key. There are several libraries available for various platform. You can use any of them. All these libraries do the same

  1. Create a URL http://server-ip:server-port/<api-version>/function-name
  2. Pass the API key as value of apiKey variable.
  3. Pass the arguments (if needed)
  4. Make a request to URL (created in step-1) and pass the api key and arguments using post method.

So, here is a simple python program without using any client’s library to create an author for Etherpad.

import requests
import json
"""
url with apikey and function name
this is for demonstration purpose, try not to pass the apikey as an get argument
"""
url = 'http://localhost:9001/api/1.2.12/createAuthor?apiKey='

result = requests.post(url,{})

print(result.json())

So, we simply created the url and passed the api key as an GET argument (this is just for demonstration). Finally, we made the request to that url.

Running the above program will display following result with author ID.

{'code': 0, 'message': 'ok', 'data': {'authorID': 'a.ln0cHzMRK3yGFcQD'}}

In the similar way, you can make call to other functions of Etherpad HTTP API. Now we are moving towards integration step.

Step-1: How to map users from your web application to Etherpad’s users

So the first thing, you need to do is to map users from your web-application to Etherpad’s users. Etherpad’s HTTP API’s function createAuthor support this mapping. You can do following

  1. When the user successfully login in your web application, you can try to create an author id for that user on Etherpad server.
  2. You can store this author ID in your database as well.

For this task, we are going to use the function createAuthorIfNotExistsFor. This function will create a new author if the user login first time. You might be thinking, how? So let’s checkout the code.

import requests
import json
"""
url with apikey and function name
this is for demonstration purpose, try not to pass the apikey as an get argument
"""
url = 'http://localhost:9001/api/1.2.12/createAuthorIfDoesNotExists?apiKey='

"""
You can pass two arguments for this function: authorMapper and name
"""
result = requests.post(url,{'authorMapper':203,'name':'Adolfo'})

response = result.json()

authorid = response['data']['authorID']

So, lets say we have a user with name Adolfo and its user id is 203 in the web-application. We will call the function createAuthorIfDoesNotExists with the arguments {'authorMapper':203,'name':'Adolfo'}. The authorMapper argument ensure the one-to-one mapping of your web-application’s user in Etherpad. On successful call, the Etherpad will return the authorID. You can save the author id in your databse and when the user login again in future, you can either access this id from database or you can again make the same call. However, in the subsequent call the function will simply access the author id from Etherpad database because it’s already exists for the specified author.

This is the way I have done it for my application. Let’s now move to pads management.

Step-2: How to manage pads using Etherpad HTTP API

In this section, I will talk about the following

  1. How to allow only Admin to create pads?
  2. How to create pads?
  3. How to access those pads in the web-application?
  4. How to access the read-only version of pad in the web-application?

2.1 How to allow only Admin to create pads?

After your installation of Etherpad, if you access the Etherpad, you will see following scree that allows user to enter to pads just by specifying the pad-name. However, when it comes to integration in web-application, we often want to restrict access to only authorized pads. You can do it by simply changing the value of editOnly in `settings.json` file in Etherpad.

/*
   * Users may edit pads but not create new ones.
   *
   * Pad creation is only via the API.
   * This applies both to group pads and regular pads.
   */
  "editOnly": true,

2.2 How to create pads?

In Etherpad, pads are associated with groups for managing the access. You can read in details here. So following are the steps, I have taken to create pads

  1. Create a group and store the group-id. It will be used while creating pads.
  2. Create pad with the group-id created in previous step.

Now, let’s have a look on the code.

So first we will create the group using createGroup function. This function doesn’t require any arguments. In case if you are storing data about the groups in your web-application’s database, you can use createGroupIfDoesNotExists to have a one-to-one mapping between your application’s group and Etherpad’s group.

import requests
import json
"""
url with apikey and function name
this is for demonstration purpose, try not to pass the apikey as an get argument
"""
url = 'http://localhost:9001/api/1.2.12/createGroup?apiKey='

"""
You can pass two arguments for this function: authorMapper and name
"""
result = requests.post(url,{})

response = result.json()

group_id = response['data']['groupID']

Once we have the group-id, we will make another request to Etherpad using function createGroupPad. This function requires group-id and pad-name (it can be skipped).

url = 'http://localhost:9001/api/1.2.12/createGroupPad?apiKey='

result = requests.post(url,{'groupID':group_id,'padName':'my pad'})

response = result.json()

pad_id = response['data']['padID']

I did store the group id and the pad id in the application’s database.

2.3 How to access the pad in the web application

So far, we have created the group and pad. Now, the question is how to access the created pad in your web application. I hope you are aware of the Session management in Etherpad (if not then I will suggest you to read this).

In order to allows access to Etherpad’s pad in your web application, you need to following

  1. Create a Session between Group and Author
  2. Create an iFrame with URL pointing to your Etherpad server with sessionID cookie.

Let’s do it now. So First we will create session between group and author.

We need group-id and author-id which we got in our previous sections. We will now make a call to first create a session for the group by calling createSession. This functions requires three arguments to be specified

  • authorId: This is the author id we got when we created author in Ehterpad.
  • groupID: This is the group id we got when we created group in Etherpad.
  • validUntil: This is the timestamp till when the access will be granted. It is unix timestamp. You can specify the duration for access. For instance, if you want to allow access only for one day from today, you can do following to compute the validUntil.
import datetime
NextDay_Date = datetime.datetime.today() + datetime.timedelta(days=1)
valid = NextDay_Date.timestamp()

let’s make a call now to create the session

url = 'http://localhost:9001/api/1.2.12/createSession?apiKey='

result = requests.post(url,{'authorID':author_id,'groupID':group_id,'validUntil':valid})

response = result.json()

session_id = response['data']['sessionID']

Now, we will create a iframe with URL to Etherpad server to access the pad we have created in previous section. Here we need the pad name and now the question is how to get the pad ID. Well, we created pad in the previous section that gave us Pad Id. If you check it, it will look like this g.s8oes9dhwrvt0zif$test. In this pad ID the pad name appear after the dollar sign ($). Therefore, the pad name for this particular pad id is test. So now we have the pad name but we still need to create a cookie with sessionId.

To avoid all the additional task of creating cookie, I used an Etherpad plugin (auth_session) to simplify the cookie thing. If you don’t know how to install plugin in Etherpad (here is the video you can check for instructions). So once we have this plugin installed we need to specify the URL in iframe and that’s it.

 <iframe  frameBorder='0' src="http://localhost:9001/auth_session?sessionID=session_id&padName=pad_name" allowfullscreen>
</iframe>

In the above code, you need to replace the session_id and pad_name with values you got when you created session and pad.

As this post is getting a bit lengthy, I decided to stop it here. I will continue with the accessing writing activities from Etherpad for monitoring purposes in the next post.

If you have any questions, feel free to post in the comments.

 

Pankaj Chejara