Improve JSON API documentation

UI/Common/UIxAclEditor.m

@@ -83,6 +83,21 @@
   return defaultUserID;
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/acls Get ACLs
+ * @apiVersion 1.0.0
+ * @apiName GetAcls
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/acls
+ *
+ * @apiSuccess (Success 200) {Object[]} users       List of users with ACL for the folder
+ * @apiSuccess (Success 200) {String} uid           User ID
+ * @apiSuccess (Success 200) {String} userClass     Either 'normal-user', 'normal-group' or 'public-access'
+ * @apiSuccess (Success 200) {Number} isSubscribed  1 if the user is subscribed to the folder
+ * @apiSuccess (Success 200) {String} [cn]          User fullname
+ * @apiSuccess (Success 200) {String} [c_email]     User main email address
+ */
 - (id <WOActionResults>) aclsAction
 {
   id <WOActionResults> result;
@@ -145,7 +160,7 @@
     }
 
   result = [self responseWithStatus: 200
-                          andString: [users jsonRepresentation]];
+              andJSONRepresentation: [NSDictionary dictionaryWithObject: users forKey: @"users"]];
 
   return result;
 }

UI/Common/UIxFolderActions.m

@@ -205,6 +205,18 @@
   return [self _realFolderActivation: NO];
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/newguid Generate new ID
+ * @apiVersion 1.0.0
+ * @apiName GetNewGUID
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/newguid
+ *
+ * @apiSuccess (Success 200) {String} pid Folder ID (element's parent)
+ * @apiSuccess (Success 200) {String} id  New element ID
+ * @apiError   (Error 500) {Object} error The error message
+ */
 - (WOResponse *) newguidAction
 {
   NSString *objectId, *folderId;
@@ -413,13 +425,24 @@
   return response;
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/subscribeUsers?uids=:uids Subscribe user(s)
+ * @apiVersion 1.0.0
+ * @apiName GetSubscribeUsers
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/subscribeUsers?uids=sogo2,sogo3
+ *
+ * @apiParam {String} uids Comma-separated list of user IDs
+ *
+ * @apiError (Error 400) {Object} error The error message
+ */
 - (id <WOActionResults>) subscribeUsersAction
 {
   id <WOActionResults> response;
   NSString *uids;
   NSArray *userIDs;
   SOGoGCSFolder *folder;
-  NSException *ex;
   int count, max;
   
   uids = [[context request] formValueForKey: @"uids"];
@@ -432,16 +455,12 @@
         [folder subscribeUserOrGroup: [userIDs objectAtIndex: count]
 			    reallyDo: YES
                             response: nil];
-      ex = nil;
+      response = [self responseWith204];
     }
   else
-    ex = [NSException exceptionWithHTTPStatus: 400
-                                       reason: @"missing 'uids' parameter"];
-  
-  if (ex)
-    response = (id <WOActionResults>) ex;
-  else
-    response = [self responseWith204];
+    response = [self responseWithStatus: 400
+                  andJSONRepresentation: [NSDictionary dictionaryWithObject: @"missing 'uids' parameter"
+                                                                     forKey: @"error"]];
   
   return response;
 }

UI/Common/UIxObjectActions.m

@@ -39,6 +39,16 @@
 
 @implementation UIxObjectActions
 
+/**
+ * @api {get} /so/:username/:folderPath/addUserInAcls?uid=:uid Add user to ACLs
+ * @apiVersion 1.0.0
+ * @apiName GetAddUserInAcls
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/addUserInAcls?uid=sogo2
+ *
+ * @apiParam {String} uid User ID
+ */
 - (WOResponse *) addUserInAclsAction
 {
   WOResponse *response;
@@ -57,6 +67,16 @@
   return response;
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/removeUserFromAcls?uid=:uid Remove user from ACLs
+ * @apiVersion 1.0.0
+ * @apiName GetRemoveUserFromAcls
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/removeUserInAcls?uid=sogo2
+ *
+ * @apiParam {String} uid User ID
+ */
 - (WOResponse *) removeUserFromAclsAction
 {
   WOResponse *response;

UI/MailerUI/UIxMailFolderActions.m

@@ -54,10 +54,14 @@
 @implementation UIxMailFolderActions
 
 /**
- * @api {post} /so/:username/Mail/:accountId/:parentMailboxPath/createFolder Create a mailbox
+ * @api {post} /so/:username/Mail/:accountId/:parentMailboxPath/createFolder Create mailbox
  * @apiVersion 1.0.0
  * @apiName PostCreateFolder
  * @apiGroup Mail
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Mail/0/folderINBOX/createFolder \
+ *          -H "Content-Type: application/json" \
+ *          -d '{ "name": "test" }'
  *
  * @apiParam {String} name Name of the mailbox
  *
@@ -92,7 +96,7 @@
           jsonResponse = [NSDictionary dictionaryWithObject: [NSString stringWithFormat: errorFormat, folderName]
                                                      forKey: @"error"];
           response = [self responseWithStatus: 500
-                                    andString: [jsonResponse jsonRepresentation]];
+                        andJSONRepresentation: jsonResponse];
         }
     }
   else
@@ -100,14 +104,14 @@
       jsonResponse = [NSDictionary dictionaryWithObject: [self labelForKey: @"Missing 'name' parameter."]
                                                  forKey: @"error"];
       response = [self responseWithStatus: 500
-                                andString: [jsonResponse jsonRepresentation]];
+                    andJSONRepresentation: jsonResponse];
     }
 
   return response;  
 }
 
 /**
- * @api {post} /so/:username/Mail/:accountId/:mailboxPath/renameFolder Rename a mailbox
+ * @api {post} /so/:username/Mail/:accountId/:mailboxPath/renameFolder Rename mailbox
  * @apiVersion 1.0.0
  * @apiName PostRenameFolder
  * @apiGroup Mail

UI/MainUI/SOGoUserHomePage.m

@@ -480,10 +480,28 @@
   return jsonResponse;
 }
 
+/**
+ * @api {get} /so/:username/usersSearch?search=:search Search for users
+ * @apiVersion 1.0.0
+ * @apiName GetUsersSearch
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/usersSearch?search=john
+ *
+ * @apiParam {String} search Substring to match against username or email address
+ *
+ * @apiSuccess (Success 200) {Object[]} users        List of matching users
+ * @apiSuccess (Success 200) {String} users.uid      User ID
+ * @apiSuccess (Success 200) {String} users.c_email  Main email address
+ * @apiSuccess (Success 200) {String} users.cn       Common name
+ * @apiSuccess (Success 200) {Number} users.isGroup  1 if the user is a group
+ * @apiError   (Error 400) {Object} error            The error message
+ */
 - (id <WOActionResults>) usersSearchAction
 {
   NSMutableArray *users;
   NSArray *currentUsers;
+  NSDictionary *message;
   NSString *contact, *domain, *uidDomain;
   NSEnumerator *visibleDomains;
   id <WOActionResults> result;
@@ -512,11 +530,15 @@
               [users addObjectsFromArray: currentUsers];
             }
         }
-      result = [self responseWithStatus: 200 andJSONRepresentation: users];
+      result = [self responseWithStatus: 200
+                  andJSONRepresentation: [NSDictionary dictionaryWithObject: users forKey: @"users"]];
     }
   else
-    result = [NSException exceptionWithHTTPStatus: 400
-                          reason: @"missing 'search' parameter"];
+    {
+      message = [NSDictionary dictionaryWithObject: [self labelForKey: @"Missing search parameter"]
+                                          forKey: @"error"];
+      result = [self responseWithStatus: 400 andJSONRepresentation: message];
+    }
 
   return result;
 }
