User:Bruederli/Draft:Kolab Webadmin API
From Kolab Wiki
Contents |
Abstract
The task of this document is to specify an API which can be used to administrate a Kolab server or server infrastructure in an abstract and functional way. The new webadmin tool planned for Kolab 3.0 could use this API to interact with the Kolab server as well as any other external software would be able to do so.
Technology
The idea is to implement a RESTful webservice based on HTTP GET/POST requests. All payload data for both requests and responses shall be JSON encoded. The transfer charset is always UTF-8 and thus doesn't need to be explicitly specified in HTTP headers.
To follow best practice in HTTP communication GET requests shall be used for data retrieval and POST request for write operations.
Proposed access URL: https://admin.<kolab-domain>/api/{action}/{id}
Client-Server conversation
Since this is only a first draft, we describe the conversation between the Kolab Server and a possible client with the following example requests/responses. This is should not be considered a complete documentation of the API.
User authentication
The interaction with the admin API is session based and requires a user authentication at first. After successful user authentication, subsequent actions are accepted if the session token returned from the user authentication request is submitted in every request either as value in the request data or as HTTP header X-Session-Token.
Request
POST /api/system.authenticate
{ username:"<fully-qualified-global-user-identifer>" }
Response (Success)
{ status:"OK", user:"<fully-qualified-global-user-identifer>", domain:"<kolab-domain>", session_token:"XXXXXXXXXXXXXXXX" }
Response (Error)
{ status:"ERROR", code:403, error:"Authentication failed" }
Obtain a list of permitted actions
After successful authentication the application should get a list of actions the current user is permitted to execute on the Kolab server. Based on this list a client application can build the UI to present a the user a reduced interface only showing options which he/she can actually use.
Request
GET /api/system.capabilities X-Session-Token: XXXXXXXXXXXXXXXX
Response
{ capabilities:[
{
domain: "<kolab-domain>",
actions: [
{ action: "user.list", type:"ls" }
{ action: "user.info", type:"r" }
{ action: "user.add", type:"w" }
{ action: "user.edit", type:"rw" },
{ action: "user.delete", type:"d" },
{ action: "mailbox.list", type:"l" },
{ action: "mailbox.info", type:"r" },
...
},
...
]
}
The 'type' attribute specifies the type of the particular action. It can be either one of the following:
- l: Listing
- ls: Listing with search capability
- r: Read only
- w: Write only (speak "adding")
- rw: Read-write (speak "editing")
- d: Delete
The action type implies the possible requests and the type of the result returned from the server. Write operations support both GET and POST requests in order to first retrieve data and/or parameters (GET) for a subsequent write operation (POST).
Read configuration information
In order to display the status of the current configuration of a Kolab server a client can query data by using list commands. Here an example to obtain a user listing:
Request
GET /api/user.list X-Session-Token: XXXXXXXXXXXXXXXX
Response
{ schema: {
"id": { type: "integer" }.
"firstname": { type: "string", title: "First name" },
"surname": { type: "string", title: "Surname" },
"roles": { type: "selection", title: "Roles", default: null },
...
},
records: [
{ id:"...", firstname:"...", surname:"...", domain:"...", type:"Kolab user", roles:["user","administrator"], ... , actions: [ 'user.edit', 'user.delete' ] },
{ id:"...", firstname:"...", surname:"...", domain:"...", type:"Kolab user", roles:["user","helpdesk"], ... , actions: [ 'user.edit', 'user.delete' ] },
...
],
count: 214,
first: 0,
pagesize: 20,
}
Retrieve parameters for a specific action
Before actually executing a specific action, a client may fetch a list of mandatory and optional parameters for a particular action from the API. This information can also be used to build UI forms presented to the user.
Sample: request parameter information for adding a new user
Resquest
GET /api/user.add X-Session-Token: XXXXXXXXXXXXXXXX
Response
{
action: "user.add",
params: [
{ name: "firstname", type: "string", mandatory: true },
{ name: "surname", type: "string", mandatory: true },
{ name: "domain", type: "selection", values: ["<kolab-domain>", "<another-kolab-domain>"] },
{ name: "type", type: "selection", values: ["user", "contact", ...] },
...
]
}
For actions of type 'rw', the GET request will additionally provide the record data in case an identifier is submitted with the request:
Resquest
GET /api/user.edit/john.doe@kolab-domain.tld X-Session-Token: XXXXXXXXXXXXXXXX
Response
{
action: "user.edit",
params: [
{ name: "firstname", type: "string", mandatory: true },
{ name: "surname", type: "string", mandatory: true },
{ name: "domain", type: "selection", values: ["<kolab-domain>", "<another-kolab-domain>"] },
...
],
record: {
id: "john.doe@kolab-domain.tld",
firstname: "John",
surname: "Die",
domain: "<kolab-domain>",
...
}
}
Executing administrative operations
With the parameter information retrieved in Step 4. a client is able to validate the user input and to compose a valid set of information which is now posted to the Kolab Admin API in order to execute the requested action. The URI to execute a specific action is the same as used for reading parameter information but action executions are sent as POST requests.
The API itself shall again validate the input before finally apply the changes requested by the client to the Kolab server. In case of a validation failure or constraint violations, an error response is sent back to the client.
Request
POST /api/user.add
{
session_token: "XXXXXXXXXXXXXXXX",
params: {
firstname: "John",
surname: "Doe",
domain: "<another-kolab-domain>",
...
}
}
Response (Success)
{ status:"OK" }
Response (Error)
{ status:"ERROR", code:602, reason:"User already exists" }
Functional requirements
The following "objects" should become editable through the proposed admin API. The detailed operations for every one of them are yet to be defined.
- Domain Name Spaces
- Types of Users
- Users
- Groups / Roles
- Nodes
- Mailboxes
- Mail Folders
- Messages
- MTA Queues
