# HG changeset patch # User Marcin Kuzminski # Date 2019-02-22 22:44:24 # Node ID 32c1e2aac56b4c093796aa3a85f53751022631f2 # Parent e189052ff8a27d43930e9ad685485ccec9f2bd16 docs: update API documentation diff --git a/docs/api/api.rst b/docs/api/api.rst --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -196,7 +196,8 @@ are not required in args. .. --- API DEFS MARKER --- .. toctree:: - methods/views + methods/repo-methods + methods/store-methods methods/license-methods methods/deprecated-methods methods/gist-methods diff --git a/docs/api/methods/pull-request-methods.rst b/docs/api/methods/pull-request-methods.rst --- a/docs/api/methods/pull-request-methods.rst +++ b/docs/api/methods/pull-request-methods.rst @@ -83,7 +83,7 @@ comment_pull_request create_pull_request ------------------- -.. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title=, description=, description_renderer=, reviewers=) +.. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, owner=>, title=, description=, description_renderer=, reviewers=) Creates a new pull request. @@ -104,6 +104,8 @@ create_pull_request :type source_ref: str :param target_ref: Set the target ref name. :type target_ref: str + :param owner: user_id or username + :type owner: Optional(str) :param title: Optionally Set the pull request title, it's generated otherwise :type title: str :param description: Set the pull request description. @@ -248,7 +250,7 @@ get_pull_request_comments get_pull_requests ----------------- -.. py:function:: get_pull_requests(apiuser, repoid, status=) +.. py:function:: get_pull_requests(apiuser, repoid, status=, merge_state=) Get all pull requests from the repository specified in `repoid`. @@ -262,6 +264,9 @@ get_pull_requests * ``open`` * ``closed`` :type status: str + :param merge_state: Optional calculate merge state for each repository. + This could result in longer time to fetch the data + :type merge_state: bool Example output: @@ -356,10 +361,11 @@ merge_pull_request "id": , "result": { - "executed": "", - "failure_reason": "", - "merge_commit_id": "", - "possible": "", + "executed": "", + "failure_reason": "", + "merge_status_message": "", + "merge_commit_id": "", + "possible": "", "merge_ref": { "commit_id": "", "type": "", diff --git a/docs/api/methods/repo-methods.rst b/docs/api/methods/repo-methods.rst --- a/docs/api/methods/repo-methods.rst +++ b/docs/api/methods/repo-methods.rst @@ -394,15 +394,54 @@ get_repo_changesets of changed files. -get_repo_nodes --------------- +get_repo_comments +----------------- + +.. py:function:: get_repo_comments(apiuser, repoid, commit_id=, comment_type=, userid=) + + Get all comments for a repository -.. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=, details=, max_file_bytes=) + :param apiuser: This is filled automatically from the |authtoken|. + :type apiuser: AuthUser + :param repoid: Set the repository name or repository ID. + :type repoid: str or int + :param commit_id: Optionally filter the comments by the commit_id + :type commit_id: Optional(str), default: None + :param comment_type: Optionally filter the comments by the comment_type + one of: 'note', 'todo' + :type comment_type: Optional(str), default: None + :param userid: Optionally filter the comments by the author of comment + :type userid: Optional(str or int), Default: None + + Example error output: + + .. code-block:: bash - Returns a list of nodes and children in a flat list for a given - path at given revision. + { + "id" : , + "result" : [ + { + "comment_author": , + "comment_created_on": "2017-02-01T14:38:16.309", + "comment_f_path": "file.txt", + "comment_id": 282, + "comment_lineno": "n1", + "comment_resolved_by": null, + "comment_status": [], + "comment_text": "This file needs a header", + "comment_type": "todo" + } + ], + "error" : null + } - It's possible to specify ret_type to show only `files` or `dirs`. + +get_repo_file +------------- + +.. py:function:: get_repo_file(apiuser, repoid, commit_id, file_path, max_file_bytes=, details=, cache=) + + Returns a single file from repository at given revision. This command can only be run using an |authtoken| with admin rights, or users with at least read rights to |repos|. @@ -411,37 +450,104 @@ get_repo_nodes :type apiuser: AuthUser :param repoid: The repository name or repository ID. :type repoid: str or int - :param revision: The revision for which listing should be done. - :type revision: str - :param root_path: The path from which to start displaying. - :type root_path: str - :param ret_type: Set the return type. Valid options are - ``all`` (default), ``files`` and ``dirs``. - :type ret_type: Optional(str) - :param details: Returns extended information about nodes, such as - md5, binary, and or content. The valid options are ``basic`` and - ``full``. + :param commit_id: The revision for which listing should be done. + :type commit_id: str + :param file_path: The path from which to start displaying. + :type file_path: str + :param details: Returns different set of information about nodes. + The valid options are ``minimal`` ``basic`` and ``full``. :type details: Optional(str) :param max_file_bytes: Only return file content under this file size bytes - :type details: Optional(int) - + :type max_file_bytes: Optional(int) + :param cache: Use internal caches for fetching files. If disabled fetching + files is slower but more memory efficient + :type cache: Optional(bool) Example output: .. code-block:: bash id : - result: [ - { - "name" : "" - "type" : "", - "binary": "" (only in extended mode) - "md5" : "" (only in extended mode) - }, - ... - ] + result: { + "binary": false, + "extension": "py", + "lines": 35, + "content": "....", + "md5": "76318336366b0f17ee249e11b0c99c41", + "mimetype": "text/x-python", + "name": "python.py", + "size": 817, + "type": "file", + } error: null +get_repo_fts_tree +----------------- + +.. py:function:: get_repo_fts_tree(apiuser, repoid, commit_id, root_path) + + Returns a list of tree nodes for path at given revision. This api is built + strictly for usage in full text search building, and shouldn't be consumed + + This command can only be run using an |authtoken| with admin rights, + or users with at least read rights to |repos|. + + +get_repo_nodes +-------------- + +.. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=, details=, max_file_bytes=) + + Returns a list of nodes and children in a flat list for a given + path at given revision. + + It's possible to specify ret_type to show only `files` or `dirs`. + + This command can only be run using an |authtoken| with admin rights, + or users with at least read rights to |repos|. + + :param apiuser: This is filled automatically from the |authtoken|. + :type apiuser: AuthUser + :param repoid: The repository name or repository ID. + :type repoid: str or int + :param revision: The revision for which listing should be done. + :type revision: str + :param root_path: The path from which to start displaying. + :type root_path: str + :param ret_type: Set the return type. Valid options are + ``all`` (default), ``files`` and ``dirs``. + :type ret_type: Optional(str) + :param details: Returns extended information about nodes, such as + md5, binary, and or content. + The valid options are ``basic`` and ``full``. + :type details: Optional(str) + :param max_file_bytes: Only return file content under this file size bytes + :type details: Optional(int) + + Example output: + + .. code-block:: bash + + id : + result: [ + { + "binary": false, + "content": "File line + Line2 + ", + "extension": "md", + "lines": 2, + "md5": "059fa5d29b19c0657e384749480f6422", + "mimetype": "text/x-minidsrc", + "name": "file.md", + "size": 580, + "type": "file" + }, + ... + ] + error: null + + get_repo_refs ------------- diff --git a/docs/api/methods/server-methods.rst b/docs/api/methods/server-methods.rst --- a/docs/api/methods/server-methods.rst +++ b/docs/api/methods/server-methods.rst @@ -103,7 +103,7 @@ get_method :param apiuser: This is filled automatically from the |authtoken|. :type apiuser: AuthUser :param pattern: pattern to match method names against - :type older_then: Optional("*") + :type pattern: Optional("*") Example output: @@ -232,3 +232,37 @@ rescan_repos } +store_exception +--------------- + +.. py:function:: store_exception(apiuser, exc_data_json, prefix=) + + Stores sent exception inside the built-in exception tracker in |RCE| server. + + This command can only be run using an |authtoken| with admin rights to + the specified repository. + + This command takes the following options: + + :param apiuser: This is filled automatically from the |authtoken|. + :type apiuser: AuthUser + + :param exc_data_json: JSON data with exception e.g + {"exc_traceback": "Value `1` is not allowed", "exc_type_name": "ValueError"} + :type exc_data_json: JSON data + + :param prefix: prefix for error type, e.g 'rhodecode', 'vcsserver', 'rhodecode-tools' + :type prefix: Optional("rhodecode") + + Example output: + + .. code-block:: bash + + id : + "result": { + "exc_id": 139718459226384, + "exc_url": "http://localhost:8080/_admin/settings/exceptions/139718459226384" + } + error : null + + diff --git a/docs/api/methods/store-methods.rst b/docs/api/methods/store-methods.rst new file mode 100644 --- /dev/null +++ b/docs/api/methods/store-methods.rst @@ -0,0 +1,37 @@ +.. _store-methods-ref: + +store methods +============= + +file_store_add (EE only) +------------------------ + +.. py:function:: file_store_add(apiuser, filename, content) + + Upload API for the file_store + + Example usage from CLI:: + rhodecode-api --instance-name=enterprise-1 upload_file "{"content": "$(cat image.jpg | base64)", "filename":"image.jpg"}" + + This command takes the following options: + + :param apiuser: This is filled automatically from the |authtoken|. + :type apiuser: AuthUser + :param filename: name of the file uploaded + :type filename: str + :param content: base64 encoded content of the uploaded file + :type content: str + + Example output: + + .. code-block:: bash + + id : + result: { + "access_path": "/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg", + "access_path_fqn": "http://server.domain.com/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg", + "store_fid": "84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg" + } + error : null + + diff --git a/docs/api/methods/views.rst b/docs/api/methods/views.rst deleted file mode 100644 --- a/docs/api/methods/views.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _views-ref: - -views -===== - -push (EE only) --------------- - -.. py:function:: push(apiuser, repoid, remote_uri=) - - Triggers a push on the given repository from a remote location. You - can use this to keep remote repositories up-to-date. - - This command can only be run using an |authtoken| with admin - rights to the specified repository. For more information, - see :ref:`config-token-ref`. - - This command takes the following options: - - :param apiuser: This is filled automatically from the |authtoken|. - :type apiuser: AuthUser - :param repoid: The repository name or repository ID. - :type repoid: str or int - :param remote_uri: Optional remote URI to pass in for push - :type remote_uri: str - - Example output: - - .. code-block:: bash - - id : - result : { - "msg": "Pushed to url `` on repo ``" - "repository": "" - } - error : null - - Example error output: - - .. code-block:: bash - - id : - result : null - error : { - "Unable to push changes to ``" - } - -