diff --git a/docs/api/api.rst b/docs/api/api.rst --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -4,10 +4,9 @@ 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 -/_admin/api . +``/_admin/api``. API access for web views @@ -16,12 +15,12 @@ API access for web views API access can also be turned on for each web view in Kallithea that is 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 +RSS/Atom feed views are enabled. Other views are +only available if they have been whitelisted. Edit the ``api_access_controllers_whitelist`` option in your .ini file and define views that should have API access enabled. -For example, to enable API access to patch/diff raw file and archive:: +For example, to enable API access to patch/diff, raw file and archive:: api_access_controllers_whitelist = ChangesetController:changeset_patch, @@ -33,7 +32,7 @@ After this change, a Kallithea view can GET parameter ``?api_key=`` to the URL. Exposing raw diffs is a good way to integrate with -3rd party services like code review, or build farms that could download archives. +third-party services like code review, or build farms that can download archives. API access @@ -50,27 +49,28 @@ Clients must send JSON encoded JSON-RPC 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"}}' + curl https://example.com/_admin/api -X POST -H 'content-type:text/plain' \ + --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}' 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. + - *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 or set on the user account page + api_key can be found or set on the user account page. The response to the JSON-RPC API call will always be a JSON structure:: { - "id":, # the id that was used in the request - "result": ""|null, # JSON formatted result, null if any errors - "error": "null"| # JSON formatted error (if any) + "id": , # the id that was used in the request + "result": |null, # JSON formatted result (null on error) + "error": null| # JSON formatted error (null on success) } -All responses from API will be ``HTTP/1.0 200 OK``. If there is an error, +All responses from the API will be ``HTTP/1.0 200 OK``. If an error occurs, the reponse will have a failure description in *error* and *result* will be null. @@ -78,7 +78,7 @@ the reponse will have a failure descript API client ++++++++++ -Kallithea comes with a ``kallithea-api`` command line tool providing a convenient +Kallithea comes with a ``kallithea-api`` command line tool, providing a convenient way to call the JSON-RPC API. For example, to call ``get_repo``:: @@ -106,7 +106,7 @@ To avoid specifying ``apihost`` and ``ap kallithea-api --save-config --apihost= --apikey= -This will create a ``~/.config/kallithea`` with the specified hostname and apikey +This will create a ``~/.config/kallithea`` with the specified hostname and API key so you don't have to specify them every time. @@ -136,7 +136,6 @@ OUTPUT:: result : "Pulled from ``" error : null - rescan_repos ------------ @@ -160,7 +159,6 @@ OUTPUT:: 'removed': []}" error : null - invalidate_cache ---------------- @@ -183,7 +181,6 @@ OUTPUT:: result : "Caches of repository ``" error : null - lock ---- @@ -215,7 +212,6 @@ OUTPUT:: } error : null - get_ip ------ @@ -248,7 +244,6 @@ OUTPUT:: error : null - get_user -------- @@ -257,7 +252,6 @@ If userid param is skipped, it is set to 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 : @@ -292,17 +286,14 @@ OUTPUT:: "repositories_groups": {"Group1": "group.read"} }, } - error: null - get_users --------- List all existing users. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -332,6 +323,7 @@ OUTPUT:: ] error: null +.. _create-user: create_user ----------- @@ -339,7 +331,6 @@ create_user Create new user. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -376,6 +367,9 @@ OUTPUT:: } error: null +Example:: + + kallithea-api create_user username:bent email:bent@example.com firstname:Bent lastname:Bentsen extern_type:ldap extern_name:uid=bent,dc=example,dc=com update_user ----------- @@ -383,7 +377,6 @@ update_user 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 : @@ -422,14 +415,12 @@ OUTPUT:: } error: null - delete_user ----------- Delete the given user if such a user exists. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -448,14 +439,12 @@ OUTPUT:: } error: null - get_user_group -------------- Get an existing user group. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -492,14 +481,12 @@ OUTPUT:: } error : null - get_user_groups --------------- List all existing user groups. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -520,14 +507,12 @@ OUTPUT:: ] error : null - create_user_group ----------------- Create a new user group. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -535,7 +520,7 @@ INPUT:: method : "create_user_group" args: { "group_name": "", - "owner" : "", + "owner" : "", "active": " = Optional(True)" } @@ -552,7 +537,6 @@ OUTPUT:: } error: null - add_user_to_user_group ---------------------- @@ -560,7 +544,6 @@ Adds a user to a user group. If the user ``false``. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -581,7 +564,6 @@ OUTPUT:: } error: null - remove_user_from_user_group --------------------------- @@ -589,7 +571,6 @@ Remove a user from a user group. If the be ``false``. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -610,7 +591,6 @@ OUTPUT:: } error: null - get_repo -------- @@ -700,7 +680,6 @@ OUTPUT:: } error: null - get_repos --------- @@ -708,7 +687,6 @@ 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 : @@ -725,7 +703,7 @@ OUTPUT:: "repo_name" : "" "repo_type" : "", "clone_uri" : "", - "private": : "", + "private" : "", "created_on" : "", "description" : "", "landing_rev": "", @@ -739,7 +717,6 @@ OUTPUT:: ] error: null - get_repo_nodes -------------- @@ -747,7 +724,6 @@ Return a list of files and directories f It is 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 : @@ -772,7 +748,6 @@ OUTPUT:: ] error: null - create_repo ----------- @@ -784,7 +759,6 @@ This command can only be executed using or that of a regular user with create repository permission. Regular users cannot specify owner parameter. - INPUT:: id : @@ -792,7 +766,7 @@ INPUT:: method : "create_repo" args: { "repo_name" : "", - "owner" : "", + "owner" : "", "repo_type" : " = Optional('hg')", "description" : " = Optional('')", "private" : " = Optional(False)", @@ -813,7 +787,7 @@ OUTPUT:: "repo_name" : "" "repo_type" : "", "clone_uri" : "", - "private": : "", + "private" : "", "created_on" : "", "description" : "", "landing_rev": "", @@ -826,6 +800,65 @@ OUTPUT:: } error: null +update_repo +----------- + +Update 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 create repository permission. +Regular users cannot specify owner parameter. + +INPUT:: + + id : + api_key : "" + method : "update_repo" + args: { + "repoid" : "" + "name" : " = Optional('')", + "group" : " = Optional(None)", + "owner" : "", + "description" : " = Optional('')", + "private" : " = Optional(False)", + "clone_uri" : " = Optional(None)", + "landing_rev" : " = Optional('tip')", + "enable_downloads": " = Optional(False)", + "enable_locking": " = Optional(False)", + "enable_statistics": " = Optional(False)", + } + +OUTPUT:: + + id : + result: { + "msg": "updated repo ID:repo_id ``", + "repository": { + "repo_id" : "", + "repo_name" : "" + "repo_type" : "", + "clone_uri" : "", + "private": "", + "created_on" : "", + "description" : "", + "landing_rev": "", + "owner": "", + "fork_of": "", + "enable_downloads": "", + "enable_locking": "", + "enable_statistics": "", + "last_changeset": { + "author": "", + "date": "", + "message": "", + "raw_id": "", + "revision": "", + "short_id": "" + } + "locked_by": "", + "locked_date": "", + }, + } + error: null fork_repo --------- @@ -838,7 +871,6 @@ rights, or with the global fork permissi repository permission and at least read access to the repository. Regular users cannot specify owner parameter. - INPUT:: id : @@ -864,7 +896,6 @@ OUTPUT:: } error: null - delete_repo ----------- @@ -873,7 +904,6 @@ This command can only be executed using or that of a regular user with admin access to the repository. When ``forks`` param is set it is possible to detach or delete forks of the deleted repository. - INPUT:: id : @@ -893,14 +923,12 @@ OUTPUT:: } error: null - grant_user_permission --------------------- Grant permission for a user on the given repository, or update the existing one if found. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -921,14 +949,12 @@ OUTPUT:: } error: null - revoke_user_permission ---------------------- Revoke permission for a user on the given repository. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -948,7 +974,6 @@ OUTPUT:: } error: null - grant_user_group_permission --------------------------- @@ -956,7 +981,6 @@ Grant permission for a user group on the existing one if found. This command can only be executed using the api_key of a user with admin rights. - INPUT:: id : @@ -977,7 +1001,6 @@ OUTPUT:: } error: null - revoke_user_group_permission ----------------------------