diff --git a/doc/api.rst b/doc/api.rst index 57eb697..265345d 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -19,16 +19,16 @@ API token generated in the project setting page. Anyone with the token can access the APIs on your behalf, so please be sure to keep it private and safe. -Request Encode -~~~~~~~~~~~~~~ +Request Encoding +~~~~~~~~~~~~~~~~ The payload of POST and GET requests is encoded as ``application/x-www-form-urlencoded``. This is an example URL of a GET request: ``https://pagure.io/api/0/test/issues?status=Open&tags=Pagure&tags=Enhancement`` -Return Type -~~~~~~~~~~~ +Return Encoding +~~~~~~~~~~~~~~~ The return value of API calls is ``application/json``. This is an example of return value: @@ -62,620 +62,3 @@ example of return value: } ] } - -Project -------- - -Project issue tags -~~~~~~~~~~~~~~~~~~ - -List the tags made on the project's issues. - -:: - - GET /api/0//tags - -:: - - GET /api/0/fork///tags - -Parameters -^^^^^^^^^^ - -+---------------+----------+--------------------------------------------+ -| Key | Type | Description | -+===============+==========+============================================+ -| ``pattern`` | string | Filters the starting letters of the tags | -+---------------+----------+--------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "tags": ["tag1", "tag2"] - } - -Project git tags -~~~~~~~~~~~~~~~~ - -List the tags made on the project Git repository. - -:: - - GET /api/0//git/tags - -:: - - GET /api/0/fork///git/tags - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "tags": ["this-is-a-tag"] - } - -Create a new issue -~~~~~~~~~~~~~~~~~~ - -Open a new issue on a project. - -:: - - POST /api/0//new_issue - -:: - - POST /api/0/fork///new_issue - -Input -^^^^^ - -+---------------+-----------+--------------------------------------------------------------+ -| Key | Type | Description | -+===============+===========+==============================================================+ -| ``title`` | string | **Required**. The title of the issue | -+---------------+-----------+--------------------------------------------------------------+ -| ``private`` | boolean | Include this key if you want a private issue to be created | -+---------------+-----------+--------------------------------------------------------------+ -| ``content`` | string | **Required**. The description of the issue | -+---------------+-----------+--------------------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Issue created" - } - -List project's issues -~~~~~~~~~~~~~~~~~~~~~ - -List issues of a project. - -:: - - GET /api/0//issues - -:: - - GET /api/0/fork///issues - -Parameters -^^^^^^^^^^ - -+----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ -| Key | Type | Description | -+================+==========+================================================================================================================================+ -| ``status`` | string | Filters the status of issues. Default: ``Open`` | -+----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ -| ``tags`` | string | A list of tags you wish to filter. If you want to filter for issues not having a tag, add an exclamation mark in front of it | -+----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ -| ``assignee`` | string | Filter the issues by assignee | -+----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ -| ``author`` | string | Filter the issues by creator | -+----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "args": { - "assignee": null, - "author": null, - "status": "Closed", - "tags": [ - "0.1" - ] - }, - "issues": [ - { - "assignee": null, - "blocks": [], - "comments": [], - "content": "asd", - "date_created": "1427442217", - "depends": [], - "id": 4, - "private": false, - "status": "Fixed", - "tags": [ - "0.1" - ], - "title": "bug", - "user": { - "fullname": "PY.C", - "name": "pingou" - } - } - ] - } - -Get information of a single issue -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Retrieve information of a specific issue. - -:: - - GET /api/0//issue/ - -:: - - GET /api/0/fork///issue/ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "assignee": None, - "blocks": [], - "comments": [], - "content": "This issue needs attention", - "date_created": "1431414800", - "depends": [], - "id": 1, - "private": False, - "status": "Open", - "tags": [], - "title": "test issue", - "user": { - "fullname": "PY C", - "name": "pingou" - } - } - -Comment on an issue -~~~~~~~~~~~~~~~~~~~ - -Add a comment to an issue. - -:: - - POST /api/0//issue//comment - -:: - - POST /api/0/fork///issue//comment - -Input -^^^^^ - -+---------------+----------+-------------------------------------------------+ -| Key | Type | Description | -+===============+==========+=================================================+ -| ``comment`` | string | **Required**. The comment to add to the issue | -+---------------+----------+-------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Comment added" - } - -Change status of issue -~~~~~~~~~~~~~~~~~~~~~~ - -Change the status of an issue. - -:: - - POST /api/0//issue//status - -:: - - POST /api/0/fork///issue//status - -Input -^^^^^ - -+--------------+----------+---------------------------------------------+ -| Key | Type | Description | -+==============+==========+=============================================+ -| ``status`` | string | **Required**. The new status of the issue | -+--------------+----------+---------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Successfully edited issue #1" - } - -List project's pull requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Retrieve pull requests of a project. - -:: - - GET /api/0//pull-requests - -:: - - GET /api/0/fork///pull-requests - -Parameters -^^^^^^^^^^ - -+----------------+-----------+--------------------------------------------------------------------------------+ -| Key | Type | Description | -+================+===========+================================================================================+ -| ``status`` | boolean | Filter the status of pull requests. Default: ``True`` (opened pull requests) | -+----------------+-----------+--------------------------------------------------------------------------------+ -| ``assignee`` | string | Filter the assignee of pull requests | -+----------------+-----------+--------------------------------------------------------------------------------+ -| ``author`` | string | Filter the author of pull requests | -+----------------+-----------+--------------------------------------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "args": { - "assignee": null, - "author": null, - "status": true - }, - "requests": [ - { - "assignee": null, - "branch": "master", - "branch_from": "master", - "comments": [], - "commit_start": null, - "commit_stop": null, - "date_created": "1431414800", - "id": 1, - "project": { - "date_created": "1431414800", - "description": "test project #1", - "id": 1, - "name": "test", - "parent": null, - "user": { - "fullname": "PY C", - "name": "pingou" - } - }, - "repo_from": { - "date_created": "1431414800", - "description": "test project #1", - "id": 1, - "name": "test", - "parent": null, - "user": { - "fullname": "PY C", - "name": "pingou" - } - }, - "status": true, - "title": "test pull-request", - "uid": "1431414800", - "user": { - "fullname": "PY C", - "name": "pingou" - } - } - ] - } - -Get information of a single pull request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Retrieve information of a specific pull request. - -:: - - GET /api/0//pull-request/ - -:: - - GET /api/0/fork///pull-request/ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "assignee": null, - "branch": "master", - "branch_from": "master", - "comments": [], - "commit_start": null, - "commit_stop": null, - "date_created": "1431414800", - "id": 1, - "project": { - "date_created": "1431414800", - "description": "test project #1", - "id": 1, - "name": "test", - "parent": null, - "user": { - "fullname": "PY C", - "name": "pingou" - } - }, - "repo_from": { - "date_created": "1431414800", - "description": "test project #1", - "id": 1, - "name": "test", - "parent": null, - "user": { - "fullname": "PY C", - "name": "pingou" - } - }, - "status": true, - "title": "test pull-request", - "uid": "1431414800", - "user": { - "fullname": "PY C", - "name": "pingou" - } - } - -Merge pull request -~~~~~~~~~~~~~~~~~~ - -Instruct Paugre to merge a pull request. - -:: - - POST /api/0//pull-request//merge - -:: - - POST /api/0/fork///pull-request//merge - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Changes merged!" - } - -Close pull request -~~~~~~~~~~~~~~~~~~ - -Instruct Pagure to close a pull request. - -:: - - POST /api/0//pull-request//close - -:: - - POST /api/0/fork///pull-request//close - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Pull-request closed!" - } - -Comment on pull request -~~~~~~~~~~~~~~~~~~~~~~~ - -Add comment to a pull request. - -:: - - POST /api/0//pull-request//comment - -:: - - POST /api/0/fork///pull-request//comment - -Input -^^^^^ - -+----------------+----------+----------------------------------------------------------------------------+ -| Key | Type | Description | -+================+==========+============================================================================+ -| ``comment`` | string | **Required**. The comment to add to the pull request | -+----------------+----------+----------------------------------------------------------------------------+ -| ``commit`` | string | The hash of the specific commit you wish to comment on | -+----------------+----------+----------------------------------------------------------------------------+ -| ``filename`` | string | The filename of the specific file you wish to comment on | -+----------------+----------+----------------------------------------------------------------------------+ -| ``row`` | int | Used in combination with filename to comment on a specific row of a file | -+----------------+----------+----------------------------------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Comment added" - } - -Flag pull request -~~~~~~~~~~~~~~~~~ - -Add or edit flags on a pull-request. - -:: - - POST /api/0//pull-request//flag - -:: - - POST /api/0/fork///pull-request//flag - -Input -^^^^^ - -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Key | Type | Description | -+================+==========+==========================================================================================================================================================================================================================================================+ -| ``username`` | string | **Required**. The name of the application to be presented to users on the pull request page | -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``percent`` | int | **Required**. A percentage of completion compared to the goal. The percentage also determine the background color of the flag on the pull-request page | -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``comment`` | string | **Required**. A short message summarizing the presented results | -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``url`` | string | **Required**. A URL to the result of this flag | -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``uid`` | string | A unique identifier used to identify a flag on a pull-request. If the provided UID matches an existing one, then the API call will update the existing one rather than create a new one. Maximum Length: 32 characters. Default: an auto generated UID | -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``commit`` | string | The hash of the commit you use | -+----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "message": "Flag added" - } - -:: - - { - "message": "Flag updated" - } - -Users ------ - -List users -~~~~~~~~~~ - -Retrieve users that have logged into the Paugre instance. - -:: - - GET /api/0/users - -Parameters -^^^^^^^^^^ - -+---------------+----------+-------------------------------------------------+ -| Key | Type | Description | -+===============+==========+=================================================+ -| ``pattern`` | string | Filters the starting letters of the usernames | -+---------------+----------+-------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "users": ["user1", "user2"] - } - -List groups -~~~~~~~~~~~ - -Retrieve groups on this Pagure instance. - -:: - - GET /api/0/groups - -Parameters -^^^^^^^^^^ - -+---------------+----------+---------------------------------------------------+ -| Key | Type | Description | -+===============+==========+===================================================+ -| ``pattern`` | string | Filters the starting letters of the group names | -+---------------+----------+---------------------------------------------------+ - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "groups": ["group1", "group2"] - } - -Extras ------- - -API version -~~~~~~~~~~~ - -Get the current API version. - -:: - - GET /api/0/version - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - "version": "1" - } - -Error codes -~~~~~~~~~~~ - -Get a dictionary of all error codes. - -:: - - GET /api/0/error_codes - -Sample response -^^^^^^^^^^^^^^^ - -:: - - { - ENOCODE: 'Variable message describing the issue', - ENOPROJECT: 'Project not found', - } diff --git a/pagure/api/__init__.py b/pagure/api/__init__.py index c9c3f68..88ca04b 100644 --- a/pagure/api/__init__.py +++ b/pagure/api/__init__.py @@ -178,15 +178,14 @@ def api_version(): ''' API Version ----------- - Display the most recent api version. + Get the current API version. :: - /api/0/version + GET /api/0/version - Accepts GET queries only. - - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -204,16 +203,23 @@ def api_users(): ''' List users ----------- - Returns the list of all users that have logged into this pagure instances. - This can then be used as input for autocompletion in some forms/fields. + Retrieve users that have logged into the Paugre instance. :: - /api/0/users + GET /api/0/users + + Parameters + ^^^^^^^^^^ - Accepts GET queries only. + +---------------+----------+-------------------------------------------------+ + | Key | Type | Description | + +===============+==========+=================================================+ + | ``pattern`` | string | Filters the starting letters of the usernames | + +---------------+----------+-------------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -245,18 +251,27 @@ def api_project_tags(repo, username=None): ''' List all the tags of a project ------------------------------ - Returns the list of all tags assigned to the tickets of the specified - project. + List the tags made on the project's issues. :: - /api/0//tags + GET /api/0//tags + + :: - /api/0/fork///tags + GET /api/0/fork///tags - Accepts GET queries only. + Parameters + ^^^^^^^^^^ - Sample response: + +---------------+----------+--------------------------------------------+ + | Key | Type | Description | + +===============+==========+============================================+ + | ``pattern`` | string | Filters the starting letters of the tags | + +---------------+----------+--------------------------------------------+ + + Sample response + ^^^^^^^^^^^^^^^ :: @@ -293,16 +308,23 @@ def api_groups(): ''' List groups ----------- - Returns the list of all groups present on this pagure instance - This can then be used as input for autocompletion in some forms/fields. + Retrieve groups on this Pagure instance. :: - /api/0/groups + GET /api/0/groups + + Parameters + ^^^^^^^^^^ - Accepts GET queries only. + +---------------+----------+---------------------------------------------------+ + | Key | Type | Description | + +===============+==========+===================================================+ + | ``pattern`` | string | Filters the starting letters of the group names | + +---------------+----------+---------------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -332,15 +354,14 @@ def api_error_codes(): ''' Error codes ------------ - Returns the dictionary (hash) of all the error codes present in the API + Get a dictionary (hash) of all error codes. :: - /api/0/error_codes - - Accepts GET queries only. + GET /api/0/error_codes - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: diff --git a/pagure/api/fork.py b/pagure/api/fork.py index 5c81001..c4de7c2 100644 --- a/pagure/api/fork.py +++ b/pagure/api/fork.py @@ -26,25 +26,31 @@ def api_pull_request_views(repo, username=None): """ List project's Pull-Requests ---------------------------- - This endpoint can be used to retrieve the pull-requests of the specified - project + Retrieve pull requests of a project. :: - /api/0//pull-requests + GET /api/0//pull-requests - /api/0/fork///pull-requests + :: + + GET /api/0/fork///pull-requests - Accepts GET queries only. + Parameters + ^^^^^^^^^^ - :kwarg status: The status of the pull-requests to return, default to - 'True' (ie: opened pull-requests) - :kwarg assignee: Filters the pull-requests returned by the user they - are assigned to - :kwarg author: Filters the pull-requests returned by the user that - opened the pull-request + +----------------+-----------+--------------------------------------------------------------------------------+ + | Key | Type | Description | + +================+===========+================================================================================+ + | ``status`` | boolean | Filter the status of pull requests. Default: ``True`` (opened pull requests) | + +----------------+-----------+--------------------------------------------------------------------------------+ + | ``assignee`` | string | Filter the assignee of pull requests | + +----------------+-----------+--------------------------------------------------------------------------------+ + | ``author`` | string | Filter the author of pull requests | + +----------------+-----------+--------------------------------------------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -148,18 +154,18 @@ def api_pull_request_view(repo, requestid, username=None): """ Pull-request information ------------------------ - This endpoint can be used to retrieve information about a specific - pull-request + Retrieve information of a specific pull request. :: - /api/0//pull-request/ + GET /api/0//pull-request/ - /api/0/fork///pull-request/ + :: - Accepts GET queries only. + GET /api/0/fork///pull-request/ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -233,17 +239,18 @@ def api_pull_request_merge(repo, requestid, username=None): """ Merge a pull-request -------------------- - This endpoint can be used to instruct pagure to merge a pull-request + Instruct Paugre to merge a pull request. :: - /api/0//pull-request//merge + POST /api/0//pull-request//merge - /api/0/fork///pull-request//merge + :: - Accepts POST queries only. + POST /api/0/fork///pull-request//merge - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -310,18 +317,18 @@ def api_pull_request_close(repo, requestid, username=None): """ Close a pull-request -------------------- - This endpoint can be used to instruct pagure to close a pull-request - without merging it + Instruct Pagure to close a pull request. :: - /api/0//pull-request//close + POST /api/0//pull-request//close - /api/0/fork///pull-request//close + :: - Accepts POST queries only. + POST /api/0/fork///pull-request//close - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -379,23 +386,33 @@ def api_pull_request_add_comment(repo, requestid, username=None): """ Comment on a pull-request ------------------------- - This endpoint can be used to comment on a pull-request + Add comment to a pull request. :: - /api/0//pull-request//comment + POST /api/0//pull-request//comment + + :: - /api/0/fork///pull-request//comment + POST /api/0/fork///pull-request//comment - Accepts POST queries only. + Input + ^^^^^ - :arg comment: The comment to add to the pull-request - :kwarg commit: The hash of the commit you wish to comment on - :kwarg filename: The name of the file you wish to comment on - :kwarg row: Used in combination with filename to comment on a specific - row of a file of the pull-request + +----------------+----------+----------------------------------------------------------------------------+ + | Key | Type | Description | + +================+==========+============================================================================+ + | ``comment`` | string | **Required**. The comment to add to the pull request | + +----------------+----------+----------------------------------------------------------------------------+ + | ``commit`` | string | The hash of the specific commit you wish to comment on | + +----------------+----------+----------------------------------------------------------------------------+ + | ``filename`` | string | The filename of the specific file you wish to comment on | + +----------------+----------+----------------------------------------------------------------------------+ + | ``row`` | int | Used in combination with filename to comment on a specific row of a file | + +----------------+----------+----------------------------------------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -468,36 +485,37 @@ def api_pull_request_add_flag(repo, requestid, username=None): """ Flag a pull-request ------------------- - This endpoint can be used to add or edit flags on a pull-request + Add or edit flags on a pull-request. :: - /api/0//pull-request//flag - - /api/0/fork///pull-request//flag - - Accepts POST queries only. - - :arg username: The name of the application as it should be presented to - the user on the pull-request page (for example: jenkins, travis-ci, - pep8bot...) - :arg percent: A percentage of completion compared to the goal, it can - be a percentage of coverage, a 0 vs 100 for fail vs pass. - The percentage also determine the background color of the flag on - the pull-request page. - :arg comment: Small information message summarizing the results presented - here. - :arg url: An URL to the link the flag to. This can be the URL of a - specific build or test, or the URL of the application itself, but - there must be one. - :kwarg uid: An unique identifier used to identify a flag on a pull-request - if you do not provide it, one will be automatically generated. - If you do provide it, sending a second request with the same UID will - update the flag instead of adding a new one. - Maximum length: ``32`` characters. - :kwarg commit: The hash of the commit you use - - Sample response: + POST /api/0//pull-request//flag + + :: + + POST /api/0/fork///pull-request//flag + + Input + ^^^^^ + + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Key | Type | Description | + +================+==========+==========================================================================================================================================================================================================================================================+ + | ``username`` | string | **Required**. The name of the application to be presented to users on the pull request page | + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``percent`` | int | **Required**. A percentage of completion compared to the goal. The percentage also determine the background color of the flag on the pull-request page | + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``comment`` | string | **Required**. A short message summarizing the presented results | + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``url`` | string | **Required**. A URL to the result of this flag | + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``uid`` | string | A unique identifier used to identify a flag on a pull-request. If the provided UID matches an existing one, then the API call will update the existing one rather than create a new one. Maximum Length: 32 characters. Default: an auto generated UID | + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``commit`` | string | The hash of the commit you use | + +----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + Sample response + ^^^^^^^^^^^^^^^ :: @@ -505,6 +523,12 @@ def api_pull_request_add_flag(repo, requestid, username=None): "message": "Flag added" } + :: + + { + "message": "Flag updated" + } + """ repo = pagure.lib.get_project(SESSION, repo, user=username) output = {} diff --git a/pagure/api/issue.py b/pagure/api/issue.py index ccae83b..8bd031f 100644 --- a/pagure/api/issue.py +++ b/pagure/api/issue.py @@ -29,22 +29,31 @@ def api_new_issue(repo, username=None): """ Create a new issue ------------------ - This endpoint can be used to open an issue on a project + Open a new issue on a project. :: - /api/0//new_issue + POST /api/0//new_issue - /api/0/fork///new_issue + :: + + POST /api/0/fork///new_issue - Accepts POST queries only. + Input + ^^^^^ - :arg title: The title of the issue/ticket to create - :arg issue_content: The content of the issue to create (ie the description of - the problem) - :arg private: A boolean specifying whether this issue is private or not + +---------------+-----------+--------------------------------------------------------------+ + | Key | Type | Description | + +===============+===========+==============================================================+ + | ``title`` | string | **Required**. The title of the issue | + +---------------+-----------+--------------------------------------------------------------+ + | ``private`` | boolean | Include this key if you want a private issue to be created | + +---------------+-----------+--------------------------------------------------------------+ + | ``content`` | string | **Required**. The description of the issue | + +---------------+-----------+--------------------------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: @@ -131,89 +140,35 @@ def api_view_issues(repo, username=None): """ List project's issues --------------------- - This endpoint can be used to retrieve the list of all issues of the - specified project + List issues of a project. :: - /api/0//issues + GET /api/0//issues - /api/0/fork///issues + :: - Accepts GET queries only. + GET /api/0/fork///issues - :kwarg status: The status of the issues to return, default to 'Open' - :kwarg tags: One or more tags to filter the issues returned. - If you want to wish to filter for issues not having a specific tag - you can mark the tag with an exclamation mark in front of it, for - example to get all the issues not tagged as ``easyfix`` you can - filter using the tag ``!easyfix`` - :kwarg assignee: Filters the issues returned by the user they are - assigned to - :kwarg author: Filters the issues returned by the user that opened the - issue + Parameters + ^^^^^^^^^^ - Sample response: + +----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ + | Key | Type | Description | + +================+==========+================================================================================================================================+ + | ``status`` | string | Filters the status of issues. Default: ``Open`` | + +----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ + | ``tags`` | string | A list of tags you wish to filter. If you want to filter for issues not having a tag, add an exclamation mark in front of it | + +----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ + | ``assignee`` | string | Filter the issues by assignee | + +----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ + | ``author`` | string | Filter the issues by creator | + +----------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ - :: + Sample response + ^^^^^^^^^^^^^^^ - { - "args": { - "assignee": null, - "author": null, - "status": null, - "tags": [] - }, - "issues": [ - { - "assignee": null, - "blocks": [], - "comments": [ - { - "comment": "bing", - "date_created": "1427441560", - "id": 379, - "parent": null, - "user": { - "fullname": "PY.C", - "name": "pingou" - } - } - ], - "content": "bar", - "date_created": "1427441555", - "depends": [], - "id": 1, - "private": false, - "status": "Open", - "tags": [], - "title": "foo", - "user": { - "fullname": "PY.C", - "name": "pingou" - } - }, - { - "assignee": null, - "blocks": [], - "comments": [], - "content": "report", - "date_created": "1427442076", - "depends": [], - "id": 2, - "private": false, - "status": "Open", - "tags": [], - "title": "bug", - "user": { - "fullname": "PY.C", - "name": "pingou" - } - } - ] - } - - Second example: + :: { "args": { @@ -322,30 +277,30 @@ def api_view_issue(repo, issueid, username=None): """ Issue information ----------------- - This endpoint can be used to retrieve information about a specific - issue/ticket + Retrieve information of a specific issue. :: - /api/0//issue/ + GET /api/0//issue/ - /api/0/fork///issue/ + :: - Accepts GET queries only. + GET /api/0/fork///issue/ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: { - "assignee": null, + "assignee": None, "blocks": [], "comments": [], "content": "This issue needs attention", "date_created": "1431414800", "depends": [], "id": 1, - "private": false, + "private": False, "status": "Open", "tags": [], "title": "test issue", @@ -394,24 +349,32 @@ def api_change_status_issue(repo, issueid, username=None): """ Change issue status ------------------- - This endpoint can be used to change the status of an issue + Change the status of an issue. :: - /api/0//issue//status + POST /api/0//issue//status + + :: - /api/0/fork///issue//status + POST /api/0/fork///issue//status - Accepts POST queries only. + Input + ^^^^^ - :arg status: The new status of the specified issue + +--------------+----------+---------------------------------------------+ + | Key | Type | Description | + +==============+==========+=============================================+ + | ``status`` | string | **Required**. The new status of the issue | + +--------------+----------+---------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: { - "message": "Edited successfully issue #1" + "message": "Successfully edited issue #1" } """ @@ -479,19 +442,27 @@ def api_comment_issue(repo, issueid, username=None): """ Comment to an issue ------------------- - This endpoint can be used to add a comment to an issue + Add a comment to an issue. :: - /api/0//issue//comment + POST /api/0//issue//comment + + :: - /api/0/fork///issue//comment + POST /api/0/fork///issue//comment - Accepts POST queries only. + Input + ^^^^^ - :arg comment: The comment to add to the specified issue + +---------------+----------+-------------------------------------------------+ + | Key | Type | Description | + +===============+==========+=================================================+ + | ``comment`` | string | **Required**. The comment to add to the issue | + +---------------+----------+-------------------------------------------------+ - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: diff --git a/pagure/api/project.py b/pagure/api/project.py index 9d03a12..c3eab15 100644 --- a/pagure/api/project.py +++ b/pagure/api/project.py @@ -24,21 +24,23 @@ def api_git_tags(repo, username=None): """ Project git tags ---------------- - Returns the list of tags made on the git repo of the project. + List the tags made on the project Git repository. :: - /api/0//git/tags - /api/0/fork///git/tags + GET /api/0//git/tags - Accepts GET queries only. + :: + + GET /api/0/fork///git/tags - Sample response: + Sample response + ^^^^^^^^^^^^^^^ :: { - "tags": ["2.5.4", "2.5.5"], + "tags": ["this-is-a-tag"] } """ diff --git a/pagure/api/user.py b/pagure/api/user.py index d6841be..65c8664 100644 --- a/pagure/api/user.py +++ b/pagure/api/user.py @@ -27,12 +27,14 @@ def api_view_user(username): :: - /api/0/user/ - /api/0/user/ralph + GET /api/0/user/ - Accepts GET queries only. + :: + + GET /api/0/user/ralph - Sample response: + Sample response + ^^^^^^^^^^^^^^^ ::