mirrors/etherpad-lite
1
0
Fork 0
mirror of https://github.com/ether/etherpad-lite.git synced 2025-04-23 17:06:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 25

Restructure headings.

Browse source
This commit is contained in:
Marcel Klehr 2012-08-07 20:19:37 +02:00
parent 5fac05a395
commit 70fb765118
9 changed files with 97 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

38
doc/api/http_api.md
View file

@ -1,6 +1,6 @@
# HTTP API
## HTTP API
## What can I do with this API?
### What can I do with this API?
The API gives another web application control of the pads. The basic functions are
* create/delete pads
@ -11,9 +11,9 @@ The API is designed in a way, so you can reuse your existing user system with th
Take a look at [HTTP API client libraries](https://github.com/Pita/etherpad-lite/wiki/HTTP-API-client-libraries) to see if a library in your favorite language.
## Examples
### Examples
### Example 1
#### 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.
@ -43,7 +43,7 @@ Portal starts the session for the user on the group:
Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.
### Example 2
#### Example 2
A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.
@ -58,11 +58,13 @@ Portal submits content into new blog post
> Portal.AddNewBlog(content)
>
## Request Format
### Usage
#### 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
#### Response Format
Responses are valid JSON in the following format:
```js
@ -82,11 +84,11 @@ Responses are valid JSON in the following format:
* **message** a status message. Its ok if everything is fine, else it contains an error message
* **data** the payload
## Overview
#### Overview
![API Overview](http://i.imgur.com/d0nWp.png)
## Data Types
#### 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
@ -94,24 +96,24 @@ Responses are valid JSON in the following format:
* **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
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
#### Node Interoperability
All functions will also be available through a node module accessable from other node.js applications.
## JSONP
#### 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
### API Methods
## Groups
#### 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 <br><br>*Example returns:*
@ -133,7 +135,7 @@ Pads can belong to a group. The padID of grouppads is starting with a groupID li
* `{code: 1, message:"pad does already exist", data: null}`
* `{code: 1, message:"groupID does not exist", data: null}`
## Author
#### Author
Theses authors are bind to the attributes the users choose (color and name).
* **createAuthor([name])** creates a new author <br><br>*Example returns:*
@ -148,7 +150,7 @@ Theses authors are bind to the attributes the users choose (color and name).
-> can't be deleted cause this would involve scanning all the pads where this author was
## Session
#### 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 <br><br>*Example returns:*
@ -173,7 +175,7 @@ Sessions can be created between a group and an author. This allows an author to
* `{"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
Pad content can be updated and retrieved through the API
@ -190,7 +192,7 @@ Pad content can be updated and retrieved through the API
* `{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}`
* `{code: 1, message:"padID does not exist", data: null}`
## Pad
#### Pad
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.
* **createPad(padID [, text])** creates a new (non-group) pad. Note that if you need to create a group Pad, you should call **createGroupPad**.<br><br>*Example returns:*