Skip to content

HTTP API

Jump to bottom
Matic Potočnik edited this page Jul 21, 2017 · 66 revisions

HTTP API

Please note: The following information only applies to v1.1.1, for newer versions, check out the doc folder or the online docs.

What can I do with this API?

The API gives another web application control of the pads. The basic functions are

  • create/delete pads
  • grant/forbid access to pads
  • get/set pad content

The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to etherpad lite. Means: Your web application still has to do authentication, but you can tell etherpad lite via the api, which visitors should get which permissions. This allows etherpad lite to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.

Take a look at HTTP API client libraries to see if a library in your favorite language.

Examples

Example 1

A portal (such as WordPress) wants to give a user access to a new pad. Let's assume the user have the internal id 7 and his name is michael.

Portal maps the internal userid to an etherpad author.

Request: http://pad.domain/api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7

Response: {code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}

Portal maps the internal userid to an etherpad group:

Request: http://pad.domain/api/1/createGroupIfNotExistsFor?apikey=secret&groupMapper=7

Response: {code: 0, message:"ok", data: {groupID: "g.s8oes9dhwrvt0zif"}}

Portal creates a pad in the userGroup

Request: http://pad.domain/api/1/createGroupPad?apikey=secret&groupID=g.s8oes9dhwrvt0zif&padName=samplePad&text=This is the first sentence in the pad

Response: {code: 0, message:"ok", data: { padID: "g.s8oes9dhwrvt0zif$samplePad" } }

Portal starts the session for the user on the group:

Request: http://pad.domain/api/1/createSession?apikey=secret&groupID=g.s8oes9dhwrvt0zif&authorID=a.s8oes9dhwrvt0zif&validUntil=1312201246

Response: {"data":{"sessionID": "s.s8oes9dhwrvt0zif"}}

Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.

Example 2

A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.

Portal retrieves the contents of the pad for entry into the db as a blog post:

Request: http://pad.domain/api/1/getText?apikey=secret&padID=g.s8oes9dhwrvt0zif$123

Response: {code: 0, message:"ok", data: {text:"Welcome Text"}}

Portal submits content into new blog post

Portal.AddNewBlog(content)

Request Format

The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION is 1

Response Format

Responses are valid JSON in the following format:

{
  "code": number,
  "message": string,
  "data": obj
}
  • code a return code
    • 0 everything ok
    • 1 wrong parameters
    • 2 internal error
    • 3 no such function
    • 4 no or wrong API Key
  • message a status message. It's ok if everything is fine, else it contains an error message
  • data the payload

Overview

API Overview

Data Types

  • groupID a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif
  • sessionID a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif
  • authorID a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif
  • readOnlyID a string, the unique id of an readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif
  • padID a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test

Authentication

Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad-Lite deployment. This token will be random string, generated by Etherpad-Lite at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad Lite. Only Etherpad Lite and the requesting application knows this key. Token management will not be exposed through this API.

Node Interoperability

All functions will also be available through a node module accessible from other node.js applications.

JSONP

The API provides JSONP support to allow requests from a server in a different domain. Simply add &jsonp=? to the API call.

Example usage: http://api.jquery.com/jQuery.getJSON/

API Functions

Groups

Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test

  • createGroup() creates a new group

    Example returns:

    • {code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}

  • createGroupIfNotExistsFor(groupMapper) this functions helps you to map your application group ids to etherpad lite group ids

    Example returns:

    • {code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}

  • deleteGroup(groupID) deletes a group

    Example returns:

    • {code: 0, message:"ok", data: null}
    • {code: 1, message:"groupID does not exist", data: null}

  • listPads(groupID) returns all pads of this group

    Example returns:

    • {code: 0, message:"ok", data: {padIDs : ["g.s8oes9dhwrvt0zif$test", "g.s8oes9dhwrvt0zif$test2"]}
    • {code: 1, message:"groupID does not exist", data: null}

  • createGroupPad(groupID, padName [, text]) creates a new pad in this group

    Example returns:

    • {code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}}
    • {code: 1, message:"pad does already exist", data: null}
    • {code: 1, message:"groupID does not exist", data: null}

Author

Theses authors are bind to the attributes the users choose (color and name).

  • createAuthor([name]) creates a new author

    Example returns:

    • {code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}

  • createAuthorIfNotExistsFor(authorMapper [, name]) this functions helps you to map your application author ids to etherpad lite author ids

    Example returns:

    • {code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}

  • listPadsOfAuthor(authorID) returns an array of all pads this author contributed to

    Example returns:

    • {code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}
    • {code: 1, message:"authorID does not exist", data: null}

