release: updated API docs

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=<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>>)
+.. 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>, extra_recipients=<Optional:[]>, userid=<Optional:<OptionalAttr:apiuser>>)
 
    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=<Optional:None>)
+.. py:function:: get_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, merge_state=<Optional:False>)
 
    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=<Optional:'new'>, merge_state=<Optional:True>)
+.. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>, merge_state=<Optional:False>)
 
    Get all pull requests from the repository specified in `repoid`.
 

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=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
+.. py:function:: comment_commit(apiuser, repoid, commit_id, message, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, extra_recipients=<Optional:[]>, userid=<Optional:<OptionalAttr:apiuser>>)
 
    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=<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>)
+.. 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:None>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)
 
    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: <rev_type>:<rev>
+   :param landing_rev: <rev_type>:<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=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, copy_permissions=<Optional:False>)
+.. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:None>, copy_permissions=<Optional:False>)
 
    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=<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:''>)
+.. 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:None>, fork_of=<Optional:None>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)
 
    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

docs/api/methods/search-methods.rst

@@ -6,7 +6,7 @@ search methods
 search 
 ------
 
-.. py:function:: search(apiuser, search_query, search_type, page_limit=<Optional:10>, page=<Optional:1>, search_sort=<Optional:'newfirst'>, repo_name=<Optional:None>, repo_group_name=<Optional:None>)
+.. py:function:: search(apiuser, search_query, search_type, page_limit=<Optional:10>, page=<Optional:1>, search_sort=<Optional:'desc:date'>, repo_name=<Optional:None>, repo_group_name=<Optional:None>)
 
    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:
+   :param search_sort: Search sort order.Must start with asc: or desc: Default desc:date.
-       * newfirst
+       The following are valid options:
-       * oldfirst
+       * 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)

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=<Optional:''>)
 
    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=<Optional:''>, scope_user_id=<Optional:None>, scope_repo_id=<Optional:None>, scope_repo_group_id=<Optional:None>)
+
+   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 : <id_given_in_input>
+     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 : <id_given_in_input>
+     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=<Optional:'unicode'>)
+
+   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 : <id_given_in_input>
+     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
+
+

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:

docs/api/methods/user-methods.rst

@@ -6,7 +6,7 @@ user methods
 create_user 
 -----------
 
-.. py:function:: create_user(apiuser, username, email, password=<Optional:''>, firstname=<Optional:''>, lastname=<Optional:''>, active=<Optional:True>, admin=<Optional:False>, extern_name=<Optional:'rhodecode'>, extern_type=<Optional:'rhodecode'>, force_password_change=<Optional:False>, create_personal_repo_group=<Optional:None>)
+.. py:function:: create_user(apiuser, username, email, password=<Optional:''>, firstname=<Optional:''>, lastname=<Optional:''>, description=<Optional:''>, active=<Optional:True>, admin=<Optional:False>, extern_name=<Optional:'rhodecode'>, extern_type=<Optional:'rhodecode'>, force_password_change=<Optional:False>, create_personal_repo_group=<Optional:None>)
 
    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=<Optional:None>, email=<Optional:None>, password=<Optional:None>, firstname=<Optional:None>, lastname=<Optional:None>, active=<Optional:None>, admin=<Optional:None>, extern_type=<Optional:None>, extern_name=<Optional:None>)
+.. py:function:: update_user(apiuser, userid, username=<Optional:None>, email=<Optional:None>, password=<Optional:None>, firstname=<Optional:None>, lastname=<Optional:None>, description=<Optional:None>, active=<Optional:None>, admin=<Optional:None>, extern_type=<Optional:None>, extern_name=<Optional:None>)
 
    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.