# HG changeset patch # User Marcin Kuzminski # Date 2020-01-07 14:10:16 # Node ID f7b5cdaba11b92f8797045cab4a07f63b5e53e92 # Parent c0982c75df18cc6a37bc225255cb89bdbc7fdc83 release: updated API docs 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 @@ -39,7 +39,7 @@ close_pull_request comment_pull_request -------------------- -.. py:function:: comment_pull_request(apiuser, pullrequestid, repoid=, message=, commit_id=, status=, comment_type=, resolves_comment_id=, userid=>) +.. py:function:: comment_pull_request(apiuser, pullrequestid, repoid=, message=, commit_id=, status=, comment_type=, resolves_comment_id=, extra_recipients=, userid=>) Comment on the pull request specified with the `pullrequestid`, in the |repo| specified by the `repoid`, and optionally change the @@ -63,6 +63,11 @@ comment_pull_request :type status: str :param comment_type: Comment type, one of: 'note', 'todo' :type comment_type: Optional(str), default: 'note' + :param resolves_comment_id: id of comment which this one will resolve + :type resolves_comment_id: Optional(int) + :param extra_recipients: list of user ids or usernames to add + notifications for this comment. Acts like a CC for notification + :type extra_recipients: Optional(list) :param userid: Comment on the pull request as this user :type userid: Optional(str or int) @@ -126,7 +131,7 @@ create_pull_request get_pull_request ---------------- -.. py:function:: get_pull_request(apiuser, pullrequestid, repoid=) +.. py:function:: get_pull_request(apiuser, pullrequestid, repoid=, merge_state=) Get a pull request based on the given ID. @@ -137,6 +142,9 @@ get_pull_request :type repoid: str or int :param pullrequestid: ID of the requested pull request. :type pullrequestid: int + :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: @@ -250,7 +258,7 @@ get_pull_request_comments get_pull_requests ----------------- -.. py:function:: get_pull_requests(apiuser, repoid, status=, merge_state=) +.. py:function:: get_pull_requests(apiuser, repoid, status=, merge_state=) Get all pull requests from the repository specified in `repoid`. 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 @@ -28,7 +28,7 @@ add_field_to_repo comment_commit -------------- -.. py:function:: comment_commit(apiuser, repoid, commit_id, message, status=, comment_type=, resolves_comment_id=, userid=>) +.. py:function:: comment_commit(apiuser, repoid, commit_id, message, status=, comment_type=, resolves_comment_id=, extra_recipients=, userid=>) Set a commit comment, and optionally change the status of the commit. @@ -45,6 +45,11 @@ comment_commit :type status: str :param comment_type: Comment type, one of: 'note', 'todo' :type comment_type: Optional(str), default: 'note' + :param resolves_comment_id: id of comment which this one will resolve + :type resolves_comment_id: Optional(int) + :param extra_recipients: list of user ids or usernames to add + notifications for this comment. Acts like a CC for notification + :type extra_recipients: Optional(list) :param userid: Set the user name of the comment creator. :type userid: Optional(str or int) @@ -66,7 +71,7 @@ comment_commit create_repo ----------- -.. py:function:: create_repo(apiuser, repo_name, repo_type, owner=>, description=, private=, clone_uri=, push_uri=, landing_rev=, enable_statistics=, enable_locking=, enable_downloads=, copy_permissions=) +.. py:function:: create_repo(apiuser, repo_name, repo_type, owner=>, description=, private=, clone_uri=, push_uri=, landing_rev=, enable_statistics=, enable_locking=, enable_downloads=, copy_permissions=) Creates a repository. @@ -97,7 +102,7 @@ create_repo :type clone_uri: str :param push_uri: set push_uri :type push_uri: str - :param landing_rev: : + :param landing_rev: :, e.g branch:default, book:dev, rev:abcd :type landing_rev: str :param enable_locking: :type enable_locking: bool @@ -169,7 +174,7 @@ delete_repo fork_repo --------- -.. py:function:: fork_repo(apiuser, repoid, fork_name, owner=>, description=, private=, clone_uri=, landing_rev=, copy_permissions=) +.. py:function:: fork_repo(apiuser, repoid, fork_name, owner=>, description=, private=, clone_uri=, landing_rev=, copy_permissions=) Creates a fork of the specified |repo|. @@ -198,7 +203,7 @@ fork_repo :type copy_permissions: bool :param private: Make the fork private. The default is False. :type private: bool - :param landing_rev: Set the landing revision. The default is tip. + :param landing_rev: Set the landing revision. E.g branch:default, book:dev, rev:abcd Example output: @@ -1085,7 +1090,7 @@ strip update_repo ----------- -.. py:function:: update_repo(apiuser, repoid, repo_name=, owner=>, description=, private=, clone_uri=, push_uri=, landing_rev=, fork_of=, enable_statistics=, enable_locking=, enable_downloads=, fields=) +.. py:function:: update_repo(apiuser, repoid, repo_name=, owner=>, description=, private=, clone_uri=, push_uri=, landing_rev=, fork_of=, enable_statistics=, enable_locking=, enable_downloads=, fields=) Updates a repository with the given information. @@ -1117,7 +1122,7 @@ update_repo :type private: bool :param clone_uri: Update the |repo| clone URI. :type clone_uri: str - :param landing_rev: Set the |repo| landing revision. Default is ``rev:tip``. + :param landing_rev: Set the |repo| landing revision. e.g branch:default, book:dev, rev:abcd :type landing_rev: str :param enable_statistics: Enable statistics on the |repo|, (True | False). :type enable_statistics: bool diff --git a/docs/api/methods/search-methods.rst b/docs/api/methods/search-methods.rst --- a/docs/api/methods/search-methods.rst +++ b/docs/api/methods/search-methods.rst @@ -6,7 +6,7 @@ search methods search ------ -.. py:function:: search(apiuser, search_query, search_type, page_limit=, page=, search_sort=, repo_name=, repo_group_name=) +.. py:function:: search(apiuser, search_query, search_type, page_limit=, page=, search_sort=, repo_name=, repo_group_name=) Fetch Full Text Search results using API. @@ -23,9 +23,15 @@ search :type page_limit: Optional(int) :param page: Page number. Default first page. :type page: Optional(int) - :param search_sort: Search sort order. Default newfirst. The following are valid options: - * newfirst - * oldfirst + :param search_sort: Search sort order.Must start with asc: or desc: Default desc:date. + The following are valid options: + * asc|desc:message.raw + * asc|desc:date + * asc|desc:author.email.raw + * asc|desc:message.raw + * newfirst (old legacy equal to desc:date) + * oldfirst (old legacy equal to asc:date) + :type search_sort: Optional(str) :param repo_name: Filter by one repo. Default is all. :type repo_name: Optional(str) diff --git a/docs/api/methods/store-methods.rst b/docs/api/methods/store-methods.rst --- a/docs/api/methods/store-methods.rst +++ b/docs/api/methods/store-methods.rst @@ -6,7 +6,7 @@ store methods file_store_add (EE only) ------------------------ -.. py:function:: file_store_add(apiuser, filename, content) +.. py:function:: file_store_add(apiuser, filename, content, description=) Upload API for the file_store @@ -19,6 +19,8 @@ file_store_add (EE only) :type apiuser: AuthUser :param filename: name of the file uploaded :type filename: str + :param description: Optional description for added file + :type description: str :param content: base64 encoded content of the uploaded file :type content: str @@ -35,3 +37,148 @@ file_store_add (EE only) error : null +file_store_add_with_acl (EE only) +--------------------------------- + +.. py:function:: file_store_add_with_acl(apiuser, filename, content, description=, scope_user_id=, scope_repo_id=, scope_repo_group_id=) + + 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", "scope_repo_id":101}" + + 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 description: Optional description for added file + :type description: str + :param content: base64 encoded content of the uploaded file + :type content: str + + :param scope_user_id: Optionally bind this file to user. + This will check ACL in such way only this user can access the file. + :type scope_user_id: int + :param scope_repo_id: Optionally bind this file to repository. + This will check ACL in such way only user with proper access to such + repository can access the file. + :type scope_repo_id: int + :param scope_repo_group_id: Optionally bind this file to repository group. + This will check ACL in such way only user with proper access to such + repository group can access the file. + :type scope_repo_group_id: int + + 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 + + +file_store_get_info (EE only) +----------------------------- + +.. py:function:: file_store_get_info(apiuser, store_fid) + + Get artifact data. + + Example output: + + .. code-block:: bash + + id : + result: { + "artifact": { + "access_path_fqn": "https://rhodecode.example.com/_file_store/download/0-031c2aa0-0d56-49a7-9ba3-b570bdd342ab.jpg", + "created_on": "2019-10-15T16:25:35.491", + "description": "my upload", + "downloaded_times": 1, + "file_uid": "0-031c2aa0-0d56-49a7-9ba3-b570bdd342ab.jpg", + "filename": "example.jpg", + "filename_org": "0-031c2aa0-0d56-49a7-9ba3-b570bdd342ab.jpg", + "hidden": false, + "metadata": [ + { + "artifact": "0-031c2aa0-0d56-49a7-9ba3-b570bdd342ab.jpg", + "key": "yellow", + "section": "tags", + "value": "bar" + } + ], + "sha256": "818dff0f44574dfb6814d38e6bf3c60c5943d1d13653398ecddaedf2f6a5b04d", + "size": 18599, + "uploaded_by": { + "email": "admin@rhodecode.com", + "emails": [ + "admin@rhodecode.com" + ], + "firstname": "Admin", + "lastname": "LastName", + "user_id": 2, + "username": "admin" + } + } + } + error : null + + +file_store_add_metadata (EE only) +--------------------------------- + +.. py:function:: file_store_add_metadata(apiuser, store_fid, section, key, value, value_type=) + + Add metadata into artifact. The metadata consist of section, key, value. eg. + section='tags', 'key'='tag_name', value='1' + + :param apiuser: This is filled automatically from the |authtoken|. + :type apiuser: AuthUser + + :param store_fid: file uid, e.g 0-d054cb71-91ab-44e2-9e4b-23fe14b4d74a.mp4 + :type store_fid: str + + :param section: Section name to add metadata + :type section: str + + :param key: Key to add as metadata + :type key: str + + :param value: Value to add as metadata + :type value: str + + :param value_type: Optional type, default is 'unicode' other types are: + int, list, bool, unicode, str + + :type value_type: str + + Example output: + + .. code-block:: bash + + id : + result: { + "metadata": [ + { + "artifact": "0-d054cb71-91ab-44e2-9e4b-23fe14b4d74a.mp4", + "key": "secret", + "section": "tags", + "value": "1" + }, + { + "artifact": "0-d054cb71-91ab-44e2-9e4b-23fe14b4d74a.mp4", + "key": "video", + "section": "tags", + "value": "1" + } + ] + } + error : null + + diff --git a/docs/api/methods/user-group-methods.rst b/docs/api/methods/user-group-methods.rst --- a/docs/api/methods/user-group-methods.rst +++ b/docs/api/methods/user-group-methods.rst @@ -72,7 +72,9 @@ create_user_group :param active: Set this group as active. :type active: Optional(``True`` | ``False``) :param sync: Set enabled or disabled the automatically sync from - external authentication types like ldap. + external authentication types like ldap. If User Group will be named like + one from e.g ldap and sync flag is enabled members will be synced automatically. + Sync type when enabled via API is set to `manual_api` :type sync: Optional(``True`` | ``False``) Example output: @@ -391,7 +393,9 @@ update_user_group :param active: Set the group as active. :type active: Optional(``True`` | ``False``) :param sync: Set enabled or disabled the automatically sync from - external authentication types like ldap. + external authentication types like ldap. If User Group will be named like + one from e.g ldap and sync flag is enabled members will be synced automatically. + Sync type when enabled via API is set to `manual_api` :type sync: Optional(``True`` | ``False``) Example output: diff --git a/docs/api/methods/user-methods.rst b/docs/api/methods/user-methods.rst --- a/docs/api/methods/user-methods.rst +++ b/docs/api/methods/user-methods.rst @@ -6,7 +6,7 @@ user methods create_user ----------- -.. py:function:: create_user(apiuser, username, email, password=, firstname=, lastname=, active=, admin=, extern_name=, extern_type=, force_password_change=, create_personal_repo_group=) +.. py:function:: create_user(apiuser, username, email, password=, firstname=, lastname=, description=, active=, admin=, extern_name=, extern_type=, force_password_change=, create_personal_repo_group=) Creates a new user and returns the new user object. @@ -27,6 +27,8 @@ create_user :type firstname: Optional(str) :param lastname: Set the new user surname. :type lastname: Optional(str) + :param description: Set user description, or short bio. Metatags are allowed. + :type description: Optional(str) :param active: Set the user as active. :type active: Optional(``True`` | ``False``) :param admin: Give the new user admin rights. @@ -155,6 +157,7 @@ get_user "extern_name": "rhodecode", "extern_type": "rhodecode", "firstname": "username", + "description": "user description", "ip_addresses": [], "language": null, "last_login": "Timestamp", @@ -268,7 +271,7 @@ get_users update_user ----------- -.. py:function:: update_user(apiuser, userid, username=, email=, password=, firstname=, lastname=, active=, admin=, extern_type=, extern_name=) +.. py:function:: update_user(apiuser, userid, username=, email=, password=, firstname=, lastname=, description=, active=, admin=, extern_type=, extern_name=) Updates the details for the specified user, if that user exists. @@ -291,6 +294,8 @@ update_user :type firstname: Optional(str) :param lastname: Set the new surname. :type lastname: Optional(str) + :param description: Set user description, or short bio. Metatags are allowed. + :type description: Optional(str) :param active: Set the new user as active. :type active: Optional(``True`` | ``False``) :param admin: Give the user admin rights.