minor changes in docs
- correct link to doc generation tool. - fixed incomplete sentence regarding API client libraries
This commit is contained in:
Alexander Lorz
parent
423d8e584e
commit
cd7f01f40a
|
|
@ -3,42 +3,42 @@
|
|||
## What can I do with this API?
|
||||
The API gives another web application control of the pads. The basic functions are
|
||||
|
||||
* create/delete pads
|
||||
* 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. Means: Your web application still has to do authentication, but you can tell Etherpad via the api, which visitors should get which permissions. This allows Etherpad 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](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) to see if a library in your favorite language.
|
||||
Take a look at [HTTP API client libraries](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) to check if a library in your favorite programming language is available.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
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: null}`
|
||||
|
||||
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.
|
||||
|
|
@ -50,7 +50,7 @@ A portal (such as WordPress) wants to transform the contents of a pad that multi
|
|||
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
|
||||
|
|
@ -103,7 +103,7 @@ Responses are valid JSON in the following format:
|
|||
|
||||
### Authentication
|
||||
|
||||
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad deployment. This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad. Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API.
|
||||
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad deployment. This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad. Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API.
|
||||
|
||||
### Node Interoperability
|
||||
|
||||
|
|
@ -123,7 +123,7 @@ Pads can belong to a group. The padID of grouppads is starting with a groupID li
|
|||
|
||||
#### createGroup()
|
||||
* API >= 1
|
||||
|
||||
|
||||
creates a new group
|
||||
|
||||
*Example returns:*
|
||||
|
|
@ -132,7 +132,7 @@ creates a new group
|
|||
#### createGroupIfNotExistsFor(groupMapper)
|
||||
* API >= 1
|
||||
|
||||
this functions helps you to map your application group ids to Etherpad group ids
|
||||
this functions helps you to map your application group ids to Etherpad group ids
|
||||
|
||||
*Example returns:*
|
||||
* `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
|
||||
|
|
@ -175,7 +175,7 @@ lists all existing groups
|
|||
* `{code: 0, message:"ok", data: {groupIDs: []}}`
|
||||
|
||||
### Author
|
||||
These authors are bound to the attributes the users choose (color and name).
|
||||
These authors are bound to the attributes the users choose (color and name).
|
||||
|
||||
#### createAuthor([name])
|
||||
* API >= 1
|
||||
|
|
@ -188,7 +188,7 @@ creates a new author
|
|||
#### createAuthorIfNotExistsFor(authorMapper [, name])
|
||||
* API >= 1
|
||||
|
||||
this functions helps you to map your application author ids to Etherpad author ids
|
||||
this functions helps you to map your application author ids to Etherpad author ids
|
||||
|
||||
*Example returns:*
|
||||
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
|
||||
|
|
@ -411,7 +411,7 @@ creates a chat message, saves it to the database and sends it to all connected c
|
|||
* `{code: 1, message:"text is no string", data: null}`
|
||||
|
||||
### 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.
|
||||
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])
|
||||
* API >= 1
|
||||
|
|
@ -575,7 +575,7 @@ 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}`
|
||||
|
||||
|
||||
#### sendClientsMessage(padID, msg)
|
||||
* API >= 1.1
|
||||
|
||||
|
|
@ -598,7 +598,7 @@ returns ok when the current api token is valid
|
|||
|
||||
#### listAllPads()
|
||||
* API >= 1.2.1
|
||||
|
||||
|
||||
lists all pads on this epl instance
|
||||
|
||||
*Example returns:*
|
||||
|
|
|
|||
|
|
@ -11,5 +11,5 @@ heading.
|
|||
|
||||
Every `.html` file is generated based on the corresponding
|
||||
`.markdown` file in the `doc/api/` folder in the source tree. The
|
||||
documentation is generated using the `tools/doc/generate.js` program.
|
||||
The HTML template is located at `doc/template.html`.
|
||||
documentation is generated using the `bin/doc/generate.js` program.
|
||||
The HTML template is located at `doc/template.html`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue