Merge branch 'feature/api_iids' of /home/git/repositories/gitlab/gitlabhq

doc/api/README.md

@@ -96,13 +96,30 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "h
 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects"
 ```
 
-#### Pagination
+## Pagination
 
 When listing resources you can pass the following parameters:
 
 + `page` (default: `1`) - page number
 + `per_page` (default: `20`, max: `100`) - number of items to list per page
 
+## id vs iid
+
+When you work with API you may notice two similar fields in api entites: id and iid. 
+The main difference between them is scope. Example: 
+
+Issue 
+  id: 46
+  iid: 5
+
+* id - is uniq across all Issues table. It used for any api calls. 
+* iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid. 
+
+So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`
+But when you want to create a link to web page - use  `http:://host/project/issues/:iid.json`
+
+
+
 ## Contents
 
 + [Users](users.md)

doc/api/issues.md

@@ -11,6 +11,7 @@ GET /issues
 [
   {
     "id": 43,
+    "iid": 3,
     "project_id": 8,
     "title": "4xx/5xx pages",
     "description": "",
@@ -31,6 +32,7 @@ GET /issues
   },
   {
     "id": 42,
+    "iid": 4,
     "project_id": 8,
     "title": "Add user settings",
     "description": "",
@@ -100,6 +102,7 @@ Parameters:
 ```json
 {
   "id": 42,
+  "iid": 3,
   "project_id": 8,
   "title": "Add user settings",
   "description": "",

doc/api/merge_requests.md

@@ -15,6 +15,7 @@ Parameters:
 [
     {
         "id":1,
+        "iid":1,
         "target_branch":"master",
         "source_branch":"test1",
         "project_id":3,
@@ -59,6 +60,7 @@ Parameters:
 ```json
 {
     "id":1,
+    "iid":1,
     "target_branch":"master",
     "source_branch":"test1",
     "project_id":3,

doc/api/milestones.md

@@ -10,6 +10,7 @@ GET /projects/:id/milestones
 [
   {
     "id":12,
+    "iid":3,
     "project_id":16,
     "title":"10.0",
     "description":"Version",

lib/api/entities.rb

@@ -91,15 +91,16 @@ module API
       expose :expires_at, :updated_at, :created_at
     end
 
-    class Milestone < Grape::Entity
-      expose :id
-      expose (:project_id) {|milestone| milestone.project.id}
+    class ProjectEntity < Grape::Entity
+      expose :id, :iid
+      expose (:project_id) { |entity| entity.project.id }
+    end
+
+    class Milestone < ProjectEntity
       expose :title, :description, :due_date, :state, :updated_at, :created_at
     end
 
-    class Issue < Grape::Entity
-      expose :id
-      expose (:project_id) {|issue| issue.project.id}
+    class Issue < ProjectEntity
       expose :title, :description
       expose :label_list, as: :labels
       expose :milestone, using: Entities::Milestone
@@ -107,14 +108,14 @@ module API
       expose :state, :updated_at, :created_at
     end
 
-    class SSHKey < Grape::Entity
-      expose :id, :title, :key, :created_at
+    class MergeRequest < ProjectEntity
+      expose :target_branch, :source_branch, :title, :state, :upvotes, :downvotes
+      expose :author, :assignee, using: Entities::UserBasic
+      expose :source_project_id, :target_project_id
     end
 
-    class MergeRequest < Grape::Entity
-      expose :id, :target_branch, :source_branch, :title, :state, :upvotes, :downvotes
-      expose :target_project_id, as: :project_id
-      expose :author, :assignee, using: Entities::UserBasic
+    class SSHKey < Grape::Entity
+      expose :id, :title, :key, :created_at
     end
 
     class Note < Grape::Entity

spec/requests/api/issues_spec.rb

@@ -42,6 +42,7 @@ describe API::API do
       get api("/projects/#{project.id}/issues/#{issue.id}", user)
       response.status.should == 200
       json_response['title'].should == issue.title
+      json_response['iid'].should == issue.iid
     end
 
     it "should return 404 if issue id not found" do

spec/requests/api/merge_requests_spec.rb

@@ -34,6 +34,7 @@ describe API::API do
       get api("/projects/#{project.id}/merge_request/#{merge_request.id}", user)
       response.status.should == 200
       json_response['title'].should == merge_request.title
+      json_response['iid'].should == merge_request.iid
     end
 
     it "should return a 404 error if merge_request_id not found" do

spec/requests/api/milestones_spec.rb

@@ -30,6 +30,7 @@ describe API::API do
       get api("/projects/#{project.id}/milestones/#{milestone.id}", user)
       response.status.should == 200
       json_response['title'].should == milestone.title
+      json_response['iid'].should == milestone.iid
     end
 
     it "should return 401 error if user not authenticated" do