##// END OF EJS Templates
API changes...
API changes - added removed_user_from_users_group function - fixed errors on wrong username - normalized add/remove members from groups functions - docs updates

File last commit:

r1989:0f87c784 beta
r1989:0f87c784 beta
Show More
api.rst
570 lines | 14.3 KiB | text/x-rst | RstLexer
API docs
r1446 .. _api:
API
===
Starting from RhodeCode version 1.2 a simple API was implemented.
Extended API...
r1500 There's a single schema for calling all api methods. API is implemented
Nicolas VINOT
[API] Update doc
r1592 with JSON protocol both ways. An url to send API request in RhodeCode is
Extended API...
r1500 <your_server>/_admin/api
API docs
r1446
docs update
r1839 API ACCESS FOR WEB VIEWS
++++++++++++++++++++++++
API docs
r1446
docs update
r1911 API access can also be turned on for each web view in RhodeCode that is
decorated with `@LoginRequired` decorator. To enable API access simple change
the standard login decorator to `@LoginRequired(api_access=True)`.
After this change, a rhodecode view can be accessed without login by adding a
GET parameter `?api_key=<api_key>` to url. By default this is only
Added instruction on enabling the API access to web views
r1812 enabled on RSS/ATOM feed views.
docs update
r1839 API ACCESS
++++++++++
changed API to match fully JSON-RPC specs
r1708 All clients are required to send JSON-RPC spec JSON data::
API docs
r1446
changed API to match fully JSON-RPC specs
r1708 {
"id:<id>,
API docs
r1446 "api_key":"<api_key>",
"method":"<method_name>",
"args":{"<arg_key>":"<arg_val>"}
}
Extended API...
r1500 Example call for autopulling remotes repos using curl::
changed API to match fully JSON-RPC specs
r1708 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"}}'
Extended API...
r1500
Nicolas VINOT
[API] Update doc
r1592 Simply provide
changed API to match fully JSON-RPC specs
r1708 - *id* A value of any type, which is used to match the response with the request that it is replying to.
Extended API...
r1500 - *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
Nicolas VINOT
[API] Update doc
r1592
API docs
r1446 .. note::
Nicolas VINOT
[API] Update doc
r1592
api_key can be found in your user account page
changed API to match fully JSON-RPC specs
r1708 RhodeCode API will return always a JSON-RPC response::
Nicolas VINOT
[API] Update doc
r1592
changed API to match fully JSON-RPC specs
r1708 {
"id":<id>,
Nicolas VINOT
[API] Update doc
r1592 "result": "<result>",
API docs
r1446 "error": null
}
All responses from API will be `HTTP/1.0 200 OK`, if there's an error while
Nicolas VINOT
[API] Update doc
r1592 calling api *error* key from response will contain failure description
API docs
r1446 and result will be null.
API METHODS
+++++++++++
Nicolas VINOT
[API] Update doc
r1592
API docs
r1446 pull
----
Nicolas VINOT
[API] Update doc
r1592 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
Extended API...
r1500 belonging to user with admin rights
INPUT::
Nicolas VINOT
[API] Update doc
r1592 api_key : "<api_key>"
method : "pull"
args : {
api review...
r1843 "repo_name" : "<reponame>"
Nicolas VINOT
[API] Update doc
r1592 }
OUTPUT::
api review...
r1843 result : "Pulled from <reponame>"
Nicolas VINOT
[API] Update doc
r1592 error : null
api review...
r1843 get_user
--------
Get's an user by username, Returns empty result if user is not found.
This command can be executed only using api_key belonging to user with admin
rights.
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 INPUT::
api_key : "<api_key>"
method : "get_user"
args : {
"username" : "<username>"
}
OUTPUT::
result: None if user does not exist or
{
"id" : "<id>",
"username" : "<username>",
"firstname": "<firstname>",
"lastname" : "<lastname>",
"email" : "<email>",
"active" : "<bool>",
"admin" :  "<bool>",
"ldap" : "<ldap_dn>"
}
error: null
Nicolas VINOT
[API] Update doc
r1592 get_users
---------
Lists all existing users. This command can be executed only using api_key
belonging to user with admin rights.
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 INPUT::
api_key : "<api_key>"
method : "get_users"
args : { }
OUTPUT::
result: [
{
"id" : "<id>",
"username" : "<username>",
"firstname": "<firstname>",
"lastname" : "<lastname>",
"email" : "<email>",
"active" : "<bool>",
"admin" :  "<bool>",
"ldap" : "<ldap_dn>"
},
…
]
error: null
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 create_user
-----------
create user api_doc update
r1909 Creates new user or updates current one if such user exists. This command can
be executed only using api_key belonging to user with admin rights.
Nicolas VINOT
[API] Update doc
r1592
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 INPUT::
api_key : "<api_key>"
method : "create_user"
args : {
"username" : "<username>",
"password" : "<password>",
#344 optional firstname lastname on user creation...
r1950 "email" : "<useremail>",
"firstname" : "<firstname> = None",
"lastname" : "<lastname> = None",
Nicolas VINOT
[API] Update doc
r1592 "active" : "<bool> = True",
"admin" : "<bool> = False",
"ldap_dn" : "<ldap_dn> = None"
}
Extended API...
r1500
OUTPUT::
Nicolas VINOT
[API] Update doc
r1592 result: {
api review...
r1843 "id" : "<new_user_id>",
Nicolas VINOT
[API] Update doc
r1592 "msg" : "created new user <username>"
}
error: null
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 get_users_group
---------------
Gets an existing users group. This command can be executed only using api_key
belonging to user with admin rights.
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 INPUT::
api_key : "<api_key>"
method : "get_users_group"
args : {
"group_name" : "<name>"
}
OUTPUT::
result : None if group not exist
{
api review...
r1843 "id" : "<id>",
"group_name" : "<groupname>",
"active": "<bool>",
Nicolas VINOT
[API] Update doc
r1592 "members" : [
api review...
r1843 { "id" : "<userid>",
"username" : "<username>",
"firstname": "<firstname>",
"lastname" : "<lastname>",
"email" : "<email>",
"active" : "<bool>",
"admin" :  "<bool>",
"ldap" : "<ldap_dn>"
},
…
]
Nicolas VINOT
[API] Update doc
r1592 }
error : null
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 get_users_groups
----------------
Lists all existing users groups. This command can be executed only using
api_key belonging to user with admin rights.
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 INPUT::
api_key : "<api_key>"
method : "get_users_groups"
args : { }
OUTPUT::
result : [
{
"id" : "<id>",
"group_name" : "<groupname>",
"active": "<bool>",
"members" : [
{
"id" : "<userid>",
"username" : "<username>",
"firstname": "<firstname>",
"lastname" : "<lastname>",
"email" : "<email>",
"active" : "<bool>",
"admin" :  "<bool>",
"ldap" : "<ldap_dn>"
},
…
]
}
]
error : null
Extended API...
r1500 create_users_group
------------------
Nicolas VINOT
[API] Update doc
r1592 Creates new users group. This command can be executed only using api_key
Extended API...
r1500 belonging to user with admin rights
#227 Initial version of repository groups permissions system...
r1982
Extended API...
r1500 INPUT::
Nicolas VINOT
[API] Update doc
r1592 api_key : "<api_key>"
method : "create_users_group"
args: {
api review...
r1843 "group_name": "<groupname>",
Nicolas VINOT
[API] Update doc
r1592 "active":"<bool> = True"
}
OUTPUT::
result: {
"id": "<newusersgroupid>",
api review...
r1843 "msg": "created new users group <groupname>"
Nicolas VINOT
[API] Update doc
r1592 }
error: null
#227 Initial version of repository groups permissions system...
r1982
implements #329...
r1793 add_user_to_users_group
-----------------------
Nicolas VINOT
[API] Update doc
r1592
API changes...
r1989 Adds a user to a users group. If user exists in that group success will be
`false`. This command can be executed only using api_key
Nicolas VINOT
[API] Update doc
r1592 belonging to user with admin rights
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 INPUT::
api_key : "<api_key>"
method : "add_user_users_group"
args: {
"group_name" : "<groupname>",
implements #330 api method for listing nodes at particular revision...
r1810 "username" : "<username>"
Nicolas VINOT
[API] Update doc
r1592 }
OUTPUT::
result: {
"id": "<newusersgroupmemberid>",
API changes...
r1989 "success": True|False # depends on if member is in group
"msg": "added member <username> to users group <groupname> |
User is already in that group"
}
error: null
remove_user_from_users_group
----------------------------
Removes a user from a users 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
INPUT::
api_key : "<api_key>"
method : "remove_user_from_users_group"
args: {
"group_name" : "<groupname>",
"username" : "<username>"
}
OUTPUT::
result: {
"success": True|False, # depends on if member is in group
"msg": "removed member <username> from users group <groupname> |
User wasn't in group"
Nicolas VINOT
[API] Update doc
r1592 }
error: null
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 get_repo
--------
Gets an existing repository. This command can be executed only using api_key
belonging to user with admin rights
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 INPUT::
api_key : "<api_key>"
method : "get_repo"
args: {
"repo_name" : "<reponame>"
}
OUTPUT::
result: None if repository does not exist or
{
"id" : "<id>",
"repo_name" : "<reponame>"
"type" : "<type>",
"description" : "<description>",
"members" : [
{ "id" : "<userid>",
"username" : "<username>",
"firstname": "<firstname>",
"lastname" : "<lastname>",
"email" : "<email>",
"active" : "<bool>",
"admin" :  "<bool>",
"ldap" : "<ldap_dn>",
"permission" : "repository.(read|write|admin)"
},
…
{
"id" : "<usersgroupid>",
"name" : "<usersgroupname>",
"active": "<bool>",
"permission" : "repository.(read|write|admin)"
},
…
]
}
error: null
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 get_repos
---------
Lists all existing repositories. This command can be executed only using api_key
belonging to user with admin rights
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 INPUT::
api_key : "<api_key>"
method : "get_repos"
args: { }
Extended API...
r1500
OUTPUT::
Nicolas VINOT
[API] Update doc
r1592 result: [
{
"id" : "<id>",
api review...
r1843 "repo_name" : "<reponame>"
Nicolas VINOT
[API] Update doc
r1592 "type" : "<type>",
"description" : "<description>"
},
…
]
error: null
implements #330 api method for listing nodes at particular revision...
r1810 get_repo_nodes
--------------
returns a list of nodes and it's children in a flat list for a given path
api review...
r1843 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
implements #330 api method for listing nodes at particular revision...
r1810 with admin rights
#227 Initial version of repository groups permissions system...
r1982
implements #330 api method for listing nodes at particular revision...
r1810 INPUT::
api_key : "<api_key>"
method : "get_repo_nodes"
args: {
api review...
r1843 "repo_name" : "<reponame>",
implements #330 api method for listing nodes at particular revision...
r1810 "revision" : "<revision>",
"root_path" : "<root_path>",
"ret_type" : "<ret_type>" = 'all'
}
OUTPUT::
result: [
{
"name" : "<name>"
"type" : "<type>",
},
…
]
error: null
Nicolas VINOT
[API] Update doc
r1592 create_repo
-----------
Creates a repository. This command can be executed only using api_key
belonging to user with admin rights.
If repository name contains "/", all needed repository groups will be created.
For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent),
and create "baz" repository with "bar" as group.
#227 Initial version of repository groups permissions system...
r1982
Nicolas VINOT
[API] Update doc
r1592 INPUT::
api_key : "<api_key>"
method : "create_repo"
args: {
api review...
r1843 "repo_name" : "<reponame>",
Nicolas VINOT
[API] Update doc
r1592 "owner_name" : "<ownername>",
"description" : "<description> = ''",
"repo_type" : "<type> = 'hg'",
"private" : "<bool> = False"
}
OUTPUT::
api review...
r1843 result: {
#227 Initial version of repository groups permissions system...
r1982 "id": "<newrepoid>",
"msg": "Created new repository <reponame>",
api review...
r1843 }
Nicolas VINOT
[API] Update doc
r1592 error: null
#227 Initial version of repository groups permissions system...
r1982
grant_user_permission
---------------------
Nicolas VINOT
[API] Update doc
r1592
#227 Initial version of repository groups permissions system...
r1982 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.
Nicolas VINOT
[API] Update doc
r1592
INPUT::
api_key : "<api_key>"
#227 Initial version of repository groups permissions system...
r1982 method : "grant_user_permission"
Nicolas VINOT
[API] Update doc
r1592 args: {
"repo_name" : "<reponame>",
api review...
r1843 "username" : "<username>",
#227 Initial version of repository groups permissions system...
r1982 "perm" : "(repository.(none|read|write|admin))",
}
OUTPUT::
result: {
"msg" : "Granted perm: <perm> for user: <username> in repo: <reponame>"
}
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.
INPUT::
api_key : "<api_key>"
method : "revoke_user_permission"
args: {
"repo_name" : "<reponame>",
"username" : "<username>",
Nicolas VINOT
[API] Update doc
r1592 }
OUTPUT::
api review...
r1843 result: {
#227 Initial version of repository groups permissions system...
r1982 "msg" : "Revoked perm for user: <suername> in repo: <reponame>"
api review...
r1843 }
Nicolas VINOT
[API] Update doc
r1592 error: null
implements #329...
r1793
#227 Initial version of repository groups permissions system...
r1982
grant_users_group_permission
----------------------------
implements #329...
r1793
#227 Initial version of repository groups permissions system...
r1982 Grant permission for users 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.
implements #329...
r1793
INPUT::
api_key : "<api_key>"
#227 Initial version of repository groups permissions system...
r1982 method : "grant_users_group_permission"
args: {
"repo_name" : "<reponame>",
"group_name" : "<usersgroupname>",
"perm" : "(repository.(none|read|write|admin))",
}
OUTPUT::
result: {
"msg" : "Granted perm: <perm> for group: <usersgroupname> in repo: <reponame>"
}
error: null
revoke_users_group_permission
-----------------------------
Revoke permission for users group on given repository.This command can be
executed only using api_key belonging to user with admin rights.
INPUT::
api_key : "<api_key>"
method : "revoke_users_group_permission"
implements #329...
r1793 args: {
"repo_name" : "<reponame>",
#227 Initial version of repository groups permissions system...
r1982 "users_group" : "<usersgroupname>",
api review...
r1843 }
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 OUTPUT::
#227 Initial version of repository groups permissions system...
r1982
api review...
r1843 result: {
#227 Initial version of repository groups permissions system...
r1982 "msg" : "Revoked perm for group: <usersgroupname> in repo: <reponame>"
api review...
r1843 }
#227 Initial version of repository groups permissions system...
r1982 error: null