##// END OF EJS Templates
docs: update API documentation
marcink -
r3495:32c1e2aa default
parent child Browse files
Show More
@@ -0,0 +1,37 b''
1 .. _store-methods-ref:
2
3 store methods
4 =============
5
6 file_store_add (EE only)
7 ------------------------
8
9 .. py:function:: file_store_add(apiuser, filename, content)
10
11 Upload API for the file_store
12
13 Example usage from CLI::
14 rhodecode-api --instance-name=enterprise-1 upload_file "{"content": "$(cat image.jpg | base64)", "filename":"image.jpg"}"
15
16 This command takes the following options:
17
18 :param apiuser: This is filled automatically from the |authtoken|.
19 :type apiuser: AuthUser
20 :param filename: name of the file uploaded
21 :type filename: str
22 :param content: base64 encoded content of the uploaded file
23 :type content: str
24
25 Example output:
26
27 .. code-block:: bash
28
29 id : <id_given_in_input>
30 result: {
31 "access_path": "/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg",
32 "access_path_fqn": "http://server.domain.com/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg",
33 "store_fid": "84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg"
34 }
35 error : null
36
37
@@ -1,208 +1,209 b''
1 1 .. _api:
2 2
3 3 API Documentation
4 4 =================
5 5
6 6 The |RCE| API uses a single scheme for calling all API methods. The API is
7 7 implemented with JSON protocol in both directions. To send API requests to
8 8 your instance of |RCE|, use the following URL format
9 9 ``<your_server>/_admin``
10 10
11 11 .. note::
12 12
13 13 To use the API, you should configure the :file:`~/.rhoderc` file with
14 14 access details per instance. For more information, see
15 15 :ref:`config-rhoderc`.
16 16
17 17
18 18 API ACCESS FOR WEB VIEWS
19 19 ------------------------
20 20
21 21 API access can also be turned on for each web view in |RCE| that is
22 22 decorated with a `@LoginRequired` decorator. To enable API access, change
23 23 the standard login decorator to `@LoginRequired(api_access=True)`.
24 24
25 25 From |RCE| version 1.7.0 you can configure a white list
26 26 of views that have API access enabled by default. To enable these,
27 27 edit the |RCE| configuration ``.ini`` file. The default location is:
28 28
29 29 * |RCE| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
30 30 * |RCE| 3.0 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
31 31
32 32 To configure the white list, edit this section of the file. In this
33 33 configuration example, API access is granted to the patch/diff raw file and
34 34 archive.
35 35
36 36 .. code-block:: ini
37 37
38 38 ## List of controllers (using glob syntax) that AUTH TOKENS could be used for access.
39 39 ## Adding ?auth_token = <token> to the url authenticates this request as if it
40 40 ## came from the the logged in user who own this authentication token.
41 41 ##
42 42 ## Syntax is <ControllerClass>:<function_pattern>.
43 43 ## The list should be "," separated and on a single line.
44 44 ##
45 45 api_access_controllers_whitelist = RepoCommitsView:repo_commit_raw,RepoCommitsView:repo_commit_patch,RepoCommitsView:repo_commit_download
46 46
47 47 After this change, a |RCE| view can be accessed without login by adding a
48 48 GET parameter ``?auth_token=<auth_token>`` to a url. For example to
49 49 access the raw diff.
50 50
51 51 .. code-block:: html
52 52
53 53 http://<server>/<repo>/changeset-diff/<sha>?auth_token=<auth_token>
54 54
55 55 By default this is only enabled on RSS/ATOM feed views. Exposing raw diffs is a
56 56 good way to integrate with 3rd party services like code review, or build farms
57 57 that could download archives.
58 58
59 59 API ACCESS
60 60 ----------
61 61
62 62 All clients are required to send JSON-RPC spec JSON data.
63 63
64 64 .. code-block:: bash
65 65
66 66 {
67 67 "id:"<id>",
68 68 "auth_token":"<auth_token>",
69 69 "method":"<method_name>",
70 70 "args":{"<arg_key>":"<arg_val>"}
71 71 }
72 72
73 73 Example call for auto pulling from remote repositories using curl:
74 74
75 75 .. code-block:: bash
76 76
77 77 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,
78 78 "auth_token":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull", "args":{"repoid":"CPython"}}'
79 79
80 80 Provide those parameters:
81 81 - **id** A value of any type, which is used to match the response with the
82 82 request that it is replying to.
83 83 - **auth_token** for access and permission validation.
84 84 - **method** is name of method to call
85 85 - **args** is an ``key:value`` list of arguments to pass to method
86 86
87 87 .. note::
88 88
89 89 To get your |authtoken|, from the |RCE| interface,
90 90 go to:
91 91 :menuselection:`username --> My account --> Auth tokens`
92 92
93 93 For security reasons you should always create a dedicated |authtoken| for
94 94 API use only.
95 95
96 96
97 97 The |RCE| API will always return a JSON-RPC response:
98 98
99 99 .. code-block:: bash
100 100
101 101 {
102 102 "id": <id>, # matching id sent by request
103 103 "result": "<result>"|null, # JSON formatted result, null if any errors
104 104 "error": "null"|<error_message> # JSON formatted error (if any)
105 105 }
106 106
107 107 All responses from API will be with `HTTP/1.0 200 OK` status code.
108 108 If there is an error when calling the API, the *error* key will contain a
109 109 failure description and the *result* will be `null`.
110 110
111 111 API CLIENT
112 112 ----------
113 113
114 114 To install the |RCE| API, see :ref:`install-tools`. To configure the API per
115 115 instance, see the :ref:`rc-tools` section as you need to configure a
116 116 :file:`~/.rhoderc` file with your |authtokens|.
117 117
118 118 Once you have set up your instance API access, use the following examples to
119 119 get started.
120 120
121 121 .. code-block:: bash
122 122
123 123 # Getting the 'rhodecode' repository
124 124 # from a RhodeCode Enterprise instance
125 125 rhodecode-api --instance-name=enterprise-1 get_repo repoid:rhodecode
126 126
127 127 Calling method get_repo => http://127.0.0.1:5000
128 128 Server response
129 129 {
130 130 <json data>
131 131 }
132 132
133 133 # Creating a new mercurial repository called 'brand-new'
134 134 # with a description 'Repo-description'
135 135 rhodecode-api --instance-name=enterprise-1 create_repo repo_name:brand-new repo_type:hg description:Repo-description
136 136 {
137 137 "error": null,
138 138 "id": 1110,
139 139 "result": {
140 140 "msg": "Created new repository `brand-new`",
141 141 "success": true,
142 142 "task": null
143 143 }
144 144 }
145 145
146 146 A broken example, what not to do.
147 147
148 148 .. code-block:: bash
149 149
150 150 # A call missing the required arguments
151 151 # and not specifying the instance
152 152 rhodecode-api get_repo
153 153
154 154 Calling method get_repo => http://127.0.0.1:5000
155 155 Server response
156 156 "Missing non optional `repoid` arg in JSON DATA"
157 157
158 158 You can specify pure JSON using the ``--format`` parameter.
159 159
160 160 .. code-block:: bash
161 161
162 162 rhodecode-api --format=json get_repo repoid:rhodecode
163 163
164 164 In such case only output that this function shows is pure JSON, we can use that
165 165 and pipe output to some json formatter.
166 166
167 167 If output is in pure JSON format, you can pipe output to a JSON formatter.
168 168
169 169 .. code-block:: bash
170 170
171 171 rhodecode-api --instance-name=enterprise-1 --format=json get_repo repoid:rhodecode | python -m json.tool
172 172
173 173 API METHODS
174 174 -----------
175 175
176 176 Each method by default required following arguments.
177 177
178 178 .. code-block:: bash
179 179
180 180 id : "<id_for_response>"
181 181 auth_token : "<auth_token>"
182 182 method : "<method name>"
183 183 args : {}
184 184
185 185 Use each **param** from docs and put it in args, Optional parameters
186 186 are not required in args.
187 187
188 188 .. code-block:: bash
189 189
190 190 args: {"repoid": "rhodecode"}
191 191
192 192 .. Note: From this point on things are generated by the script in
193 193 `scripts/fabfile.py`. To change things below, update the docstrings in the
194 194 ApiController.
195 195
196 196 .. --- API DEFS MARKER ---
197 197 .. toctree::
198 198
199 methods/views
199 methods/repo-methods
200 methods/store-methods
200 201 methods/license-methods
201 202 methods/deprecated-methods
202 203 methods/gist-methods
203 204 methods/pull-request-methods
204 205 methods/repo-methods
205 206 methods/repo-group-methods
206 207 methods/server-methods
207 208 methods/user-methods
208 209 methods/user-group-methods
@@ -1,428 +1,434 b''
1 1 .. _pull-request-methods-ref:
2 2
3 3 pull_request methods
4 4 ====================
5 5
6 6 close_pull_request
7 7 ------------------
8 8
9 9 .. py:function:: close_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>, message=<Optional:''>)
10 10
11 11 Close the pull request specified by `pullrequestid`.
12 12
13 13 :param apiuser: This is filled automatically from the |authtoken|.
14 14 :type apiuser: AuthUser
15 15 :param repoid: Repository name or repository ID to which the pull
16 16 request belongs.
17 17 :type repoid: str or int
18 18 :param pullrequestid: ID of the pull request to be closed.
19 19 :type pullrequestid: int
20 20 :param userid: Close the pull request as this user.
21 21 :type userid: Optional(str or int)
22 22 :param message: Optional message to close the Pull Request with. If not
23 23 specified it will be generated automatically.
24 24 :type message: Optional(str)
25 25
26 26 Example output:
27 27
28 28 .. code-block:: bash
29 29
30 30 "id": <id_given_in_input>,
31 31 "result": {
32 32 "pull_request_id": "<int>",
33 33 "close_status": "<str:status_lbl>,
34 34 "closed": "<bool>"
35 35 },
36 36 "error": null
37 37
38 38
39 39 comment_pull_request
40 40 --------------------
41 41
42 42 .. py:function:: comment_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, message=<Optional:None>, commit_id=<Optional:None>, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
43 43
44 44 Comment on the pull request specified with the `pullrequestid`,
45 45 in the |repo| specified by the `repoid`, and optionally change the
46 46 review status.
47 47
48 48 :param apiuser: This is filled automatically from the |authtoken|.
49 49 :type apiuser: AuthUser
50 50 :param repoid: Optional repository name or repository ID.
51 51 :type repoid: str or int
52 52 :param pullrequestid: The pull request ID.
53 53 :type pullrequestid: int
54 54 :param commit_id: Specify the commit_id for which to set a comment. If
55 55 given commit_id is different than latest in the PR status
56 56 change won't be performed.
57 57 :type commit_id: str
58 58 :param message: The text content of the comment.
59 59 :type message: str
60 60 :param status: (**Optional**) Set the approval status of the pull
61 61 request. One of: 'not_reviewed', 'approved', 'rejected',
62 62 'under_review'
63 63 :type status: str
64 64 :param comment_type: Comment type, one of: 'note', 'todo'
65 65 :type comment_type: Optional(str), default: 'note'
66 66 :param userid: Comment on the pull request as this user
67 67 :type userid: Optional(str or int)
68 68
69 69 Example output:
70 70
71 71 .. code-block:: bash
72 72
73 73 id : <id_given_in_input>
74 74 result : {
75 75 "pull_request_id": "<Integer>",
76 76 "comment_id": "<Integer>",
77 77 "status": {"given": <given_status>,
78 78 "was_changed": <bool status_was_actually_changed> },
79 79 },
80 80 error : null
81 81
82 82
83 83 create_pull_request
84 84 -------------------
85 85
86 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
86 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, owner=<Optional:<OptionalAttr:apiuser>>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
87 87
88 88 Creates a new pull request.
89 89
90 90 Accepts refs in the following formats:
91 91
92 92 * branch:<branch_name>:<sha>
93 93 * branch:<branch_name>
94 94 * bookmark:<bookmark_name>:<sha> (Mercurial only)
95 95 * bookmark:<bookmark_name> (Mercurial only)
96 96
97 97 :param apiuser: This is filled automatically from the |authtoken|.
98 98 :type apiuser: AuthUser
99 99 :param source_repo: Set the source repository name.
100 100 :type source_repo: str
101 101 :param target_repo: Set the target repository name.
102 102 :type target_repo: str
103 103 :param source_ref: Set the source ref name.
104 104 :type source_ref: str
105 105 :param target_ref: Set the target ref name.
106 106 :type target_ref: str
107 :param owner: user_id or username
108 :type owner: Optional(str)
107 109 :param title: Optionally Set the pull request title, it's generated otherwise
108 110 :type title: str
109 111 :param description: Set the pull request description.
110 112 :type description: Optional(str)
111 113 :type description_renderer: Optional(str)
112 114 :param description_renderer: Set pull request renderer for the description.
113 115 It should be 'rst', 'markdown' or 'plain'. If not give default
114 116 system renderer will be used
115 117 :param reviewers: Set the new pull request reviewers list.
116 118 Reviewer defined by review rules will be added automatically to the
117 119 defined list.
118 120 :type reviewers: Optional(list)
119 121 Accepts username strings or objects of the format:
120 122
121 123 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
122 124
123 125
124 126 get_pull_request
125 127 ----------------
126 128
127 129 .. py:function:: get_pull_request(apiuser, pullrequestid, repoid=<Optional:None>)
128 130
129 131 Get a pull request based on the given ID.
130 132
131 133 :param apiuser: This is filled automatically from the |authtoken|.
132 134 :type apiuser: AuthUser
133 135 :param repoid: Optional, repository name or repository ID from where
134 136 the pull request was opened.
135 137 :type repoid: str or int
136 138 :param pullrequestid: ID of the requested pull request.
137 139 :type pullrequestid: int
138 140
139 141 Example output:
140 142
141 143 .. code-block:: bash
142 144
143 145 "id": <id_given_in_input>,
144 146 "result":
145 147 {
146 148 "pull_request_id": "<pull_request_id>",
147 149 "url": "<url>",
148 150 "title": "<title>",
149 151 "description": "<description>",
150 152 "status" : "<status>",
151 153 "created_on": "<date_time_created>",
152 154 "updated_on": "<date_time_updated>",
153 155 "commit_ids": [
154 156 ...
155 157 "<commit_id>",
156 158 "<commit_id>",
157 159 ...
158 160 ],
159 161 "review_status": "<review_status>",
160 162 "mergeable": {
161 163 "status": "<bool>",
162 164 "message": "<message>",
163 165 },
164 166 "source": {
165 167 "clone_url": "<clone_url>",
166 168 "repository": "<repository_name>",
167 169 "reference":
168 170 {
169 171 "name": "<name>",
170 172 "type": "<type>",
171 173 "commit_id": "<commit_id>",
172 174 }
173 175 },
174 176 "target": {
175 177 "clone_url": "<clone_url>",
176 178 "repository": "<repository_name>",
177 179 "reference":
178 180 {
179 181 "name": "<name>",
180 182 "type": "<type>",
181 183 "commit_id": "<commit_id>",
182 184 }
183 185 },
184 186 "merge": {
185 187 "clone_url": "<clone_url>",
186 188 "reference":
187 189 {
188 190 "name": "<name>",
189 191 "type": "<type>",
190 192 "commit_id": "<commit_id>",
191 193 }
192 194 },
193 195 "author": <user_obj>,
194 196 "reviewers": [
195 197 ...
196 198 {
197 199 "user": "<user_obj>",
198 200 "review_status": "<review_status>",
199 201 }
200 202 ...
201 203 ]
202 204 },
203 205 "error": null
204 206
205 207
206 208 get_pull_request_comments
207 209 -------------------------
208 210
209 211 .. py:function:: get_pull_request_comments(apiuser, pullrequestid, repoid=<Optional:None>)
210 212
211 213 Get all comments of pull request specified with the `pullrequestid`
212 214
213 215 :param apiuser: This is filled automatically from the |authtoken|.
214 216 :type apiuser: AuthUser
215 217 :param repoid: Optional repository name or repository ID.
216 218 :type repoid: str or int
217 219 :param pullrequestid: The pull request ID.
218 220 :type pullrequestid: int
219 221
220 222 Example output:
221 223
222 224 .. code-block:: bash
223 225
224 226 id : <id_given_in_input>
225 227 result : [
226 228 {
227 229 "comment_author": {
228 230 "active": true,
229 231 "full_name_or_username": "Tom Gore",
230 232 "username": "admin"
231 233 },
232 234 "comment_created_on": "2017-01-02T18:43:45.533",
233 235 "comment_f_path": null,
234 236 "comment_id": 25,
235 237 "comment_lineno": null,
236 238 "comment_status": {
237 239 "status": "under_review",
238 240 "status_lbl": "Under Review"
239 241 },
240 242 "comment_text": "Example text",
241 243 "comment_type": null,
242 244 "pull_request_version": null
243 245 }
244 246 ],
245 247 error : null
246 248
247 249
248 250 get_pull_requests
249 251 -----------------
250 252
251 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>)
253 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>, merge_state=<Optional:True>)
252 254
253 255 Get all pull requests from the repository specified in `repoid`.
254 256
255 257 :param apiuser: This is filled automatically from the |authtoken|.
256 258 :type apiuser: AuthUser
257 259 :param repoid: Optional repository name or repository ID.
258 260 :type repoid: str or int
259 261 :param status: Only return pull requests with the specified status.
260 262 Valid options are.
261 263 * ``new`` (default)
262 264 * ``open``
263 265 * ``closed``
264 266 :type status: str
267 :param merge_state: Optional calculate merge state for each repository.
268 This could result in longer time to fetch the data
269 :type merge_state: bool
265 270
266 271 Example output:
267 272
268 273 .. code-block:: bash
269 274
270 275 "id": <id_given_in_input>,
271 276 "result":
272 277 [
273 278 ...
274 279 {
275 280 "pull_request_id": "<pull_request_id>",
276 281 "url": "<url>",
277 282 "title" : "<title>",
278 283 "description": "<description>",
279 284 "status": "<status>",
280 285 "created_on": "<date_time_created>",
281 286 "updated_on": "<date_time_updated>",
282 287 "commit_ids": [
283 288 ...
284 289 "<commit_id>",
285 290 "<commit_id>",
286 291 ...
287 292 ],
288 293 "review_status": "<review_status>",
289 294 "mergeable": {
290 295 "status": "<bool>",
291 296 "message: "<message>",
292 297 },
293 298 "source": {
294 299 "clone_url": "<clone_url>",
295 300 "reference":
296 301 {
297 302 "name": "<name>",
298 303 "type": "<type>",
299 304 "commit_id": "<commit_id>",
300 305 }
301 306 },
302 307 "target": {
303 308 "clone_url": "<clone_url>",
304 309 "reference":
305 310 {
306 311 "name": "<name>",
307 312 "type": "<type>",
308 313 "commit_id": "<commit_id>",
309 314 }
310 315 },
311 316 "merge": {
312 317 "clone_url": "<clone_url>",
313 318 "reference":
314 319 {
315 320 "name": "<name>",
316 321 "type": "<type>",
317 322 "commit_id": "<commit_id>",
318 323 }
319 324 },
320 325 "author": <user_obj>,
321 326 "reviewers": [
322 327 ...
323 328 {
324 329 "user": "<user_obj>",
325 330 "review_status": "<review_status>",
326 331 }
327 332 ...
328 333 ]
329 334 }
330 335 ...
331 336 ],
332 337 "error": null
333 338
334 339
335 340 merge_pull_request
336 341 ------------------
337 342
338 343 .. py:function:: merge_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
339 344
340 345 Merge the pull request specified by `pullrequestid` into its target
341 346 repository.
342 347
343 348 :param apiuser: This is filled automatically from the |authtoken|.
344 349 :type apiuser: AuthUser
345 350 :param repoid: Optional, repository name or repository ID of the
346 351 target repository to which the |pr| is to be merged.
347 352 :type repoid: str or int
348 353 :param pullrequestid: ID of the pull request which shall be merged.
349 354 :type pullrequestid: int
350 355 :param userid: Merge the pull request as this user.
351 356 :type userid: Optional(str or int)
352 357
353 358 Example output:
354 359
355 360 .. code-block:: bash
356 361
357 362 "id": <id_given_in_input>,
358 363 "result": {
359 364 "executed": "<bool>",
360 365 "failure_reason": "<int>",
366 "merge_status_message": "<str>",
361 367 "merge_commit_id": "<merge_commit_id>",
362 368 "possible": "<bool>",
363 369 "merge_ref": {
364 370 "commit_id": "<commit_id>",
365 371 "type": "<type>",
366 372 "name": "<name>"
367 373 }
368 374 },
369 375 "error": null
370 376
371 377
372 378 update_pull_request
373 379 -------------------
374 380
375 381 .. py:function:: update_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>)
376 382
377 383 Updates a pull request.
378 384
379 385 :param apiuser: This is filled automatically from the |authtoken|.
380 386 :type apiuser: AuthUser
381 387 :param repoid: Optional repository name or repository ID.
382 388 :type repoid: str or int
383 389 :param pullrequestid: The pull request ID.
384 390 :type pullrequestid: int
385 391 :param title: Set the pull request title.
386 392 :type title: str
387 393 :param description: Update pull request description.
388 394 :type description: Optional(str)
389 395 :type description_renderer: Optional(str)
390 396 :param description_renderer: Update pull request renderer for the description.
391 397 It should be 'rst', 'markdown' or 'plain'
392 398 :param reviewers: Update pull request reviewers list with new value.
393 399 :type reviewers: Optional(list)
394 400 Accepts username strings or objects of the format:
395 401
396 402 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
397 403
398 404 :param update_commits: Trigger update of commits for this pull request
399 405 :type: update_commits: Optional(bool)
400 406
401 407 Example output:
402 408
403 409 .. code-block:: bash
404 410
405 411 id : <id_given_in_input>
406 412 result : {
407 413 "msg": "Updated pull request `63`",
408 414 "pull_request": <pull_request_object>,
409 415 "updated_reviewers": {
410 416 "added": [
411 417 "username"
412 418 ],
413 419 "removed": []
414 420 },
415 421 "updated_commits": {
416 422 "added": [
417 423 "<sha1_hash>"
418 424 ],
419 425 "common": [
420 426 "<sha1_hash>",
421 427 "<sha1_hash>",
422 428 ],
423 429 "removed": []
424 430 }
425 431 }
426 432 error : null
427 433
428 434
@@ -1,1028 +1,1134 b''
1 1 .. _repo-methods-ref:
2 2
3 3 repo methods
4 4 ============
5 5
6 6 add_field_to_repo
7 7 -----------------
8 8
9 9 .. py:function:: add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)
10 10
11 11 Adds an extra field to a repository.
12 12
13 13 This command can only be run using an |authtoken| with at least
14 14 write permissions to the |repo|.
15 15
16 16 :param apiuser: This is filled automatically from the |authtoken|.
17 17 :type apiuser: AuthUser
18 18 :param repoid: Set the repository name or repository id.
19 19 :type repoid: str or int
20 20 :param key: Create a unique field key for this repository.
21 21 :type key: str
22 22 :param label:
23 23 :type label: Optional(str)
24 24 :param description:
25 25 :type description: Optional(str)
26 26
27 27
28 28 comment_commit
29 29 --------------
30 30
31 31 .. py:function:: comment_commit(apiuser, repoid, commit_id, message, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
32 32
33 33 Set a commit comment, and optionally change the status of the commit.
34 34
35 35 :param apiuser: This is filled automatically from the |authtoken|.
36 36 :type apiuser: AuthUser
37 37 :param repoid: Set the repository name or repository ID.
38 38 :type repoid: str or int
39 39 :param commit_id: Specify the commit_id for which to set a comment.
40 40 :type commit_id: str
41 41 :param message: The comment text.
42 42 :type message: str
43 43 :param status: (**Optional**) status of commit, one of: 'not_reviewed',
44 44 'approved', 'rejected', 'under_review'
45 45 :type status: str
46 46 :param comment_type: Comment type, one of: 'note', 'todo'
47 47 :type comment_type: Optional(str), default: 'note'
48 48 :param userid: Set the user name of the comment creator.
49 49 :type userid: Optional(str or int)
50 50
51 51 Example error output:
52 52
53 53 .. code-block:: bash
54 54
55 55 {
56 56 "id" : <id_given_in_input>,
57 57 "result" : {
58 58 "msg": "Commented on commit `<commit_id>` for repository `<repoid>`",
59 59 "status_change": null or <status>,
60 60 "success": true
61 61 },
62 62 "error" : null
63 63 }
64 64
65 65
66 66 create_repo
67 67 -----------
68 68
69 69 .. py:function:: create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, push_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)
70 70
71 71 Creates a repository.
72 72
73 73 * If the repository name contains "/", repository will be created inside
74 74 a repository group or nested repository groups
75 75
76 76 For example "foo/bar/repo1" will create |repo| called "repo1" inside
77 77 group "foo/bar". You have to have permissions to access and write to
78 78 the last repository group ("bar" in this example)
79 79
80 80 This command can only be run using an |authtoken| with at least
81 81 permissions to create repositories, or write permissions to
82 82 parent repository groups.
83 83
84 84 :param apiuser: This is filled automatically from the |authtoken|.
85 85 :type apiuser: AuthUser
86 86 :param repo_name: Set the repository name.
87 87 :type repo_name: str
88 88 :param repo_type: Set the repository type; 'hg','git', or 'svn'.
89 89 :type repo_type: str
90 90 :param owner: user_id or username
91 91 :type owner: Optional(str)
92 92 :param description: Set the repository description.
93 93 :type description: Optional(str)
94 94 :param private: set repository as private
95 95 :type private: bool
96 96 :param clone_uri: set clone_uri
97 97 :type clone_uri: str
98 98 :param push_uri: set push_uri
99 99 :type push_uri: str
100 100 :param landing_rev: <rev_type>:<rev>
101 101 :type landing_rev: str
102 102 :param enable_locking:
103 103 :type enable_locking: bool
104 104 :param enable_downloads:
105 105 :type enable_downloads: bool
106 106 :param enable_statistics:
107 107 :type enable_statistics: bool
108 108 :param copy_permissions: Copy permission from group in which the
109 109 repository is being created.
110 110 :type copy_permissions: bool
111 111
112 112
113 113 Example output:
114 114
115 115 .. code-block:: bash
116 116
117 117 id : <id_given_in_input>
118 118 result: {
119 119 "msg": "Created new repository `<reponame>`",
120 120 "success": true,
121 121 "task": "<celery task id or None if done sync>"
122 122 }
123 123 error: null
124 124
125 125
126 126 Example error output:
127 127
128 128 .. code-block:: bash
129 129
130 130 id : <id_given_in_input>
131 131 result : null
132 132 error : {
133 133 'failed to create repository `<repo_name>`'
134 134 }
135 135
136 136
137 137 delete_repo
138 138 -----------
139 139
140 140 .. py:function:: delete_repo(apiuser, repoid, forks=<Optional:''>)
141 141
142 142 Deletes a repository.
143 143
144 144 * When the `forks` parameter is set it's possible to detach or delete
145 145 forks of deleted repository.
146 146
147 147 This command can only be run using an |authtoken| with admin
148 148 permissions on the |repo|.
149 149
150 150 :param apiuser: This is filled automatically from the |authtoken|.
151 151 :type apiuser: AuthUser
152 152 :param repoid: Set the repository name or repository ID.
153 153 :type repoid: str or int
154 154 :param forks: Set to `detach` or `delete` forks from the |repo|.
155 155 :type forks: Optional(str)
156 156
157 157 Example error output:
158 158
159 159 .. code-block:: bash
160 160
161 161 id : <id_given_in_input>
162 162 result: {
163 163 "msg": "Deleted repository `<reponame>`",
164 164 "success": true
165 165 }
166 166 error: null
167 167
168 168
169 169 fork_repo
170 170 ---------
171 171
172 172 .. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, copy_permissions=<Optional:False>)
173 173
174 174 Creates a fork of the specified |repo|.
175 175
176 176 * If the fork_name contains "/", fork will be created inside
177 177 a repository group or nested repository groups
178 178
179 179 For example "foo/bar/fork-repo" will create fork called "fork-repo"
180 180 inside group "foo/bar". You have to have permissions to access and
181 181 write to the last repository group ("bar" in this example)
182 182
183 183 This command can only be run using an |authtoken| with minimum
184 184 read permissions of the forked repo, create fork permissions for an user.
185 185
186 186 :param apiuser: This is filled automatically from the |authtoken|.
187 187 :type apiuser: AuthUser
188 188 :param repoid: Set repository name or repository ID.
189 189 :type repoid: str or int
190 190 :param fork_name: Set the fork name, including it's repository group membership.
191 191 :type fork_name: str
192 192 :param owner: Set the fork owner.
193 193 :type owner: str
194 194 :param description: Set the fork description.
195 195 :type description: str
196 196 :param copy_permissions: Copy permissions from parent |repo|. The
197 197 default is False.
198 198 :type copy_permissions: bool
199 199 :param private: Make the fork private. The default is False.
200 200 :type private: bool
201 201 :param landing_rev: Set the landing revision. The default is tip.
202 202
203 203 Example output:
204 204
205 205 .. code-block:: bash
206 206
207 207 id : <id_for_response>
208 208 api_key : "<api_key>"
209 209 args: {
210 210 "repoid" : "<reponame or repo_id>",
211 211 "fork_name": "<forkname>",
212 212 "owner": "<username or user_id = Optional(=apiuser)>",
213 213 "description": "<description>",
214 214 "copy_permissions": "<bool>",
215 215 "private": "<bool>",
216 216 "landing_rev": "<landing_rev>"
217 217 }
218 218
219 219 Example error output:
220 220
221 221 .. code-block:: bash
222 222
223 223 id : <id_given_in_input>
224 224 result: {
225 225 "msg": "Created fork of `<reponame>` as `<forkname>`",
226 226 "success": true,
227 227 "task": "<celery task id or None if done sync>"
228 228 }
229 229 error: null
230 230
231 231
232 232 get_repo
233 233 --------
234 234
235 235 .. py:function:: get_repo(apiuser, repoid, cache=<Optional:True>)
236 236
237 237 Gets an existing repository by its name or repository_id.
238 238
239 239 The members section so the output returns users groups or users
240 240 associated with that repository.
241 241
242 242 This command can only be run using an |authtoken| with admin rights,
243 243 or users with at least read rights to the |repo|.
244 244
245 245 :param apiuser: This is filled automatically from the |authtoken|.
246 246 :type apiuser: AuthUser
247 247 :param repoid: The repository name or repository id.
248 248 :type repoid: str or int
249 249 :param cache: use the cached value for last changeset
250 250 :type: cache: Optional(bool)
251 251
252 252 Example output:
253 253
254 254 .. code-block:: bash
255 255
256 256 {
257 257 "error": null,
258 258 "id": <repo_id>,
259 259 "result": {
260 260 "clone_uri": null,
261 261 "created_on": "timestamp",
262 262 "description": "repo description",
263 263 "enable_downloads": false,
264 264 "enable_locking": false,
265 265 "enable_statistics": false,
266 266 "followers": [
267 267 {
268 268 "active": true,
269 269 "admin": false,
270 270 "api_key": "****************************************",
271 271 "api_keys": [
272 272 "****************************************"
273 273 ],
274 274 "email": "user@example.com",
275 275 "emails": [
276 276 "user@example.com"
277 277 ],
278 278 "extern_name": "rhodecode",
279 279 "extern_type": "rhodecode",
280 280 "firstname": "username",
281 281 "ip_addresses": [],
282 282 "language": null,
283 283 "last_login": "2015-09-16T17:16:35.854",
284 284 "lastname": "surname",
285 285 "user_id": <user_id>,
286 286 "username": "name"
287 287 }
288 288 ],
289 289 "fork_of": "parent-repo",
290 290 "landing_rev": [
291 291 "rev",
292 292 "tip"
293 293 ],
294 294 "last_changeset": {
295 295 "author": "User <user@example.com>",
296 296 "branch": "default",
297 297 "date": "timestamp",
298 298 "message": "last commit message",
299 299 "parents": [
300 300 {
301 301 "raw_id": "commit-id"
302 302 }
303 303 ],
304 304 "raw_id": "commit-id",
305 305 "revision": <revision number>,
306 306 "short_id": "short id"
307 307 },
308 308 "lock_reason": null,
309 309 "locked_by": null,
310 310 "locked_date": null,
311 311 "owner": "owner-name",
312 312 "permissions": [
313 313 {
314 314 "name": "super-admin-name",
315 315 "origin": "super-admin",
316 316 "permission": "repository.admin",
317 317 "type": "user"
318 318 },
319 319 {
320 320 "name": "owner-name",
321 321 "origin": "owner",
322 322 "permission": "repository.admin",
323 323 "type": "user"
324 324 },
325 325 {
326 326 "name": "user-group-name",
327 327 "origin": "permission",
328 328 "permission": "repository.write",
329 329 "type": "user_group"
330 330 }
331 331 ],
332 332 "private": true,
333 333 "repo_id": 676,
334 334 "repo_name": "user-group/repo-name",
335 335 "repo_type": "hg"
336 336 }
337 337 }
338 338
339 339
340 340 get_repo_changeset
341 341 ------------------
342 342
343 343 .. py:function:: get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)
344 344
345 345 Returns information about a changeset.
346 346
347 347 Additionally parameters define the amount of details returned by
348 348 this function.
349 349
350 350 This command can only be run using an |authtoken| with admin rights,
351 351 or users with at least read rights to the |repo|.
352 352
353 353 :param apiuser: This is filled automatically from the |authtoken|.
354 354 :type apiuser: AuthUser
355 355 :param repoid: The repository name or repository id
356 356 :type repoid: str or int
357 357 :param revision: revision for which listing should be done
358 358 :type revision: str
359 359 :param details: details can be 'basic|extended|full' full gives diff
360 360 info details like the diff itself, and number of changed files etc.
361 361 :type details: Optional(str)
362 362
363 363
364 364 get_repo_changesets
365 365 -------------------
366 366
367 367 .. py:function:: get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)
368 368
369 369 Returns a set of commits limited by the number starting
370 370 from the `start_rev` option.
371 371
372 372 Additional parameters define the amount of details returned by this
373 373 function.
374 374
375 375 This command can only be run using an |authtoken| with admin rights,
376 376 or users with at least read rights to |repos|.
377 377
378 378 :param apiuser: This is filled automatically from the |authtoken|.
379 379 :type apiuser: AuthUser
380 380 :param repoid: The repository name or repository ID.
381 381 :type repoid: str or int
382 382 :param start_rev: The starting revision from where to get changesets.
383 383 :type start_rev: str
384 384 :param limit: Limit the number of commits to this amount
385 385 :type limit: str or int
386 386 :param details: Set the level of detail returned. Valid option are:
387 387 ``basic``, ``extended`` and ``full``.
388 388 :type details: Optional(str)
389 389
390 390 .. note::
391 391
392 392 Setting the parameter `details` to the value ``full`` is extensive
393 393 and returns details like the diff itself, and the number
394 394 of changed files.
395 395
396 396
397 get_repo_comments
398 -----------------
399
400 .. py:function:: get_repo_comments(apiuser, repoid, commit_id=<Optional:None>, comment_type=<Optional:None>, userid=<Optional:None>)
401
402 Get all comments for a repository
403
404 :param apiuser: This is filled automatically from the |authtoken|.
405 :type apiuser: AuthUser
406 :param repoid: Set the repository name or repository ID.
407 :type repoid: str or int
408 :param commit_id: Optionally filter the comments by the commit_id
409 :type commit_id: Optional(str), default: None
410 :param comment_type: Optionally filter the comments by the comment_type
411 one of: 'note', 'todo'
412 :type comment_type: Optional(str), default: None
413 :param userid: Optionally filter the comments by the author of comment
414 :type userid: Optional(str or int), Default: None
415
416 Example error output:
417
418 .. code-block:: bash
419
420 {
421 "id" : <id_given_in_input>,
422 "result" : [
423 {
424 "comment_author": <USER_DETAILS>,
425 "comment_created_on": "2017-02-01T14:38:16.309",
426 "comment_f_path": "file.txt",
427 "comment_id": 282,
428 "comment_lineno": "n1",
429 "comment_resolved_by": null,
430 "comment_status": [],
431 "comment_text": "This file needs a header",
432 "comment_type": "todo"
433 }
434 ],
435 "error" : null
436 }
437
438
439 get_repo_file
440 -------------
441
442 .. py:function:: get_repo_file(apiuser, repoid, commit_id, file_path, max_file_bytes=<Optional:None>, details=<Optional:'basic'>, cache=<Optional:True>)
443
444 Returns a single file from repository at given revision.
445
446 This command can only be run using an |authtoken| with admin rights,
447 or users with at least read rights to |repos|.
448
449 :param apiuser: This is filled automatically from the |authtoken|.
450 :type apiuser: AuthUser
451 :param repoid: The repository name or repository ID.
452 :type repoid: str or int
453 :param commit_id: The revision for which listing should be done.
454 :type commit_id: str
455 :param file_path: The path from which to start displaying.
456 :type file_path: str
457 :param details: Returns different set of information about nodes.
458 The valid options are ``minimal`` ``basic`` and ``full``.
459 :type details: Optional(str)
460 :param max_file_bytes: Only return file content under this file size bytes
461 :type max_file_bytes: Optional(int)
462 :param cache: Use internal caches for fetching files. If disabled fetching
463 files is slower but more memory efficient
464 :type cache: Optional(bool)
465 Example output:
466
467 .. code-block:: bash
468
469 id : <id_given_in_input>
470 result: {
471 "binary": false,
472 "extension": "py",
473 "lines": 35,
474 "content": "....",
475 "md5": "76318336366b0f17ee249e11b0c99c41",
476 "mimetype": "text/x-python",
477 "name": "python.py",
478 "size": 817,
479 "type": "file",
480 }
481 error: null
482
483
484 get_repo_fts_tree
485 -----------------
486
487 .. py:function:: get_repo_fts_tree(apiuser, repoid, commit_id, root_path)
488
489 Returns a list of tree nodes for path at given revision. This api is built
490 strictly for usage in full text search building, and shouldn't be consumed
491
492 This command can only be run using an |authtoken| with admin rights,
493 or users with at least read rights to |repos|.
494
495
397 496 get_repo_nodes
398 497 --------------
399 498
400 499 .. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)
401 500
402 501 Returns a list of nodes and children in a flat list for a given
403 502 path at given revision.
404 503
405 504 It's possible to specify ret_type to show only `files` or `dirs`.
406 505
407 506 This command can only be run using an |authtoken| with admin rights,
408 507 or users with at least read rights to |repos|.
409 508
410 509 :param apiuser: This is filled automatically from the |authtoken|.
411 510 :type apiuser: AuthUser
412 511 :param repoid: The repository name or repository ID.
413 512 :type repoid: str or int
414 513 :param revision: The revision for which listing should be done.
415 514 :type revision: str
416 515 :param root_path: The path from which to start displaying.
417 516 :type root_path: str
418 517 :param ret_type: Set the return type. Valid options are
419 518 ``all`` (default), ``files`` and ``dirs``.
420 519 :type ret_type: Optional(str)
421 520 :param details: Returns extended information about nodes, such as
422 md5, binary, and or content. The valid options are ``basic`` and
423 ``full``.
521 md5, binary, and or content.
522 The valid options are ``basic`` and ``full``.
424 523 :type details: Optional(str)
425 524 :param max_file_bytes: Only return file content under this file size bytes
426 525 :type details: Optional(int)
427 526
428 527 Example output:
429 528
430 529 .. code-block:: bash
431 530
432 531 id : <id_given_in_input>
433 532 result: [
434 533 {
435 "name" : "<name>"
436 "type" : "<type>",
437 "binary": "<true|false>" (only in extended mode)
438 "md5" : "<md5 of file content>" (only in extended mode)
534 "binary": false,
535 "content": "File line
536 Line2
537 ",
538 "extension": "md",
539 "lines": 2,
540 "md5": "059fa5d29b19c0657e384749480f6422",
541 "mimetype": "text/x-minidsrc",
542 "name": "file.md",
543 "size": 580,
544 "type": "file"
439 545 },
440 546 ...
441 547 ]
442 548 error: null
443 549
444 550
445 551 get_repo_refs
446 552 -------------
447 553
448 554 .. py:function:: get_repo_refs(apiuser, repoid)
449 555
450 556 Returns a dictionary of current references. It returns
451 557 bookmarks, branches, closed_branches, and tags for given repository
452 558
453 559 It's possible to specify ret_type to show only `files` or `dirs`.
454 560
455 561 This command can only be run using an |authtoken| with admin rights,
456 562 or users with at least read rights to |repos|.
457 563
458 564 :param apiuser: This is filled automatically from the |authtoken|.
459 565 :type apiuser: AuthUser
460 566 :param repoid: The repository name or repository ID.
461 567 :type repoid: str or int
462 568
463 569 Example output:
464 570
465 571 .. code-block:: bash
466 572
467 573 id : <id_given_in_input>
468 574 "result": {
469 575 "bookmarks": {
470 576 "dev": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
471 577 "master": "367f590445081d8ec8c2ea0456e73ae1f1c3d6cf"
472 578 },
473 579 "branches": {
474 580 "default": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
475 581 "stable": "367f590445081d8ec8c2ea0456e73ae1f1c3d6cf"
476 582 },
477 583 "branches_closed": {},
478 584 "tags": {
479 585 "tip": "5611d30200f4040ba2ab4f3d64e5b06408a02188",
480 586 "v4.4.0": "1232313f9e6adac5ce5399c2a891dc1e72b79022",
481 587 "v4.4.1": "cbb9f1d329ae5768379cdec55a62ebdd546c4e27",
482 588 "v4.4.2": "24ffe44a27fcd1c5b6936144e176b9f6dd2f3a17",
483 589 }
484 590 }
485 591 error: null
486 592
487 593
488 594 get_repo_settings
489 595 -----------------
490 596
491 597 .. py:function:: get_repo_settings(apiuser, repoid, key=<Optional:None>)
492 598
493 599 Returns all settings for a repository. If key is given it only returns the
494 600 setting identified by the key or null.
495 601
496 602 :param apiuser: This is filled automatically from the |authtoken|.
497 603 :type apiuser: AuthUser
498 604 :param repoid: The repository name or repository id.
499 605 :type repoid: str or int
500 606 :param key: Key of the setting to return.
501 607 :type: key: Optional(str)
502 608
503 609 Example output:
504 610
505 611 .. code-block:: bash
506 612
507 613 {
508 614 "error": null,
509 615 "id": 237,
510 616 "result": {
511 617 "extensions_largefiles": true,
512 618 "extensions_evolve": true,
513 619 "hooks_changegroup_push_logger": true,
514 620 "hooks_changegroup_repo_size": false,
515 621 "hooks_outgoing_pull_logger": true,
516 622 "phases_publish": "True",
517 623 "rhodecode_hg_use_rebase_for_merging": true,
518 624 "rhodecode_pr_merge_enabled": true,
519 625 "rhodecode_use_outdated_comments": true
520 626 }
521 627 }
522 628
523 629
524 630 get_repos
525 631 ---------
526 632
527 633 .. py:function:: get_repos(apiuser, root=<Optional:None>, traverse=<Optional:True>)
528 634
529 635 Lists all existing repositories.
530 636
531 637 This command can only be run using an |authtoken| with admin rights,
532 638 or users with at least read rights to |repos|.
533 639
534 640 :param apiuser: This is filled automatically from the |authtoken|.
535 641 :type apiuser: AuthUser
536 642 :param root: specify root repository group to fetch repositories.
537 643 filters the returned repositories to be members of given root group.
538 644 :type root: Optional(None)
539 645 :param traverse: traverse given root into subrepositories. With this flag
540 646 set to False, it will only return top-level repositories from `root`.
541 647 if root is empty it will return just top-level repositories.
542 648 :type traverse: Optional(True)
543 649
544 650
545 651 Example output:
546 652
547 653 .. code-block:: bash
548 654
549 655 id : <id_given_in_input>
550 656 result: [
551 657 {
552 658 "repo_id" : "<repo_id>",
553 659 "repo_name" : "<reponame>"
554 660 "repo_type" : "<repo_type>",
555 661 "clone_uri" : "<clone_uri>",
556 662 "private": : "<bool>",
557 663 "created_on" : "<datetimecreated>",
558 664 "description" : "<description>",
559 665 "landing_rev": "<landing_rev>",
560 666 "owner": "<repo_owner>",
561 667 "fork_of": "<name_of_fork_parent>",
562 668 "enable_downloads": "<bool>",
563 669 "enable_locking": "<bool>",
564 670 "enable_statistics": "<bool>",
565 671 },
566 672 ...
567 673 ]
568 674 error: null
569 675
570 676
571 677 grant_user_group_permission
572 678 ---------------------------
573 679
574 680 .. py:function:: grant_user_group_permission(apiuser, repoid, usergroupid, perm)
575 681
576 682 Grant permission for a user group on the specified repository,
577 683 or update existing permissions.
578 684
579 685 This command can only be run using an |authtoken| with admin
580 686 permissions on the |repo|.
581 687
582 688 :param apiuser: This is filled automatically from the |authtoken|.
583 689 :type apiuser: AuthUser
584 690 :param repoid: Set the repository name or repository ID.
585 691 :type repoid: str or int
586 692 :param usergroupid: Specify the ID of the user group.
587 693 :type usergroupid: str or int
588 694 :param perm: Set the user group permissions using the following
589 695 format: (repository.(none|read|write|admin))
590 696 :type perm: str
591 697
592 698 Example output:
593 699
594 700 .. code-block:: bash
595 701
596 702 id : <id_given_in_input>
597 703 result : {
598 704 "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
599 705 "success": true
600 706
601 707 }
602 708 error : null
603 709
604 710 Example error output:
605 711
606 712 .. code-block:: bash
607 713
608 714 id : <id_given_in_input>
609 715 result : null
610 716 error : {
611 717 "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
612 718 }
613 719
614 720
615 721 grant_user_permission
616 722 ---------------------
617 723
618 724 .. py:function:: grant_user_permission(apiuser, repoid, userid, perm)
619 725
620 726 Grant permissions for the specified user on the given repository,
621 727 or update existing permissions if found.
622 728
623 729 This command can only be run using an |authtoken| with admin
624 730 permissions on the |repo|.
625 731
626 732 :param apiuser: This is filled automatically from the |authtoken|.
627 733 :type apiuser: AuthUser
628 734 :param repoid: Set the repository name or repository ID.
629 735 :type repoid: str or int
630 736 :param userid: Set the user name.
631 737 :type userid: str
632 738 :param perm: Set the user permissions, using the following format
633 739 ``(repository.(none|read|write|admin))``
634 740 :type perm: str
635 741
636 742 Example output:
637 743
638 744 .. code-block:: bash
639 745
640 746 id : <id_given_in_input>
641 747 result: {
642 748 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
643 749 "success": true
644 750 }
645 751 error: null
646 752
647 753
648 754 invalidate_cache
649 755 ----------------
650 756
651 757 .. py:function:: invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)
652 758
653 759 Invalidates the cache for the specified repository.
654 760
655 761 This command can only be run using an |authtoken| with admin rights to
656 762 the specified repository.
657 763
658 764 This command takes the following options:
659 765
660 766 :param apiuser: This is filled automatically from |authtoken|.
661 767 :type apiuser: AuthUser
662 768 :param repoid: Sets the repository name or repository ID.
663 769 :type repoid: str or int
664 770 :param delete_keys: This deletes the invalidated keys instead of
665 771 just flagging them.
666 772 :type delete_keys: Optional(``True`` | ``False``)
667 773
668 774 Example output:
669 775
670 776 .. code-block:: bash
671 777
672 778 id : <id_given_in_input>
673 779 result : {
674 780 'msg': Cache for repository `<repository name>` was invalidated,
675 781 'repository': <repository name>
676 782 }
677 783 error : null
678 784
679 785 Example error output:
680 786
681 787 .. code-block:: bash
682 788
683 789 id : <id_given_in_input>
684 790 result : null
685 791 error : {
686 792 'Error occurred during cache invalidation action'
687 793 }
688 794
689 795
690 796 lock
691 797 ----
692 798
693 799 .. py:function:: lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
694 800
695 801 Sets the lock state of the specified |repo| by the given user.
696 802 From more information, see :ref:`repo-locking`.
697 803
698 804 * If the ``userid`` option is not set, the repository is locked to the
699 805 user who called the method.
700 806 * If the ``locked`` parameter is not set, the current lock state of the
701 807 repository is displayed.
702 808
703 809 This command can only be run using an |authtoken| with admin rights to
704 810 the specified repository.
705 811
706 812 This command takes the following options:
707 813
708 814 :param apiuser: This is filled automatically from the |authtoken|.
709 815 :type apiuser: AuthUser
710 816 :param repoid: Sets the repository name or repository ID.
711 817 :type repoid: str or int
712 818 :param locked: Sets the lock state.
713 819 :type locked: Optional(``True`` | ``False``)
714 820 :param userid: Set the repository lock to this user.
715 821 :type userid: Optional(str or int)
716 822
717 823 Example error output:
718 824
719 825 .. code-block:: bash
720 826
721 827 id : <id_given_in_input>
722 828 result : {
723 829 'repo': '<reponame>',
724 830 'locked': <bool: lock state>,
725 831 'locked_since': <int: lock timestamp>,
726 832 'locked_by': <username of person who made the lock>,
727 833 'lock_reason': <str: reason for locking>,
728 834 'lock_state_changed': <bool: True if lock state has been changed in this request>,
729 835 'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
730 836 or
731 837 'msg': 'Repo `<repository name>` not locked.'
732 838 or
733 839 'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
734 840 }
735 841 error : null
736 842
737 843 Example error output:
738 844
739 845 .. code-block:: bash
740 846
741 847 id : <id_given_in_input>
742 848 result : null
743 849 error : {
744 850 'Error occurred locking repository `<reponame>`'
745 851 }
746 852
747 853
748 854 maintenance
749 855 -----------
750 856
751 857 .. py:function:: maintenance(apiuser, repoid)
752 858
753 859 Triggers a maintenance on the given repository.
754 860
755 861 This command can only be run using an |authtoken| with admin
756 862 rights to the specified repository. For more information,
757 863 see :ref:`config-token-ref`.
758 864
759 865 This command takes the following options:
760 866
761 867 :param apiuser: This is filled automatically from the |authtoken|.
762 868 :type apiuser: AuthUser
763 869 :param repoid: The repository name or repository ID.
764 870 :type repoid: str or int
765 871
766 872 Example output:
767 873
768 874 .. code-block:: bash
769 875
770 876 id : <id_given_in_input>
771 877 result : {
772 878 "msg": "executed maintenance command",
773 879 "executed_actions": [
774 880 <action_message>, <action_message2>...
775 881 ],
776 882 "repository": "<repository name>"
777 883 }
778 884 error : null
779 885
780 886 Example error output:
781 887
782 888 .. code-block:: bash
783 889
784 890 id : <id_given_in_input>
785 891 result : null
786 892 error : {
787 893 "Unable to execute maintenance on `<reponame>`"
788 894 }
789 895
790 896
791 897 pull
792 898 ----
793 899
794 900 .. py:function:: pull(apiuser, repoid, remote_uri=<Optional:None>)
795 901
796 902 Triggers a pull on the given repository from a remote location. You
797 903 can use this to keep remote repositories up-to-date.
798 904
799 905 This command can only be run using an |authtoken| with admin
800 906 rights to the specified repository. For more information,
801 907 see :ref:`config-token-ref`.
802 908
803 909 This command takes the following options:
804 910
805 911 :param apiuser: This is filled automatically from the |authtoken|.
806 912 :type apiuser: AuthUser
807 913 :param repoid: The repository name or repository ID.
808 914 :type repoid: str or int
809 915 :param remote_uri: Optional remote URI to pass in for pull
810 916 :type remote_uri: str
811 917
812 918 Example output:
813 919
814 920 .. code-block:: bash
815 921
816 922 id : <id_given_in_input>
817 923 result : {
818 924 "msg": "Pulled from url `<remote_url>` on repo `<repository name>`"
819 925 "repository": "<repository name>"
820 926 }
821 927 error : null
822 928
823 929 Example error output:
824 930
825 931 .. code-block:: bash
826 932
827 933 id : <id_given_in_input>
828 934 result : null
829 935 error : {
830 936 "Unable to push changes from `<remote_url>`"
831 937 }
832 938
833 939
834 940 remove_field_from_repo
835 941 ----------------------
836 942
837 943 .. py:function:: remove_field_from_repo(apiuser, repoid, key)
838 944
839 945 Removes an extra field from a repository.
840 946
841 947 This command can only be run using an |authtoken| with at least
842 948 write permissions to the |repo|.
843 949
844 950 :param apiuser: This is filled automatically from the |authtoken|.
845 951 :type apiuser: AuthUser
846 952 :param repoid: Set the repository name or repository ID.
847 953 :type repoid: str or int
848 954 :param key: Set the unique field key for this repository.
849 955 :type key: str
850 956
851 957
852 958 revoke_user_group_permission
853 959 ----------------------------
854 960
855 961 .. py:function:: revoke_user_group_permission(apiuser, repoid, usergroupid)
856 962
857 963 Revoke the permissions of a user group on a given repository.
858 964
859 965 This command can only be run using an |authtoken| with admin
860 966 permissions on the |repo|.
861 967
862 968 :param apiuser: This is filled automatically from the |authtoken|.
863 969 :type apiuser: AuthUser
864 970 :param repoid: Set the repository name or repository ID.
865 971 :type repoid: str or int
866 972 :param usergroupid: Specify the user group ID.
867 973 :type usergroupid: str or int
868 974
869 975 Example output:
870 976
871 977 .. code-block:: bash
872 978
873 979 id : <id_given_in_input>
874 980 result: {
875 981 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
876 982 "success": true
877 983 }
878 984 error: null
879 985
880 986
881 987 revoke_user_permission
882 988 ----------------------
883 989
884 990 .. py:function:: revoke_user_permission(apiuser, repoid, userid)
885 991
886 992 Revoke permission for a user on the specified repository.
887 993
888 994 This command can only be run using an |authtoken| with admin
889 995 permissions on the |repo|.
890 996
891 997 :param apiuser: This is filled automatically from the |authtoken|.
892 998 :type apiuser: AuthUser
893 999 :param repoid: Set the repository name or repository ID.
894 1000 :type repoid: str or int
895 1001 :param userid: Set the user name of revoked user.
896 1002 :type userid: str or int
897 1003
898 1004 Example error output:
899 1005
900 1006 .. code-block:: bash
901 1007
902 1008 id : <id_given_in_input>
903 1009 result: {
904 1010 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
905 1011 "success": true
906 1012 }
907 1013 error: null
908 1014
909 1015
910 1016 set_repo_settings
911 1017 -----------------
912 1018
913 1019 .. py:function:: set_repo_settings(apiuser, repoid, settings)
914 1020
915 1021 Update repository settings. Returns true on success.
916 1022
917 1023 :param apiuser: This is filled automatically from the |authtoken|.
918 1024 :type apiuser: AuthUser
919 1025 :param repoid: The repository name or repository id.
920 1026 :type repoid: str or int
921 1027 :param settings: The new settings for the repository.
922 1028 :type: settings: dict
923 1029
924 1030 Example output:
925 1031
926 1032 .. code-block:: bash
927 1033
928 1034 {
929 1035 "error": null,
930 1036 "id": 237,
931 1037 "result": true
932 1038 }
933 1039
934 1040
935 1041 strip
936 1042 -----
937 1043
938 1044 .. py:function:: strip(apiuser, repoid, revision, branch)
939 1045
940 1046 Strips the given revision from the specified repository.
941 1047
942 1048 * This will remove the revision and all of its decendants.
943 1049
944 1050 This command can only be run using an |authtoken| with admin rights to
945 1051 the specified repository.
946 1052
947 1053 This command takes the following options:
948 1054
949 1055 :param apiuser: This is filled automatically from the |authtoken|.
950 1056 :type apiuser: AuthUser
951 1057 :param repoid: The repository name or repository ID.
952 1058 :type repoid: str or int
953 1059 :param revision: The revision you wish to strip.
954 1060 :type revision: str
955 1061 :param branch: The branch from which to strip the revision.
956 1062 :type branch: str
957 1063
958 1064 Example output:
959 1065
960 1066 .. code-block:: bash
961 1067
962 1068 id : <id_given_in_input>
963 1069 result : {
964 1070 "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
965 1071 "repository": "<repository name>"
966 1072 }
967 1073 error : null
968 1074
969 1075 Example error output:
970 1076
971 1077 .. code-block:: bash
972 1078
973 1079 id : <id_given_in_input>
974 1080 result : null
975 1081 error : {
976 1082 "Unable to strip commit <commit_hash> from repo `<repository name>`"
977 1083 }
978 1084
979 1085
980 1086 update_repo
981 1087 -----------
982 1088
983 1089 .. py:function:: update_repo(apiuser, repoid, repo_name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, push_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, fork_of=<Optional:None>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)
984 1090
985 1091 Updates a repository with the given information.
986 1092
987 1093 This command can only be run using an |authtoken| with at least
988 1094 admin permissions to the |repo|.
989 1095
990 1096 * If the repository name contains "/", repository will be updated
991 1097 accordingly with a repository group or nested repository groups
992 1098
993 1099 For example repoid=repo-test name="foo/bar/repo-test" will update |repo|
994 1100 called "repo-test" and place it inside group "foo/bar".
995 1101 You have to have permissions to access and write to the last repository
996 1102 group ("bar" in this example)
997 1103
998 1104 :param apiuser: This is filled automatically from the |authtoken|.
999 1105 :type apiuser: AuthUser
1000 1106 :param repoid: repository name or repository ID.
1001 1107 :type repoid: str or int
1002 1108 :param repo_name: Update the |repo| name, including the
1003 1109 repository group it's in.
1004 1110 :type repo_name: str
1005 1111 :param owner: Set the |repo| owner.
1006 1112 :type owner: str
1007 1113 :param fork_of: Set the |repo| as fork of another |repo|.
1008 1114 :type fork_of: str
1009 1115 :param description: Update the |repo| description.
1010 1116 :type description: str
1011 1117 :param private: Set the |repo| as private. (True | False)
1012 1118 :type private: bool
1013 1119 :param clone_uri: Update the |repo| clone URI.
1014 1120 :type clone_uri: str
1015 1121 :param landing_rev: Set the |repo| landing revision. Default is ``rev:tip``.
1016 1122 :type landing_rev: str
1017 1123 :param enable_statistics: Enable statistics on the |repo|, (True | False).
1018 1124 :type enable_statistics: bool
1019 1125 :param enable_locking: Enable |repo| locking.
1020 1126 :type enable_locking: bool
1021 1127 :param enable_downloads: Enable downloads from the |repo|, (True | False).
1022 1128 :type enable_downloads: bool
1023 1129 :param fields: Add extra fields to the |repo|. Use the following
1024 1130 example format: ``field_key=field_val,field_key2=fieldval2``.
1025 1131 Escape ', ' with \,
1026 1132 :type fields: str
1027 1133
1028 1134
@@ -1,234 +1,268 b''
1 1 .. _server-methods-ref:
2 2
3 3 server methods
4 4 ==============
5 5
6 6 cleanup_sessions
7 7 ----------------
8 8
9 9 .. py:function:: cleanup_sessions(apiuser, older_then=<Optional:60>)
10 10
11 11 Triggers a session cleanup action.
12 12
13 13 If the ``older_then`` option is set, only sessions that hasn't been
14 14 accessed in the given number of days will be removed.
15 15
16 16 This command can only be run using an |authtoken| with admin rights to
17 17 the specified repository.
18 18
19 19 This command takes the following options:
20 20
21 21 :param apiuser: This is filled automatically from the |authtoken|.
22 22 :type apiuser: AuthUser
23 23 :param older_then: Deletes session that hasn't been accessed
24 24 in given number of days.
25 25 :type older_then: Optional(int)
26 26
27 27 Example output:
28 28
29 29 .. code-block:: bash
30 30
31 31 id : <id_given_in_input>
32 32 result: {
33 33 "backend": "<type of backend>",
34 34 "sessions_removed": <number_of_removed_sessions>
35 35 }
36 36 error : null
37 37
38 38 Example error output:
39 39
40 40 .. code-block:: bash
41 41
42 42 id : <id_given_in_input>
43 43 result : null
44 44 error : {
45 45 'Error occurred during session cleanup'
46 46 }
47 47
48 48
49 49 get_ip
50 50 ------
51 51
52 52 .. py:function:: get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
53 53
54 54 Displays the IP Address as seen from the |RCE| server.
55 55
56 56 * This command displays the IP Address, as well as all the defined IP
57 57 addresses for the specified user. If the ``userid`` is not set, the
58 58 data returned is for the user calling the method.
59 59
60 60 This command can only be run using an |authtoken| with admin rights to
61 61 the specified repository.
62 62
63 63 This command takes the following options:
64 64
65 65 :param apiuser: This is filled automatically from |authtoken|.
66 66 :type apiuser: AuthUser
67 67 :param userid: Sets the userid for which associated IP Address data
68 68 is returned.
69 69 :type userid: Optional(str or int)
70 70
71 71 Example output:
72 72
73 73 .. code-block:: bash
74 74
75 75 id : <id_given_in_input>
76 76 result : {
77 77 "server_ip_addr": "<ip_from_clien>",
78 78 "user_ips": [
79 79 {
80 80 "ip_addr": "<ip_with_mask>",
81 81 "ip_range": ["<start_ip>", "<end_ip>"],
82 82 },
83 83 ...
84 84 ]
85 85 }
86 86
87 87
88 88 get_method
89 89 ----------
90 90
91 91 .. py:function:: get_method(apiuser, pattern=<Optional:'*'>)
92 92
93 93 Returns list of all available API methods. By default match pattern
94 94 os "*" but any other pattern can be specified. eg *comment* will return
95 95 all methods with comment inside them. If just single method is matched
96 96 returned data will also include method specification
97 97
98 98 This command can only be run using an |authtoken| with admin rights to
99 99 the specified repository.
100 100
101 101 This command takes the following options:
102 102
103 103 :param apiuser: This is filled automatically from the |authtoken|.
104 104 :type apiuser: AuthUser
105 105 :param pattern: pattern to match method names against
106 :type older_then: Optional("*")
106 :type pattern: Optional("*")
107 107
108 108 Example output:
109 109
110 110 .. code-block:: bash
111 111
112 112 id : <id_given_in_input>
113 113 "result": [
114 114 "changeset_comment",
115 115 "comment_pull_request",
116 116 "comment_commit"
117 117 ]
118 118 error : null
119 119
120 120 .. code-block:: bash
121 121
122 122 id : <id_given_in_input>
123 123 "result": [
124 124 "comment_commit",
125 125 {
126 126 "apiuser": "<RequiredType>",
127 127 "comment_type": "<Optional:u'note'>",
128 128 "commit_id": "<RequiredType>",
129 129 "message": "<RequiredType>",
130 130 "repoid": "<RequiredType>",
131 131 "request": "<RequiredType>",
132 132 "resolves_comment_id": "<Optional:None>",
133 133 "status": "<Optional:None>",
134 134 "userid": "<Optional:<OptionalAttr:apiuser>>"
135 135 }
136 136 ]
137 137 error : null
138 138
139 139
140 140 get_repo_store
141 141 --------------
142 142
143 143 .. py:function:: get_repo_store(apiuser)
144 144
145 145 Returns the |RCE| repository storage information.
146 146
147 147 :param apiuser: This is filled automatically from the |authtoken|.
148 148 :type apiuser: AuthUser
149 149
150 150 Example output:
151 151
152 152 .. code-block:: bash
153 153
154 154 id : <id_given_in_input>
155 155 result : {
156 156 'modules': [<module name>,...]
157 157 'py_version': <python version>,
158 158 'platform': <platform type>,
159 159 'rhodecode_version': <rhodecode version>
160 160 }
161 161 error : null
162 162
163 163
164 164 get_server_info
165 165 ---------------
166 166
167 167 .. py:function:: get_server_info(apiuser)
168 168
169 169 Returns the |RCE| server information.
170 170
171 171 This includes the running version of |RCE| and all installed
172 172 packages. This command takes the following options:
173 173
174 174 :param apiuser: This is filled automatically from the |authtoken|.
175 175 :type apiuser: AuthUser
176 176
177 177 Example output:
178 178
179 179 .. code-block:: bash
180 180
181 181 id : <id_given_in_input>
182 182 result : {
183 183 'modules': [<module name>,...]
184 184 'py_version': <python version>,
185 185 'platform': <platform type>,
186 186 'rhodecode_version': <rhodecode version>
187 187 }
188 188 error : null
189 189
190 190
191 191 rescan_repos
192 192 ------------
193 193
194 194 .. py:function:: rescan_repos(apiuser, remove_obsolete=<Optional:False>)
195 195
196 196 Triggers a rescan of the specified repositories.
197 197
198 198 * If the ``remove_obsolete`` option is set, it also deletes repositories
199 199 that are found in the database but not on the file system, so called
200 200 "clean zombies".
201 201
202 202 This command can only be run using an |authtoken| with admin rights to
203 203 the specified repository.
204 204
205 205 This command takes the following options:
206 206
207 207 :param apiuser: This is filled automatically from the |authtoken|.
208 208 :type apiuser: AuthUser
209 209 :param remove_obsolete: Deletes repositories from the database that
210 210 are not found on the filesystem.
211 211 :type remove_obsolete: Optional(``True`` | ``False``)
212 212
213 213 Example output:
214 214
215 215 .. code-block:: bash
216 216
217 217 id : <id_given_in_input>
218 218 result : {
219 219 'added': [<added repository name>,...]
220 220 'removed': [<removed repository name>,...]
221 221 }
222 222 error : null
223 223
224 224 Example error output:
225 225
226 226 .. code-block:: bash
227 227
228 228 id : <id_given_in_input>
229 229 result : null
230 230 error : {
231 231 'Error occurred during rescan repositories action'
232 232 }
233 233
234 234
235 store_exception
236 ---------------
237
238 .. py:function:: store_exception(apiuser, exc_data_json, prefix=<Optional:'rhodecode'>)
239
240 Stores sent exception inside the built-in exception tracker in |RCE| server.
241
242 This command can only be run using an |authtoken| with admin rights to
243 the specified repository.
244
245 This command takes the following options:
246
247 :param apiuser: This is filled automatically from the |authtoken|.
248 :type apiuser: AuthUser
249
250 :param exc_data_json: JSON data with exception e.g
251 {"exc_traceback": "Value `1` is not allowed", "exc_type_name": "ValueError"}
252 :type exc_data_json: JSON data
253
254 :param prefix: prefix for error type, e.g 'rhodecode', 'vcsserver', 'rhodecode-tools'
255 :type prefix: Optional("rhodecode")
256
257 Example output:
258
259 .. code-block:: bash
260
261 id : <id_given_in_input>
262 "result": {
263 "exc_id": 139718459226384,
264 "exc_url": "http://localhost:8080/_admin/settings/exceptions/139718459226384"
265 }
266 error : null
267
268
1 NO CONTENT: file was removed
General Comments 0
You need to be logged in to leave comments. Login now