From e96d77d3dbd789981b8e85e7afba9a5908d79483 Mon Sep 17 00:00:00 2001
From: Sebastian Ziebell <sebastian.ziebell@asquera.de>
Date: Wed, 27 Feb 2013 14:36:20 +0100
Subject: [PATCH] API: issues documentation and API functions updated
The issues documentation is updated with infos to status codes and the deprecated `DELETE` function and
how to close an issue. A few more tests added to check status codes of API functions.
---
doc/api/issues.md | 67 ++++++++++++++++++++++++++++----
lib/api/issues.rb | 1 +
spec/requests/api/issues_spec.rb | 16 ++++++++
3 files changed, 77 insertions(+), 7 deletions(-)
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 0383b676073..b782cec975b 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,6 +1,7 @@
## List issues
-Get all issues created by authenticed user.
+Get all issues created by authenticed user. This function takes pagination parameters
+`page` and `per_page` to get a list of issues.
```
GET /issues
@@ -68,9 +69,18 @@ GET /issues
]
```
+Return values:
+
++ `200 Ok` on success and the list of issues
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something fails
+
+
+
## List project issues
-Get a list of project issues.
+Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
+to return the list of project issues.
```
GET /projects/:id/issues
@@ -80,9 +90,16 @@ Parameters:
+ `id` (required) - The ID of a project
+Return values:
+
++ `200 Ok` on success and the list of project issues
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
## Single issue
-Get a project issue.
+Gets a single project issue.
```
GET /projects/:id/issues/:issue_id
@@ -133,9 +150,16 @@ Parameters:
}
```
+Return values:
+
++ `200 Ok` on success and the list of project issues
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or issue ID not found
+
+
## New issue
-Create a new project issue.
+Creates a new project issue.
```
POST /projects/:id/issues
@@ -150,11 +174,17 @@ Parameters:
+ `milestone_id` (optional) - The ID of a milestone to assign issue
+ `labels` (optional) - Comma-separated label names for an issue
-Will return created issue with status `201 Created` on success, or `404 Not found` on fail.
+Return values:
+
++ `201 Created` on success and the newly created project issue
++ `400 Bad Request` if the required attribute title is not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
## Edit issue
-Update an existing project issue.
+Updates an existing project issue. This function is also used to mark an issue as closed.
```
PUT /projects/:id/issues/:issue_id
@@ -171,5 +201,28 @@ Parameters:
+ `labels` (optional) - Comma-separated label names for an issue
+ `closed` (optional) - The state of an issue (0 = false, 1 = true)
-Will return updated issue with status `200 OK` on success, or `404 Not found` on fail.
+Return values:
+
++ `200 Ok` on success and the update project issue
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or issue ID not found
+
+
+## Delete existing issue (**Deprecated**)
+
+The function is deprecated and returns a `405 Method Not Allowed`
+error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with
+parameter `closed` set to 1.
+
+```
+DELETE /projects/:id/issues/:issue_id
+```
+
+Parameters:
+
++ `id` (required) - The project ID
++ `issue_id` (required) - The ID of the issue
+
+Return values:
++ `405 Method Not Allowed` is always returned, because the function is deprecated
diff --git a/lib/api/issues.rb b/lib/api/issues.rb
index 70bbf47e72c..da966fc0399 100644
--- a/lib/api/issues.rb
+++ b/lib/api/issues.rb
@@ -48,6 +48,7 @@ module Gitlab
# Example Request:
# POST /projects/:id/issues
post ":id/issues" do
+ bad_request!(:title) unless params[:title].present?
attrs = attributes_for_keys [:title, :description, :assignee_id, :milestone_id]
attrs[:label_list] = params[:labels] if params[:labels].present?
@issue = user_project.issues.new attrs
diff --git a/spec/requests/api/issues_spec.rb b/spec/requests/api/issues_spec.rb
index 630ac0f820a..ecf0bdb7084 100644
--- a/spec/requests/api/issues_spec.rb
+++ b/spec/requests/api/issues_spec.rb
@@ -41,6 +41,11 @@ describe Gitlab::API do
response.status.should == 200
json_response['title'].should == issue.title
end
+
+ it "should return 404 if issue id not found" do
+ get api("/projects/#{project.id}/issues/54321", user)
+ response.status.should == 404
+ end
end
describe "POST /projects/:id/issues" do
@@ -52,6 +57,11 @@ describe Gitlab::API do
json_response['description'].should be_nil
json_response['labels'].should == ['label', 'label2']
end
+
+ it "should return a 400 bad request if title not given" do
+ post api("/projects/#{project.id}/issues", user), labels: 'label, label2'
+ response.status.should == 400
+ end
end
describe "PUT /projects/:id/issues/:issue_id to update only title" do
@@ -62,6 +72,12 @@ describe Gitlab::API do
json_response['title'].should == 'updated title'
end
+
+ it "should return 404 error if issue id not found" do
+ put api("/projects/#{project.id}/issues/44444", user),
+ title: 'updated title'
+ response.status.should == 404
+ end
end
describe "PUT /projects/:id/issues/:issue_id to update state and label" do
--
GitLab