mirror of
https://github.com/ether/etherpad-lite.git
synced 2025-04-23 00:46:16 -04:00
merge develop
This commit is contained in:
John McLear
commit
4ea7ccd104
60 changed files with 6957 additions and 232 deletions
712
out/doc/api/http_api.html
Normal file
712
out/doc/api/http_api.html
Normal file
|
|
@ -0,0 +1,712 @@
|
|||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>HTTP API - Etherpad Lite v1.2.81 Manual & Documentation</title>
|
||||
<link rel="stylesheet" href="assets/style.css">
|
||||
</head>
|
||||
<body class="apidoc" id="api-section-http_api">
|
||||
<header id="header">
|
||||
<h1>Etherpad-Lite v1.2.81 Manual & Documentation</h1>
|
||||
</header>
|
||||
|
||||
<div id="toc">
|
||||
<h2>Table of Contents</h2>
|
||||
<ul>
|
||||
<li><a href="#http_api_http_api">HTTP API</a><ul>
|
||||
<li><a href="#http_api_what_can_i_do_with_this_api">What can I do with this API?</a></li>
|
||||
<li><a href="#http_api_examples">Examples</a><ul>
|
||||
<li><a href="#http_api_example_1">Example 1</a></li>
|
||||
<li><a href="#http_api_example_2">Example 2</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_usage">Usage</a><ul>
|
||||
<li><a href="#http_api_api_version">API version</a></li>
|
||||
<li><a href="#http_api_request_format">Request Format</a></li>
|
||||
<li><a href="#http_api_response_format">Response Format</a></li>
|
||||
<li><a href="#http_api_overview">Overview</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_data_types">Data Types</a><ul>
|
||||
<li><a href="#http_api_authentication">Authentication</a></li>
|
||||
<li><a href="#http_api_node_interoperability">Node Interoperability</a></li>
|
||||
<li><a href="#http_api_jsonp">JSONP</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_api_methods">API Methods</a><ul>
|
||||
<li><a href="#http_api_groups">Groups</a><ul>
|
||||
<li><a href="#http_api_creategroup">createGroup()</a></li>
|
||||
<li><a href="#http_api_creategroupifnotexistsfor_groupmapper">createGroupIfNotExistsFor(groupMapper)</a></li>
|
||||
<li><a href="#http_api_deletegroup_groupid">deleteGroup(groupID)</a></li>
|
||||
<li><a href="#http_api_listpads_groupid">listPads(groupID)</a></li>
|
||||
<li><a href="#http_api_creategrouppad_groupid_padname_text">createGroupPad(groupID, padName [, text])</a></li>
|
||||
<li><a href="#http_api_listallgroups">listAllGroups()</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_author">Author</a><ul>
|
||||
<li><a href="#http_api_createauthor_name">createAuthor([name])</a></li>
|
||||
<li><a href="#http_api_createauthorifnotexistsfor_authormapper_name">createAuthorIfNotExistsFor(authorMapper [, name])</a></li>
|
||||
<li><a href="#http_api_listpadsofauthor_authorid">listPadsOfAuthor(authorID)</a></li>
|
||||
<li><a href="#http_api_getauthorname_authorid">getAuthorName(authorID)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_session">Session</a><ul>
|
||||
<li><a href="#http_api_createsession_groupid_authorid_validuntil">createSession(groupID, authorID, validUntil)</a></li>
|
||||
<li><a href="#http_api_deletesession_sessionid">deleteSession(sessionID)</a></li>
|
||||
<li><a href="#http_api_getsessioninfo_sessionid">getSessionInfo(sessionID)</a></li>
|
||||
<li><a href="#http_api_listsessionsofgroup_groupid">listSessionsOfGroup(groupID)</a></li>
|
||||
<li><a href="#http_api_listsessionsofauthor_authorid">listSessionsOfAuthor(authorID)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_pad_content">Pad Content</a><ul>
|
||||
<li><a href="#http_api_gettext_padid_rev">getText(padID, [rev])</a></li>
|
||||
<li><a href="#http_api_settext_padid_text">setText(padID, text)</a></li>
|
||||
<li><a href="#http_api_gethtml_padid_rev">getHTML(padID, [rev])</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_chat">Chat</a><ul>
|
||||
<li><a href="#http_api_getchathistory_padid_start_end">getChatHistory(padID, [start, end])</a></li>
|
||||
<li><a href="#http_api_getchathead_padid">getChatHead(padID)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_pad">Pad</a><ul>
|
||||
<li><a href="#http_api_createpad_padid_text">createPad(padID [, text])</a></li>
|
||||
<li><a href="#http_api_getrevisionscount_padid">getRevisionsCount(padID)</a></li>
|
||||
<li><a href="#http_api_paduserscount_padid">padUsersCount(padID)</a></li>
|
||||
<li><a href="#http_api_padusers_padid">padUsers(padID)</a></li>
|
||||
<li><a href="#http_api_deletepad_padid">deletePad(padID)</a></li>
|
||||
<li><a href="#http_api_getreadonlyid_padid">getReadOnlyID(padID)</a></li>
|
||||
<li><a href="#http_api_setpublicstatus_padid_publicstatus">setPublicStatus(padID, publicStatus)</a></li>
|
||||
<li><a href="#http_api_getpublicstatus_padid">getPublicStatus(padID)</a></li>
|
||||
<li><a href="#http_api_setpassword_padid_password">setPassword(padID, password)</a></li>
|
||||
<li><a href="#http_api_ispasswordprotected_padid">isPasswordProtected(padID)</a></li>
|
||||
<li><a href="#http_api_listauthorsofpad_padid">listAuthorsOfPad(padID)</a></li>
|
||||
<li><a href="#http_api_getlastedited_padid">getLastEdited(padID)</a></li>
|
||||
<li><a href="#http_api_sendclientsmessage_padid_msg">sendClientsMessage(padID, msg)</a></li>
|
||||
<li><a href="#http_api_checktoken">checkToken()</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#http_api_pads">Pads</a><ul>
|
||||
<li><a href="#http_api_listallpads">listAllPads()</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
<div id="apicontent">
|
||||
<h1>HTTP API<span><a class="mark" href="#http_api_http_api" id="http_api_http_api">#</a></span></h1>
|
||||
<h2>What can I do with this API?<span><a class="mark" href="#http_api_what_can_i_do_with_this_api" id="http_api_what_can_i_do_with_this_api">#</a></span></h2>
|
||||
<p>The API gives another web application control of the pads. The basic functions are
|
||||
|
||||
</p>
|
||||
<ul>
|
||||
<li>create/delete pads </li>
|
||||
<li>grant/forbid access to pads</li>
|
||||
<li>get/set pad content</li>
|
||||
</ul>
|
||||
<p>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.
|
||||
|
||||
</p>
|
||||
<p>Take a look at <a href="https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries">HTTP API client libraries</a> to see if a library in your favorite language.
|
||||
|
||||
</p>
|
||||
<h2>Examples<span><a class="mark" href="#http_api_examples" id="http_api_examples">#</a></span></h2>
|
||||
<h3>Example 1<span><a class="mark" href="#http_api_example_1" id="http_api_example_1">#</a></span></h3>
|
||||
<p>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.
|
||||
|
||||
</p>
|
||||
<p>Portal maps the internal userid to an etherpad author.
|
||||
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>Request: <code>http://pad.domain/api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7</code>
|
||||
|
||||
</p>
|
||||
<p>Response: <code>{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}</code>
|
||||
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>Portal maps the internal userid to an etherpad group:
|
||||
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>Request: <code>http://pad.domain/api/1/createGroupIfNotExistsFor?apikey=secret&groupMapper=7</code>
|
||||
|
||||
</p>
|
||||
<p>Response: <code>{code: 0, message:"ok", data: {groupID: "g.s8oes9dhwrvt0zif"}}</code>
|
||||
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>Portal creates a pad in the userGroup
|
||||
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>Request: <code>http://pad.domain/api/1/createGroupPad?apikey=secret&groupID=g.s8oes9dhwrvt0zif&padName=samplePad&text=This is the first sentence in the pad</code>
|
||||
|
||||
</p>
|
||||
<p>Response: <code>{code: 0, message:"ok", data: null}</code>
|
||||
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>Portal starts the session for the user on the group:
|
||||
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>Request: <code>http://pad.domain/api/1/createSession?apikey=secret&groupID=g.s8oes9dhwrvt0zif&authorID=a.s8oes9dhwrvt0zif&validUntil=1312201246</code>
|
||||
|
||||
</p>
|
||||
<p>Response: <code>{"data":{"sessionID": "s.s8oes9dhwrvt0zif"}}</code>
|
||||
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.
|
||||
|
||||
</p>
|
||||
<h3>Example 2<span><a class="mark" href="#http_api_example_2" id="http_api_example_2">#</a></span></h3>
|
||||
<p>A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.
|
||||
|
||||
</p>
|
||||
<p>Portal retrieves the contents of the pad for entry into the db as a blog post:
|
||||
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>Request: <code>http://pad.domain/api/1/getText?apikey=secret&padID=g.s8oes9dhwrvt0zif$123</code>
|
||||
|
||||
</p>
|
||||
<p>Response: <code>{code: 0, message:"ok", data: {text:"Welcome Text"}}</code>
|
||||
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>Portal submits content into new blog post
|
||||
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>Portal.AddNewBlog(content)
|
||||
|
||||
|
||||
</p>
|
||||
</blockquote>
|
||||
<h2>Usage<span><a class="mark" href="#http_api_usage" id="http_api_usage">#</a></span></h2>
|
||||
<h3>API version<span><a class="mark" href="#http_api_api_version" id="http_api_api_version">#</a></span></h3>
|
||||
<p>The latest version is <code>1.2.7</code>
|
||||
|
||||
</p>
|
||||
<p>The current version can be queried via /api.
|
||||
|
||||
</p>
|
||||
<h3>Request Format<span><a class="mark" href="#http_api_request_format" id="http_api_request_format">#</a></span></h3>
|
||||
<p>The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION depends on the endpoints you want to use.
|
||||
|
||||
</p>
|
||||
<h3>Response Format<span><a class="mark" href="#http_api_response_format" id="http_api_response_format">#</a></span></h3>
|
||||
<p>Responses are valid JSON in the following format:
|
||||
|
||||
</p>
|
||||
<pre><code class="js">{
|
||||
"code": number,
|
||||
"message": string,
|
||||
"data": obj
|
||||
}</code></pre>
|
||||
<ul>
|
||||
<li><strong>code</strong> a return code<ul>
|
||||
<li><strong>0</strong> everything ok</li>
|
||||
<li><strong>1</strong> wrong parameters</li>
|
||||
<li><strong>2</strong> internal error</li>
|
||||
<li><strong>3</strong> no such function</li>
|
||||
<li><strong>4</strong> no or wrong API Key</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>message</strong> a status message. Its ok if everything is fine, else it contains an error message</li>
|
||||
<li><strong>data</strong> the payload</li>
|
||||
</ul>
|
||||
<h3>Overview<span><a class="mark" href="#http_api_overview" id="http_api_overview">#</a></span></h3>
|
||||
<p><img src="http://i.imgur.com/d0nWp.png" alt="API Overview">
|
||||
|
||||
</p>
|
||||
<h2>Data Types<span><a class="mark" href="#http_api_data_types" id="http_api_data_types">#</a></span></h2>
|
||||
<div class="signature"><ul>
|
||||
<li><strong>groupID</strong> a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif</li>
|
||||
<li><strong>sessionID</strong> a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif</li>
|
||||
<li><strong>authorID</strong> a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif</li>
|
||||
<li><strong>readOnlyID</strong> a string, the unique id of an readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif</li>
|
||||
<li><strong>padID</strong> a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test</li>
|
||||
</div></ul>
|
||||
<h3>Authentication<span><a class="mark" href="#http_api_authentication" id="http_api_authentication">#</a></span></h3>
|
||||
<p>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.
|
||||
|
||||
</p>
|
||||
<h3>Node Interoperability<span><a class="mark" href="#http_api_node_interoperability" id="http_api_node_interoperability">#</a></span></h3>
|
||||
<p>All functions will also be available through a node module accessable from other node.js applications.
|
||||
|
||||
</p>
|
||||
<h3>JSONP<span><a class="mark" href="#http_api_jsonp" id="http_api_jsonp">#</a></span></h3>
|
||||
<p>The API provides <em>JSONP</em> support to allow requests from a server in a different domain.
|
||||
Simply add <code>&jsonp=?</code> to the API call.
|
||||
|
||||
</p>
|
||||
<p>Example usage: <a href="http://api.jquery.com/jQuery.getJSON/">http://api.jquery.com/jQuery.getJSON/</a>
|
||||
|
||||
</p>
|
||||
<h2>API Methods<span><a class="mark" href="#http_api_api_methods" id="http_api_api_methods">#</a></span></h2>
|
||||
<h3>Groups<span><a class="mark" href="#http_api_groups" id="http_api_groups">#</a></span></h3>
|
||||
<p>Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test
|
||||
|
||||
</p>
|
||||
<h4>createGroup()<span><a class="mark" href="#http_api_creategroup" id="http_api_creategroup">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>creates a new group
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}</code>
|
||||
|
||||
</p>
|
||||
<h4>createGroupIfNotExistsFor(groupMapper)<span><a class="mark" href="#http_api_creategroupifnotexistsfor_groupmapper" id="http_api_creategroupifnotexistsfor_groupmapper">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>this functions helps you to map your application group ids to etherpad lite group ids
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}</code>
|
||||
|
||||
</p>
|
||||
<h4>deleteGroup(groupID)<span><a class="mark" href="#http_api_deletegroup_groupid" id="http_api_deletegroup_groupid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>deletes a group
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"groupID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>listPads(groupID)<span><a class="mark" href="#http_api_listpads_groupid" id="http_api_listpads_groupid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns all pads of this group
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {padIDs : ["g.s8oes9dhwrvt0zif$test", "g.s8oes9dhwrvt0zif$test2"]}</code>
|
||||
</em> <code>{code: 1, message:"groupID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>createGroupPad(groupID, padName [, text])<span><a class="mark" href="#http_api_creategrouppad_groupid_padname_text" id="http_api_creategrouppad_groupid_padname_text">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>creates a new pad in this group
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"pad does already exist", data: null}</code>
|
||||
* <code>{code: 1, message:"groupID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>listAllGroups()<span><a class="mark" href="#http_api_listallgroups" id="http_api_listallgroups">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1.1</li>
|
||||
</div></ul>
|
||||
<p>lists all existing groups
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {groupIDs: ["g.mKjkmnAbSMtCt8eL", "g.3ADWx6sbGuAiUmCy"]}}</code>
|
||||
</em> <code>{code: 0, message:"ok", data: {groupIDs: []}}</code>
|
||||
|
||||
</p>
|
||||
<h3>Author<span><a class="mark" href="#http_api_author" id="http_api_author">#</a></span></h3>
|
||||
<p>These authors are bound to the attributes the users choose (color and name).
|
||||
|
||||
</p>
|
||||
<h4>createAuthor([name])<span><a class="mark" href="#http_api_createauthor_name" id="http_api_createauthor_name">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>creates a new author
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}</code>
|
||||
|
||||
</p>
|
||||
<h4>createAuthorIfNotExistsFor(authorMapper [, name])<span><a class="mark" href="#http_api_createauthorifnotexistsfor_authormapper_name" id="http_api_createauthorifnotexistsfor_authormapper_name">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>this functions helps you to map your application author ids to etherpad lite author ids
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}</code>
|
||||
|
||||
</p>
|
||||
<h4>listPadsOfAuthor(authorID)<span><a class="mark" href="#http_api_listpadsofauthor_authorid" id="http_api_listpadsofauthor_authorid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns an array of all pads this author contributed to
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}</code>
|
||||
</em> <code>{code: 1, message:"authorID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getAuthorName(authorID)<span><a class="mark" href="#http_api_getauthorname_authorid" id="http_api_getauthorname_authorid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1.1</li>
|
||||
</div></ul>
|
||||
<p>Returns the Author Name of the author
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: {authorName: "John McLear"}}</code>
|
||||
|
||||
</p>
|
||||
<p>-> can't be deleted cause this would involve scanning all the pads where this author was
|
||||
|
||||
</p>
|
||||
<h3>Session<span><a class="mark" href="#http_api_session" id="http_api_session">#</a></span></h3>
|
||||
<p>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. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. 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.
|
||||
|
||||
</p>
|
||||
<h4>createSession(groupID, authorID, validUntil)<span><a class="mark" href="#http_api_createsession_groupid_authorid_validuntil" id="http_api_createsession_groupid_authorid_validuntil">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>creates a new session. validUntil is an unix timestamp in seconds
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {sessionID: "s.s8oes9dhwrvt0zif"}}</code>
|
||||
</em> <code>{code: 1, message:"groupID doesn't exist", data: null}</code>
|
||||
<em> <code>{code: 1, message:"authorID doesn't exist", data: null}</code>
|
||||
</em> <code>{code: 1, message:"validUntil is in the past", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>deleteSession(sessionID)<span><a class="mark" href="#http_api_deletesession_sessionid" id="http_api_deletesession_sessionid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>deletes a session
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 1, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"sessionID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getSessionInfo(sessionID)<span><a class="mark" href="#http_api_getsessioninfo_sessionid" id="http_api_getsessioninfo_sessionid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns informations about a session
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif", groupID: g.s8oes9dhwrvt0zif, validUntil: 1312201246}}</code>
|
||||
</em> <code>{code: 1, message:"sessionID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>listSessionsOfGroup(groupID)<span><a class="mark" href="#http_api_listsessionsofgroup_groupid" id="http_api_listsessionsofgroup_groupid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns all sessions of a group
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}</code>
|
||||
</em> <code>{code: 1, message:"groupID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>listSessionsOfAuthor(authorID)<span><a class="mark" href="#http_api_listsessionsofauthor_authorid" id="http_api_listsessionsofauthor_authorid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns all sessions of an author
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}</code>
|
||||
</em> <code>{code: 1, message:"authorID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h3>Pad Content<span><a class="mark" href="#http_api_pad_content" id="http_api_pad_content">#</a></span></h3>
|
||||
<p>Pad content can be updated and retrieved through the API
|
||||
|
||||
</p>
|
||||
<h4>getText(padID, [rev])<span><a class="mark" href="#http_api_gettext_padid_rev" id="http_api_gettext_padid_rev">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns the text of a pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {text:"Welcome Text"}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>setText(padID, text)<span><a class="mark" href="#http_api_settext_padid_text" id="http_api_settext_padid_text">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>sets the text of a pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
* <code>{code: 1, message:"text too long", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getHTML(padID, [rev])<span><a class="mark" href="#http_api_gethtml_padid_rev" id="http_api_gethtml_padid_rev">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns the text of a pad formatted as HTML
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h3>Chat<span><a class="mark" href="#http_api_chat" id="http_api_chat">#</a></span></h3>
|
||||
<h4>getChatHistory(padID, [start, end])<span><a class="mark" href="#http_api_getchathistory_padid_start_end" id="http_api_getchathistory_padid_start_end">#</a></span></h4>
|
||||
<ul>
|
||||
<li>API >= 1.2.7</li>
|
||||
</ul>
|
||||
<p>returns
|
||||
|
||||
</p>
|
||||
<ul>
|
||||
<li>a part of the chat history, when <code>start</code> and <code>end</code> are given</li>
|
||||
<li>the whole chat histroy, when no extra parameters are given</li>
|
||||
</ul>
|
||||
<p><em>Example returns:</em>
|
||||
|
||||
</p>
|
||||
<ul>
|
||||
<li><code>{"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}</code></li>
|
||||
<li><code>{code: 1, message:"start is higher or equal to the current chatHead", data: null}</code></li>
|
||||
<li><code>{code: 1, message:"padID does not exist", data: null}</code></li>
|
||||
</ul>
|
||||
<h4>getChatHead(padID)<span><a class="mark" href="#http_api_getchathead_padid" id="http_api_getchathead_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1.2.7</li>
|
||||
</div></ul>
|
||||
<p>returns the chatHead (last number of the last chat-message) of the pad
|
||||
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
|
||||
</p>
|
||||
<ul>
|
||||
<li><code>{code: 0, message:"ok", data: {chatHead: 42}}</code></li>
|
||||
<li><code>{code: 1, message:"padID does not exist", data: null}</code></li>
|
||||
</ul>
|
||||
<h3>Pad<span><a class="mark" href="#http_api_pad" id="http_api_pad">#</a></span></h3>
|
||||
<p>Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.
|
||||
|
||||
</p>
|
||||
<h4>createPad(padID [, text])<span><a class="mark" href="#http_api_createpad_padid_text" id="http_api_createpad_padid_text">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>creates a new (non-group) pad. Note that if you need to create a group Pad, you should call <strong>createGroupPad</strong>.
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"pad does already exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getRevisionsCount(padID)<span><a class="mark" href="#http_api_getrevisionscount_padid" id="http_api_getrevisionscount_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns the number of revisions of this pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {revisions: 56}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>padUsersCount(padID)<span><a class="mark" href="#http_api_paduserscount_padid" id="http_api_paduserscount_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns the number of user that are currently editing this pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: {padUsersCount: 5}}</code>
|
||||
|
||||
</p>
|
||||
<h4>padUsers(padID)<span><a class="mark" href="#http_api_padusers_padid" id="http_api_padusers_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1.1</li>
|
||||
</div></ul>
|
||||
<p>returns the list of users that are currently editing this pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}</code>
|
||||
</em> <code>{code: 0, message:"ok", data: {padUsers: []}}</code>
|
||||
|
||||
</p>
|
||||
<h4>deletePad(padID)<span><a class="mark" href="#http_api_deletepad_padid" id="http_api_deletepad_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>deletes a pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getReadOnlyID(padID)<span><a class="mark" href="#http_api_getreadonlyid_padid" id="http_api_getreadonlyid_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns the read only link of a pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>setPublicStatus(padID, publicStatus)<span><a class="mark" href="#http_api_setpublicstatus_padid_publicstatus" id="http_api_setpublicstatus_padid_publicstatus">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>sets a boolean for the public status of a pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getPublicStatus(padID)<span><a class="mark" href="#http_api_getpublicstatus_padid" id="http_api_getpublicstatus_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>return true of false
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {publicStatus: true}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>setPassword(padID, password)<span><a class="mark" href="#http_api_setpassword_padid_password" id="http_api_setpassword_padid_password">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns ok or a error message
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: null}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>isPasswordProtected(padID)<span><a class="mark" href="#http_api_ispasswordprotected_padid" id="http_api_ispasswordprotected_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns true or false
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {passwordProtection: true}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>listAuthorsOfPad(padID)<span><a class="mark" href="#http_api_listauthorsofpad_padid" id="http_api_listauthorsofpad_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns an array of authors who contributed to this pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>getLastEdited(padID)<span><a class="mark" href="#http_api_getlastedited_padid" id="http_api_getlastedited_padid">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1</li>
|
||||
</div></ul>
|
||||
<p>returns the timestamp of the last revision of the pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {lastEdited: 1340815946602}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>sendClientsMessage(padID, msg)<span><a class="mark" href="#http_api_sendclientsmessage_padid_msg" id="http_api_sendclientsmessage_padid_msg">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1.1</li>
|
||||
</div></ul>
|
||||
<p>sends a custom message of type <code>msg</code> to the pad
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{code: 0, message:"ok", data: {}}</code>
|
||||
</em> <code>{code: 1, message:"padID does not exist", data: null}</code>
|
||||
|
||||
</p>
|
||||
<h4>checkToken()<span><a class="mark" href="#http_api_checktoken" id="http_api_checktoken">#</a></span></h4>
|
||||
<div class="signature"><ul>
|
||||
<li>API >= 1.2</li>
|
||||
</div></ul>
|
||||
<p>returns ok when the current api token is valid
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
<em> <code>{"code":0,"message":"ok","data":null}</code>
|
||||
</em> <code>{"code":4,"message":"no or wrong API Key","data":null}</code>
|
||||
|
||||
</p>
|
||||
<h3>Pads<span><a class="mark" href="#http_api_pads" id="http_api_pads">#</a></span></h3>
|
||||
<h4>listAllPads()<span><a class="mark" href="#http_api_listallpads" id="http_api_listallpads">#</a></span></h4>
|
||||
<ul>
|
||||
<li>API >= 1.2.1</li>
|
||||
</ul>
|
||||
<p>lists all pads on this epl instance
|
||||
|
||||
</p>
|
||||
<p><em>Example returns:</em>
|
||||
* <code>{code: 0, message:"ok", data: ["testPad", "thePadsOfTheOthers"]}</code>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue