JAMES-1759 WebAdminServer REST API documentation
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/6275dc3f Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/6275dc3f Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/6275dc3f Branch: refs/heads/master Commit: 6275dc3f85b5876e07081a27c484dee159aef2f5 Parents: ef155e3 Author: Benoit Tellier <[email protected]> Authored: Thu Jun 16 19:14:32 2016 +0700 Committer: Benoit Tellier <[email protected]> Committed: Wed Jun 22 15:34:19 2016 +0700 ---------------------------------------------------------------------- server/protocols/webadmin/README.adoc | 123 +++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/6275dc3f/server/protocols/webadmin/README.adoc ---------------------------------------------------------------------- diff --git a/server/protocols/webadmin/README.adoc b/server/protocols/webadmin/README.adoc new file mode 100644 index 0000000..7f09778 --- /dev/null +++ b/server/protocols/webadmin/README.adoc @@ -0,0 +1,123 @@ += Web administration for JAMES + +The web administration supports for now the CRUD operations on the domains and the users, as described in the following sections. + +**WARNING** : This API do not allow authentication for now. It means that an administrator should ensure an attacker can not use this API. + +== Administrating domains + +=== Create a domain + +.bash +==== +curl -XPUT http://ip:port/domains/domainToBeCreated +==== + +Resource name domainToBeCreated : + - can not be null or empty + - can not contain '@' + - can not be more than 255 characters + - can not contain '/' + +Response codes : + - 204 : The domain was successfully added + - 400 : The domain name is invalid + - 500 : Internal error while adding the domain + +=== Delete a domain + +.bash +==== +curl -XDELETE http://ip:port/domains/domainToBeDeleted +==== + +Response codes : + - 204 : The domain was successfully removed + - 500 : Internal error while removing the domain + +=== Test if a domain exists + +.bash +==== +curl -XGET http://ip:port/domains/domainName +==== + +Response codes : + - 204 : The domains exists + - 404 : The domain does not exist + - 500 : Internal error while accessing the domains + +=== Get the list of domains + +.bash +==== +curl -XGET http://ip:port/domains +==== + +Possible response : + +.json +==== +{"domains":["domain1", "domain2"]} +==== + +Response codes : + - 200 : The domain list was successfully retrieved + - 500 : Internal error while accessing the domains + +== Administrating users + +=== Create a user + +.bash +==== +curl -XPUT http://ip:port/users/usernameToBeUsed -d '{"password":"passwordToBeUsed"}' +==== + +Resource name usernameToBeUsed : + - can not be null or empty + - can not be more than 255 characters + - can not contain '/' + +Response codes : + - 204 : The user was successfully created + - 400 : The user name or the payload is invalid + - 409 : Conflict : A concurrent modification make that query to fail + - 500 : Internal error while adding the user + +Note : if the user is already, its password will be updated. + +=== Updating a user password + +Same than Create, but a user need to exist. + +If the user do not exist, then it will be created. + +=== Deleting a user + +.bash +==== +curl -XDELETE http://ip:port/users/userToBeDeleted +==== + +Response codes : + - 204 : The user was successfully deleted + - 500 : Internal error while deleting the user + +=== Retrieving the user list + +.bash +==== +curl -XGET http://ip:port/users +==== + +The answer looks like : + +.json +==== +[{"username":"[email protected]"},{"username":"[email protected]"}] +==== + +Response codes : + - 200 : The user name list was successfully retrieved + - 500 : Internal error while retrieving the users --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
