docs: improve the API documentation

docs/api/api.rst

@@ -1,1012 +1,1002 b''
 .. _api:
 
 ===
 API
 ===
 
 
-Starting from Kallithea version 1.2 a simple API was implemented.
-There's a single schema for calling all api methods. API is implemented
-with JSON protocol both ways. An url to send API request to Kallithea is
-<your_server>/_admin/api
+Kallithea has a simple JSON RPC API with a single schema for calling all api
+methods. Everything is available by sending JSON encoded http(s) requests to
+<your_server>/_admin/api .
+
 
 API ACCESS FOR WEB VIEWS
 ++++++++++++++++++++++++
 
 API access can also be turned on for each web view in Kallithea that is
-decorated with `@LoginRequired` decorator. To enable API access simple change
-the standard login decorator to `@LoginRequired(api_access=True)`.
+decorated with the `@LoginRequired` decorator. Some views use
+`@LoginRequired(api_access=True)` and are always available. By default only
+RSS/ATOM feed views are enabled. Other views are
+only available if they have been white listed. Edit the
+`api_access_controllers_whitelist` option in your .ini file and define views
+that should have API access enabled.
 
-To make this operation easier, starting from version 1.7.0 there's a white list
-of views that will have API access enabled. Simply edit `api_access_controllers_whitelist`
-option in your .ini file, and define views that should have API access enabled.
-Following example shows how to enable API access to patch/diff raw file and archive
-in Kallithea::
+For example, to enable API access to patch/diff raw file and archive::
 
     api_access_controllers_whitelist =
         ChangesetController:changeset_patch,
         ChangesetController:changeset_raw,
         FilesController:raw,
         FilesController:archivefile
 
+After this change, a Kallithea view can be accessed without login by adding a
+GET parameter `?api_key=<api_key>` to url.
 
-After this change, a Kallithea view can be accessed without login by adding a
-GET parameter `?api_key=<api_key>` to url. By default this is only
-enabled on RSS/ATOM feed views. Exposing raw diffs is a good way to integrate with
+Exposing raw diffs is a good way to integrate with
 3rd party services like code review, or build farms that could download archives.
 
 
 API ACCESS
 ++++++++++
 
-All clients are required to send JSON-RPC spec JSON data::
+Clients must send JSON encoded JSON-RPC requests::
 
     {
-        "id:"<id>",
-        "api_key":"<api_key>",
-        "method":"<method_name>",
-        "args":{"<arg_key>":"<arg_val>"}
+        "id: "<id>",
+        "api_key": "<api_key>",
+        "method": "<method_name>",
+        "args": {"<arg_key>": "<arg_val>"}
     }
 
-Example call for autopulling remotes repos using curl::
+For example, to pull to a local "CPython" mirror using curl::
+
     curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'
 
-Simply provide
- - *id* A value of any type, which is used to match the response with the request that it is replying to.
- - *api_key* for access and permission validation.
- - *method* is name of method to call
- - *args* is an key:value list of arguments to pass to method
+In general, provide
+ - *id*, a value of any type, can be used to match the response with the request that it is replying to.
+ - *api_key*, for authentication and permission validation.
+ - *method*, the name of the method to call - a list of available methods can be found below.
+ - *args*, the arguments to pass to the method.
 
 .. note::
 
-    api_key can be found in your user account page
+    api_key can be found or set on the user account page
 
-
-Kallithea API will return always a JSON-RPC response::
+The response to the JSON-RPC API call will always be a JSON structure::
 
     {
-        "id":<id>, # matching id sent by request
+        "id":<id>, # the id that was used in the request
         "result": "<result>"|null, # JSON formatted result, null if any errors
         "error": "null"|<error_message> # JSON formatted error (if any)
     }
 