-> can't be deleted cause this would involve scanning all the pads where this author was

Session

Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out

  • createSession(groupID, authorID, validUntil) creates a new session. validUntil is an unix timestamp in seconds

    Example returns:

    • {code: 0, message:"ok", data: {sessionID: "s.s8oes9dhwrvt0zif"}}
    • {code: 1, message:"groupID doesn't exist", data: null}
    • {code: 1, message:"authorID doesn't exist", data: null}
    • {code: 1, message:"validUntil is in the past", data: null}

  • deleteSession(sessionID) deletes a session

    Example returns:

    • {code: 1, message:"ok", data: null}
    • {code: 1, message:"sessionID does not exist", data: null}

  • getSessionInfo(sessionID) returns informations about a session

    Example returns:

    • {code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif", groupID: g.s8oes9dhwrvt0zif, validUntil: 1312201246}}
    • {code: 1, message:"sessionID does not exist", data: null}

  • listSessionsOfGroup(groupID) returns all sessions of a group

    Example returns:

    • {"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}
    • {code: 1, message:"groupID does not exist", data: null}

  • listSessionsOfAuthor(authorID) returns all sessions of an author

    Example returns:

    • {"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}
    • {code: 1, message:"authorID does not exist", data: null}

Pad Content

Pad content can be updated and retrieved through the API

  • getText(padID, [rev]) returns the text of a pad

    Example returns:

    • {code: 0, message:"ok", data: {text:"Welcome Text"}}
    • {code: 1, message:"padID does not exist", data: null}

  • setText(padID, text) sets the text of a pad

    Example returns:

    • {code: 0, message:"ok", data: null}
    • {code: 1, message:"padID does not exist", data: null}
    • {code: 1, message:"text too long", data: null}

  • getHTML(padID, [rev]) returns the text of a pad formatted as HTML

    Example returns:

    • {code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}
    • {code: 1, message:"padID does not exist", data: null}

Pad

Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and it's forbidden for normal pads to include a $ in the name.

  • createPad(padID [, text]) creates a new (non-group) pad. Note that if you need to create a group Pad, you should call createGroupPad.

    Example returns:

    • {code: 0, message:"ok", data: null}
    • {code: 1, message:"pad does already exist", data: null}

  • getRevisionsCount(padID) returns the number of revisions of this pad

    Example returns:

    • {code: 0, message:"ok", data: {revisions: 56}}
    • {code: 1, message:"padID does not exist", data: null}

  • padUsersCount(padID) returns the number of user that are currently editing this pad

    Example returns:

    • {code: 0, message:"ok", data: {padUsersCount: 5}}

  • deletePad(padID) deletes a pad

    Example returns:

    • {code: 0, message:"ok", data: null}
    • {code: 1, message:"padID does not exist", data: null}

  • getReadOnlyID(padID) returns the read only link of a pad

    Example returns:

    • {code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}}
    • {code: 1, message:"padID does not exist", data: null}

  • setPublicStatus(padID, publicStatus) sets a boolean for the public status of a pad

    Example returns:

    • {code: 0, message:"ok", data: null}
    • {code: 1, message:"padID does not exist", data: null}

  • getPublicStatus(padID) return true of false

    Example returns:

    • {code: 0, message:"ok", data: {publicStatus: true}}
    • {code: 1, message:"padID does not exist", data: null}

  • setPassword(padID, password) returns ok or a error message

    Example returns:

    • {code: 0, message:"ok", data: null}
    • {code: 1, message:"padID does not exist", data: null}

  • isPasswordProtected(padID) returns true or false

    Example returns:

    • {code: 0, message:"ok", data: {passwordProtection: true}}
    • {code: 1, message:"padID does not exist", data: null}

  • listAuthorsOfPad(padID) returns an array of authors who contributed to this pad

    Example returns:

    • {code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}
    • {code: 1, message:"padID does not exist", data: null}

  • getLastEdited(padID) returns the timestamp of the last revision of the pad

    Example returns:

    • {code: 0, message:"ok", data: {lastEdited: 1340815946602}}
    • {code: 1, message:"padID does not exist", data: null}

General

Resources

For Developers

How to's

Set up

Advanced steps

Integrating Etherpad in your web app

for Developers

Clone this wiki locally