diff --git a/doc/api/README.md b/doc/api/README.md
index ee24449343a4aa5e6f66e3ba391460b0a701889d..517a9fae6f60054985f7e0d73c4bfcfb58ae3aa7 100644
--- a/doc/api/README.md
+++ b/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)
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 9082cbb50ba1cefe7a47e62efbf0f3d64913e760..ef37940faf014df5a72db693ce8870b74eb30fe5 100644
--- a/doc/api/issues.md
+++ b/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": "",
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index dae12f03ef5e9682bfcc1b5952162cdf273cd645..2ddaea5a584b04db72f5cf0bf86dde22c2ce2433 100644
--- a/doc/api/merge_requests.md
+++ b/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,
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 2bdca68351bd6bd7208a1402d8e72fd6f1f03441..e899e28d219591cf51ca55b6685af9c4196327a8 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -10,6 +10,7 @@ GET /projects/:id/milestones
 [
   {
     "id":12,
+    "iid":3,
     "project_id":16,
     "title":"10.0",
     "description":"Version",
diff --git a/lib/api/entities.rb b/lib/api/entities.rb
index b4771eecc7f713f4a7ca2a422271655073e96dc5..429083d75be1dd20106d9453a1d377eb7c94e4c4 100644
--- a/lib/api/entities.rb
+++ b/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
diff --git a/spec/requests/api/issues_spec.rb b/spec/requests/api/issues_spec.rb
index a97d6a282a9bf55195ef6920146280b395f513a1..e9422cd26439845f5d8037e4d0200e30c98a5cbf 100644
--- a/spec/requests/api/issues_spec.rb
+++ b/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
diff --git a/spec/requests/api/merge_requests_spec.rb b/spec/requests/api/merge_requests_spec.rb
index 2f11f562aa1c4898bf11071891ced6cc2553dc03..f31b4da90cd320f9e2273e1c7ada14eca894e72e 100644
--- a/spec/requests/api/merge_requests_spec.rb
+++ b/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
diff --git a/spec/requests/api/milestones_spec.rb b/spec/requests/api/milestones_spec.rb
index 246fe262ce86a21fb73e74a6786548a9a06dd259..e79ce083a463942564bada603055b961d8f87ae8 100644
--- a/spec/requests/api/milestones_spec.rb
+++ b/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