-All responses from API will be `HTTP/1.0 200 OK`, if there's an error while
-calling api *error* key from response will contain failure description
-and result will be null.
+All responses from API will be `HTTP/1.0 200 OK`. If there is an error,
+the reponse will have a failure description in *error* and
+*result* will be null.
 
 
 API CLIENT
 ++++++++++
 
-From version 1.4 Kallithea adds a script that allows to easily
-communicate with API. After installing Kallithea a `kallithea-api` script
-will be available.
-
-To get started quickly simply run::
-
-  kallithea-api _create_config --apikey=<youapikey> --apihost=<your.kallithea.server>
+Kallithea comes with a `kallithea-api` command line tool providing a convenient
+way to call the JSON-RPC API.
 
-This will create a file named .config in the directory you executed it storing
-json config file with credentials. You can skip this step and always provide
-both of the arguments to be able to communicate with server
+For example, to call `get_repo`::
 
-
-after that simply run any api command for example get_repo::
-
- kallithea-api get_repo
+ kallithea-api --apihost=<your.kallithea.server.url> --apikey=<yourapikey> get_repo
 
  calling {"api_key": "<apikey>", "id": 75, "args": {}, "method": "get_repo"} to http://127.0.0.1:5000
  Kallithea said:
  {'error': 'Missing non optional `repoid` arg in JSON DATA',
   'id': 75,
   'result': None}
 
-Ups looks like we forgot to add an argument
-
-Let's try again now giving the repoid as parameters::
+Oops, looks like we forgot to add an argument. Let's try again, now providing the repoid as parameter::
 
     kallithea-api get_repo repoid:myrepo
 
     calling {"api_key": "<apikey>", "id": 39, "args": {"repoid": "myrepo"}, "method": "get_repo"} to http://127.0.0.1:5000
     Kallithea said:
     {'error': None,
      'id': 39,
      'result': <json data...>}
 
+To avoid specifying apihost and apikey every time, run::
+
+  kallithea-api --save-config --apihost=<your.kallithea.server.url> --apikey=<yourapikey>
+
+This will create a `~/.config/kallithea` with the specified hostname and apikey
+so you don't have to specify them every time.
 
 
 API METHODS
 +++++++++++
 
 
 pull
 ----
 