@@ -530,15 +552,34 @@
   [response setHeader: @"text/plain; charset=utf-8"
 	    forKey: @"Content-Type"];
 
-  [response appendContentString: [folders JSONRepresentation]];
+  [response appendContentString: [[NSDictionary dictionaryWithObject: folders
+                                                              forKey: @"folders"] JSONRepresentation]];
 
   return response;
 }
 
+/**
+ * @api {get} /so/:username/foldersSearch?type=:type Search for folders
+ * @apiVersion 1.0.0
+ * @apiName GetFoldersSearch
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/foldersSearch?type=contact
+ *
+ * @apiParam {String} type Either 'calendar' or 'contact'
+ *
+ * @apiSuccess (Success 200) {Object[]} folders           List of matching folders
+ * @apiSuccess (Success 200) {String} folders.name        Path of folder
+ * @apiSuccess (Success 200) {String} folders.displayName Human readable name
+ * @apiSuccess (Success 200) {String} folders.owner       Username of owner
+ * @apiSuccess (Success 200) {String} folders.type        Either 'calendar' or 'contact'
+ * @apiError   (Error 400) {Object} error                 The error message
+ */
 - (id <WOActionResults>) foldersSearchAction
 {
   NSString *folderType;
   NSArray *folders;
+  NSDictionary *message;
   id <WOActionResults> result;
   SOGoUserFolder *userFolder;
 
@@ -552,8 +593,11 @@
       result = [self _foldersResponseForResults: folders];
     }
   else
-    result = [NSException exceptionWithHTTPStatus: 400
-                          reason: @"missing 'type' parameter"];
+    {
+      message = [NSDictionary dictionaryWithObject: [self labelForKey: @"Missing type parameter"]
+                                          forKey: @"error"];
+      result = [self responseWithStatus: 400 andJSONRepresentation: message];
+    }
   
   return result;
 }

UI/WebServerResources/js/Common/acl-model.js

@@ -46,10 +46,10 @@
       deferred.resolve(this.users);
     }
     else {
-      return Acl.$$resource.fetch(this.folderId, 'acls').then(function(users) {
+      return Acl.$$resource.fetch(this.folderId, 'acls').then(function(response) {
         _this.users = [];
         // console.debug(JSON.stringify(users, undefined, 2));
-        angular.forEach(users, function(data) {
+        angular.forEach(response.users, function(data) {
           user = new Acl.$User(data);
           user.canSubscribeUser = user.isSubscribed;
           user.wasSubscribed = user.isSubscribed;

UI/WebServerResources/js/Common/user-model.js

@@ -39,9 +39,9 @@
    */
   User.$filter = function(search) {
     var param = {search: search};
-    return User.$$resource.fetch(null, 'usersSearch', param).then(function(users) {
+    return User.$$resource.fetch(null, 'usersSearch', param).then(function(response) {
       var results = [];
-      angular.forEach(users, function(data) {
+      angular.forEach(response.users, function(data) {
         console.debug(JSON.stringify(data, undefined, 2));
         var user = new User(data);
         results.push(user);
@@ -186,9 +186,9 @@
       deferred.resolve(this.$$folders);
     }
     else {
-      User.$$resource.userResource(this.uid).fetch(null, 'foldersSearch', param).then(function(data) {
-        _this.$$folders = data;
-        deferred.resolve(data);
+      User.$$resource.userResource(this.uid).fetch(null, 'foldersSearch', param).then(function(response) {
+        _this.$$folders = response.folders;
+        deferred.resolve(response.folders);
         return data;
       });
     }