-Pulls given repo from remote location. Can be used to automatically keep
-remote repos up to date. This command can be executed only using api_key
-belonging to user with admin rights
+Pull the given repo from remote location. Can be used to automatically keep
+remote repos up to date.
+This command can only be executed using the api_key of a user with admin rights.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "pull"
     args :    {
                 "repoid" : "<reponame or repo_id>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : "Pulled from `<reponame>`"
     error :  null
 
 
 rescan_repos
 ------------
 
-Dispatch rescan repositories action. If remove_obsolete is set
+Rescan repositories. If remove_obsolete is set,
 Kallithea will delete repos that are in database but not in the filesystem.
-This command can be executed only using api_key belonging to user with admin
-rights.
+This command can only be executed using the api_key of a user with admin rights.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "rescan_repos"
     args :    {
                 "remove_obsolete" : "<boolean = Optional(False)>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : "{'added': [<list of names of added repos>],
                'removed': [<list of names of removed repos>]}"
     error :  null
 
 
 invalidate_cache
 ----------------
 
 Invalidate cache for repository.
-This command can be executed only using api_key belonging to user with admin
-rights or regular user that have write or admin or write access to repository.
+This command can only be executed using the api_key of a user with admin rights,
+or that of a regular user with admin or write access to the repository.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "invalidate_cache"
     args :    {
                 "repoid" : "<reponame or repo_id>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : "Caches of repository `<reponame>`"
     error :  null
 
+
 lock
 ----
 
-Set locking state on given repository by given user. If userid param is skipped
-, then it is set to id of user whos calling this method. If locked param is skipped
-then function shows current lock state of given repo.
-This command can be executed only using api_key belonging to user with admin
-rights or regular user that have admin or write access to repository.
+Set the locking state on the given repository by the given user.
+If param 'userid' is skipped, it is set to the id of the user who is calling this method.
+If param 'locked' is skipped, the current lock state of the repository is returned.
+This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin or write access to the repository.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "lock"
     args :    {
                 "repoid" : "<reponame or repo_id>"
                 "userid" : "<user_id or username = Optional(=apiuser)>",
                 "locked" : "<bool true|false = Optional(=None)>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : {
                  "repo": "<reponame>",
                  "locked": "<bool true|false>",
                  "locked_since": "<float lock_time>",
                  "locked_by": "<username>",
                  "msg": "User `<username>` set lock state for repo `<reponame>` to `<false|true>`"
              }
     error :  null
 
 
 get_ip
 ------
 
-Shows IP address as seen from Kallithea server, together with all
+Return IP address as seen from Kallithea server, together with all
 defined IP addresses for given user.
-This command can be executed only using api_key belonging to user with admin
-rights.
+This command can only be executed using the api_key of a user with admin rights.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_ip"
     args :    {
                 "userid" : "<user_id or username>",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : {
                  "ip_addr_server": <ip_from_clien>",
                  "user_ips": [
                                 {
                                    "ip_addr": "<ip_with_mask>",
                                    "ip_range": ["<start_ip>", "<end_ip>"],
                                 },
                                 ...
                              ]
              }
 
     error :  null
 
 
 get_user
 --------
 
-Gets an user by username or user_id, Returns empty result if user is not found.
-If userid param is skipped it is set to id of user who is calling this method.
-This command can be executed only using api_key belonging to user with admin
-rights, or regular users that cannot specify different userid than theirs
+Get a user by username or userid. The result is empty if user can't be found.
+If userid param is skipped, it is set to id of user who is calling this method.
+Any userid can be specified when the command is executed using the api_key of a user with admin rights.
+Regular users can only speicy their own userid.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_user"
     args :    {
                 "userid" : "<username or user_id Optional(=apiuser)>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: None if user does not exist or
             {
                 "user_id" :     "<user_id>",
                 "api_key" :     "<api_key>",
                 "username" :    "<username>",
                 "firstname":    "<firstname>",
                 "lastname" :    "<lastname>",
                 "email" :       "<email>",
                 "emails":       "<list_of_all_additional_emails>",
                 "ip_addresses": "<list_of_ip_addresses_for_user>",
                 "active" :      "<bool>",
                 "admin" :       "<bool>",
                 "ldap_dn" :     "<ldap_dn>",
                 "last_login":   "<last_login>",
                 "permissions": {
                     "global": ["hg.create.repository",
                                "repository.read",
                                "hg.register.manual_activate"],
                     "repositories": {"repo1": "repository.none"},
                     "repositories_groups": {"Group1": "group.read"}
                  },
             }
 
     error:  null
 
 
 get_users
 ---------
 
-Lists all existing users. This command can be executed only using api_key
-belonging to user with admin rights.
+List all existing users.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_users"
     args :    { }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: [
               {
                 "user_id" :     "<user_id>",
                 "api_key" :     "<api_key>",
                 "username" :    "<username>",
                 "firstname":    "<firstname>",
                 "lastname" :    "<lastname>",
                 "email" :       "<email>",
                 "emails":       "<list_of_all_additional_emails>",
                 "ip_addresses": "<list_of_ip_addresses_for_user>",
                 "active" :      "<bool>",
                 "admin" :       "<bool>",
                 "ldap_dn" :     "<ldap_dn>",
                 "last_login":   "<last_login>",
               },
               …
             ]
     error:  null
 
 
 create_user
 -----------
 
-Creates new user. This command can
-be executed only using api_key belonging to user with admin rights.
+Create new user.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "create_user"
     args :    {
                 "username" :  "<username>",
                 "email" :     "<useremail>",
                 "password" :  "<password = Optional(None)>",
                 "firstname" : "<firstname> = Optional(None)",
                 "lastname" :  "<lastname> = Optional(None)",
                 "active" :    "<bool> = Optional(True)",
                 "admin" :     "<bool> = Optional(False)",
                 "ldap_dn" :   "<ldap_dn> = Optional(None)"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "created new user `<username>`",
               "user": {
                 "user_id" :  "<user_id>",
                 "username" : "<username>",
                 "firstname": "<firstname>",
                 "lastname" : "<lastname>",
                 "email" :    "<email>",
                 "emails":    "<list_of_all_additional_emails>",
                 "active" :   "<bool>",
                 "admin" :    "<bool>",
                 "ldap_dn" :  "<ldap_dn>",
                 "last_login": "<last_login>",
               },
             }
     error:  null
 
 
 update_user
 -----------
 
-updates given user if such user exists. This command can
-be executed only using api_key belonging to user with admin rights.
+Update the given user if such user exists.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "update_user"
     args :    {
                 "userid" : "<user_id or username>",
                 "username" :  "<username> = Optional(None)",
                 "email" :     "<useremail> = Optional(None)",
                 "password" :  "<password> = Optional(None)",
                 "firstname" : "<firstname> = Optional(None)",
                 "lastname" :  "<lastname> = Optional(None)",
                 "active" :    "<bool> = Optional(None)",
                 "admin" :     "<bool> = Optional(None)",
                 "ldap_dn" :   "<ldap_dn> = Optional(None)"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "updated user ID:<userid> <username>",
               "user": {
                 "user_id" :  "<user_id>",
                 "api_key" :  "<api_key>",
                 "username" : "<username>",
                 "firstname": "<firstname>",
                 "lastname" : "<lastname>",
                 "email" :    "<email>",
                 "emails":    "<list_of_all_additional_emails>",
                 "active" :   "<bool>",
                 "admin" :    "<bool>",
                 "ldap_dn" :  "<ldap_dn>",
                 "last_login": "<last_login>",
               },
             }
     error:  null
 
 
 delete_user
 -----------
 
-
-deletes givenuser if such user exists. This command can
-be executed only using api_key belonging to user with admin rights.
+Delete given user if such user exists.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "delete_user"
     args :    {
                 "userid" : "<user_id or username>",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "deleted user ID:<userid> <username>",
               "user": null
             }
     error:  null
 
 
 get_user_group
 --------------
 
-Gets an existing user group. This command can be executed only using api_key
-belonging to user with admin rights.
+Get an existing user group.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_user_group"
     args :    {
                 "usergroupid" : "<user group id or name>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : None if group not exist
              {
                "users_group_id" : "<id>",
                "group_name" :     "<groupname>",
                "active":          "<bool>",
                "members" :  [
                               {
                                 "user_id" :  "<user_id>",
                                 "api_key" :  "<api_key>",
                                 "username" : "<username>",
                                 "firstname": "<firstname>",
                                 "lastname" : "<lastname>",
                                 "email" :    "<email>",
                                 "emails":    "<list_of_all_additional_emails>",
                                 "active" :   "<bool>",
                                 "admin" :    "<bool>",
                                 "ldap_dn" :  "<ldap_dn>",
                                 "last_login": "<last_login>",
                               },
                               …
                             ]
              }
     error : null
 
 
 get_user_groups
 ---------------
 
-Lists all existing user groups. This command can be executed only using
-api_key belonging to user with admin rights.
+List all existing user groups.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_user_groups"
     args :    { }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result : [
                {
                "users_group_id" : "<id>",
                "group_name" :     "<groupname>",
                "active":          "<bool>",
                },
                …
               ]
     error : null
 
 
 create_user_group
 -----------------
 
-Creates new user group. This command can be executed only using api_key
-belonging to user with admin rights
+Create a new user group.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "create_user_group"
     args:     {
                 "group_name": "<groupname>",
                 "owner" :     "<onwer_name_or_id = Optional(=apiuser)>",
                 "active":     "<bool> = Optional(True)"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg": "created new user group `<groupname>`",
               "users_group": {
                      "users_group_id" : "<id>",
                      "group_name" :     "<groupname>",
                      "active":          "<bool>",
                },
             }
     error:  null
 
 
 add_user_to_user_group
 ----------------------
 
-Adds a user to a user group. If user exists in that group success will be
-`false`. This command can be executed only using api_key
-belonging to user with admin rights
+Addsa user to a user group. If the user already is in that group, success will be
+`false`.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "add_user_user_group"
     args:     {
                 "usersgroupid" : "<user group id or name>",
                 "userid" : "<user_id or username>",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "success": True|False # depends on if member is in group
-              "msg": "added member `<username>` to user group `<groupname>` |
+              "msg": "added member `<username>` to a user group `<groupname>` |
                       User is already in that group"
             }
     error:  null
 
 
 remove_user_from_user_group
 ---------------------------
 
-Removes a user from a user group. If user is not in given group success will
-be `false`. This command can be executed only
-using api_key belonging to user with admin rights
+Remove a user from a user group. If the user isn't in the given group, success will
+be `false`.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "remove_user_from_user_group"
     args:     {
                 "usersgroupid" : "<user group id or name>",
                 "userid" : "<user_id or username>",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "success":  True|False,  # depends on if member is in group
               "msg": "removed member <username> from user group <groupname> |
                       User wasn't in group"
             }
     error:  null
 
 
 get_repo
 --------
 
-Gets an existing repository by it's name or repository_id. Members will return
-either users_group or user associated to that repository. This command can be
-executed only using api_key belonging to user with admin
-rights or regular user that have at least read access to repository.
-
+Get an existing repository by its name or repository_id. Members will contain
+either users_group or user associated to that repository.
+This command can only be executed using the api_key of a user with admin rights,
+or that of a regular user with at least read access to the repository.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_repo"
     args:     {
                 "repoid" : "<reponame or repo_id>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: None if repository does not exist or
             {
                 "repo_id" :          "<repo_id>",
                 "repo_name" :        "<reponame>"
                 "repo_type" :        "<repo_type>",
                 "clone_uri" :        "<clone_uri>",
                 "enable_downloads":  "<bool>",
                 "enable_locking":    "<bool>",
                 "enable_statistics": "<bool>",
                 "private":           "<bool>",
                 "created_on" :       "<date_time_created>",
                 "description" :      "<description>",
                 "landing_rev":       "<landing_rev>",
                 "last_changeset":    {
                                        "author":   "<full_author>",
                                        "date":     "<date_time_of_commit>",
                                        "message":  "<commit_message>",
                                        "raw_id":   "<raw_id>",
                                        "revision": "<numeric_revision>",
                                        "short_id": "<short_id>"
                                      }
                 "owner":             "<repo_owner>",
                 "fork_of":           "<name_of_fork_parent>",
                 "members" :     [
                                   {
                                     "type":        "user",
                                     "user_id" :    "<user_id>",
                                     "api_key" :    "<api_key>",
                                     "username" :   "<username>",
                                     "firstname":   "<firstname>",
                                     "lastname" :   "<lastname>",
                                     "email" :      "<email>",
                                     "emails":      "<list_of_all_additional_emails>",
                                     "active" :     "<bool>",
                                     "admin" :      "<bool>",
                                     "ldap_dn" :    "<ldap_dn>",
                                     "last_login":  "<last_login>",
                                     "permission" : "repository.(read|write|admin)"
                                   },
                                   …
                                   {
                                     "type":      "users_group",
                                     "id" :       "<usersgroupid>",
                                     "name" :     "<usersgroupname>",
                                     "active":    "<bool>",
                                     "permission" : "repository.(read|write|admin)"
                                   },
                                   …
                                 ]
                  "followers":   [
                                   {
                                     "user_id" :     "<user_id>",
                                     "username" :    "<username>",
                                     "api_key" :     "<api_key>",
                                     "firstname":    "<firstname>",
                                     "lastname" :    "<lastname>",
                                     "email" :       "<email>",
                                     "emails":       "<list_of_all_additional_emails>",
                                     "ip_addresses": "<list_of_ip_addresses_for_user>",
                                     "active" :      "<bool>",
                                     "admin" :       "<bool>",
                                     "ldap_dn" :     "<ldap_dn>",
                                     "last_login":   "<last_login>",
                                   },
                                   …
                  ]
             }
     error:  null
 
 
 get_repos
 ---------
 
-Lists all existing repositories. This command can be executed only using
-api_key belonging to user with admin rights or regular user that have
-admin, write or read access to repository.
+List all existing repositories.
+This command can only be executed using the api_key of a user with admin rights,
+or that of a regular user with at least read access to the repository.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_repos"
     args:     { }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: [
               {
                 "repo_id" :          "<repo_id>",
                 "repo_name" :        "<reponame>"
                 "repo_type" :        "<repo_type>",
                 "clone_uri" :        "<clone_uri>",
                 "private": :         "<bool>",
                 "created_on" :       "<datetimecreated>",
                 "description" :      "<description>",
                 "landing_rev":       "<landing_rev>",
                 "owner":             "<repo_owner>",
                 "fork_of":           "<name_of_fork_parent>",
                 "enable_downloads":  "<bool>",
                 "enable_locking":    "<bool>",
                 "enable_statistics": "<bool>",
               },
               …
             ]
     error:  null
 
 
 get_repo_nodes
 --------------
 
-returns a list of nodes and it's children in a flat list for a given path
-at given revision. It's possible to specify ret_type to show only `files` or
-`dirs`. This command can be executed only using api_key belonging to user
-with admin rights
+Return a list of files and directories for a given path at the given revision.
+It's possible to specify ret_type to show only `files` or `dirs`.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_repo_nodes"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "revision"  : "<revision>",
                 "root_path" : "<root_path>",
                 "ret_type"  : "<ret_type> = Optional('all')"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: [
               {
                 "name" :        "<name>"
                 "type" :        "<type>",
               },
               …
             ]
     error:  null
 
 
 create_repo
 -----------
 
-Creates a repository. If repository name contains "/", all needed repository
-groups will be created. For example "foo/bar/baz" will create groups
+Create a repository. If repository name contains "/", all needed repository
+groups will be created. For example "foo/bar/baz" will create repository groups
 "foo", "bar" (with "foo" as parent), and create "baz" repository with
-"bar" as group. This command can be executed only using api_key belonging to user with admin
-rights or regular user that have create repository permission. Regular users
-cannot specify owner parameter
+"bar" as group.
+This command can only be executed using the api_key of a user with admin rights,
+or that of a regular user with create repository permission.
+Regular users cannot specify owner parameter.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "create_repo"
     args:     {
                 "repo_name" :        "<reponame>",
                 "owner" :            "<onwer_name_or_id = Optional(=apiuser)>",
                 "repo_type" :        "<repo_type> = Optional('hg')",
                 "description" :      "<description> = Optional('')",
                 "private" :          "<bool> = Optional(False)",
                 "clone_uri" :        "<clone_uri> = Optional(None)",
                 "landing_rev" :      "<landing_rev> = Optional('tip')",
                 "enable_downloads":  "<bool> = Optional(False)",
                 "enable_locking":    "<bool> = Optional(False)",
                 "enable_statistics": "<bool> = Optional(False)",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg": "Created new repository `<reponame>`",
               "repo": {
                 "repo_id" :          "<repo_id>",
                 "repo_name" :        "<reponame>"
                 "repo_type" :        "<repo_type>",
                 "clone_uri" :        "<clone_uri>",
                 "private": :         "<bool>",
                 "created_on" :       "<datetimecreated>",
                 "description" :      "<description>",
                 "landing_rev":       "<landing_rev>",
                 "owner":             "<username or user_id>",
                 "fork_of":           "<name_of_fork_parent>",
                 "enable_downloads":  "<bool>",
                 "enable_locking":    "<bool>",
                 "enable_statistics": "<bool>",
               },
             }
     error:  null
 
 
 fork_repo
 ---------
 
-Creates a fork of given repo. In case of using celery this will
-immidiatelly return success message, while fork is going to be created
-asynchronous. This command can be executed only using api_key belonging to
-user with admin rights or regular user that have fork permission, and at least
-read access to forking repository. Regular users cannot specify owner parameter.
+Create a fork of given repo. If using celery, this will
+return success message immidiatelly and fork will be created
+asynchronously.
+This command can only be executed using the api_key of a user with admin rights,
+or that of a regular user with fork permission and at least read access to the repository.
+Regular users cannot specify owner parameter.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "fork_repo"
     args:     {
                 "repoid" :          "<reponame or repo_id>",
                 "fork_name":        "<forkname>",
                 "owner":            "<username or user_id = Optional(=apiuser)>",
                 "description":      "<description>",
                 "copy_permissions": "<bool>",
                 "private":          "<bool>",
                 "landing_rev":      "<landing_rev>"
 
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg": "Created fork of `<reponame>` as `<forkname>`",
               "success": true
             }
     error:  null
 
 
 delete_repo
 -----------
 
-Deletes a repository. This command can be executed only using api_key belonging
-to user with admin rights or regular user that have admin access to repository.
-When `forks` param is set it's possible to detach or delete forks of deleting
-repository
+Delete a repository.
+This command can only be executed using the api_key of a user with admin rights,
+or that of a regular user with admin access to the repository.
+When `forks` param is set it's possible to detach or delete forks of the deleted repository.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "delete_repo"
     args:     {
                 "repoid" : "<reponame or repo_id>",
                 "forks"  : "`delete` or `detach` = Optional(None)"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg": "Deleted repository `<reponame>`",
               "success": true
             }
     error:  null
 
 
 grant_user_permission
 ---------------------
 
-Grant permission for user on given repository, or update existing one
-if found. This command can be executed only using api_key belonging to user
-with admin rights.
+Grant permission for user on given repository, or update existing one if found.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "grant_user_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "userid" : "<username or user_id>"
                 "perm" :       "(repository.(none|read|write|admin))",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
               "success": true
             }
     error:  null
 
 
 revoke_user_permission
 ----------------------
 
-Revoke permission for user on given repository. This command can be executed
-only using api_key belonging to user with admin rights.
+Revoke permission for user on given repository.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method  : "revoke_user_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "userid" : "<username or user_id>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
               "success": true
             }
     error:  null
 
 
 grant_user_group_permission
 ---------------------------
 
 Grant permission for user group on given repository, or update
-existing one if found. This command can be executed only using
-api_key belonging to user with admin rights.
+existing one if found.
+This command can only be executed using the api_key of a user with admin rights.
 
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "grant_user_group_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "usersgroupid" : "<user group id or name>"
                 "perm" : "(repository.(none|read|write|admin))",
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
               "success": true
             }
     error:  null
 
 
 revoke_user_group_permission
 ----------------------------
 
-Revoke permission for user group on given repository.This command can be
-executed only using api_key belonging to user with admin rights.
+Revoke permission for user group on given repository.
+This command can only be executed using the api_key of a user with admin rights.
 
 INPUT::
 
     id : <id_for_response>
     api_key : "<api_key>"
     method  : "revoke_user_group_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "usersgroupid" : "<user group id or name>"
               }
 
 OUTPUT::
 
     id : <id_given_in_input>
     result: {
               "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
               "success": true
             }
     error:  null